OpenAI Codex 会从用户级 ~/.codex/config.toml、项目级 .codex/config.toml 和 CLI 覆盖项里合并配置，优先级最高的是 CLI flags 与 --config。如果项目被标记为 untrusted，Codex 会跳过项目 .codex/ 层；你可以在 IDE 扩展里从齿轮菜单直接打开 config.toml，并用 codex --enable feature_name 打开可选功能。
OpenAI Codex 配置基础：config.toml 优先级与常用选项
OpenAI Codex 的配置会从多个位置读取。用户默认值放在 ~/.codex/config.toml，项目或子目录的覆盖值放在 .codex/config.toml。只有在你信任该项目时，Codex 才会加载项目里的 .codex/ 层。
Codex 配置文件位置
Codex 的用户级配置保存在 ~/.codex/config.toml。如果你想让某个仓库或子目录使用单独的设置，就在该代码库里添加 .codex/config.toml。
在 Codex IDE extension 里打开配置文件的方法是：点击右上角齿轮图标，然后选择 Codex Settings > Open config.toml。
CLI 和 IDE extension 共用同一套配置层级。它们可以用来：
- 设置默认模型和 provider。
- 配置 approval policies 和 sandbox settings。
- 配置 MCP servers。
配置优先级
Codex 按下面的顺序解析配置，越靠前优先级越高：
- CLI flags 和
--config覆盖 - Profile 值（来自
--profile <name>） - 项目配置文件：
.codex/config.toml，按项目根目录到当前工作目录排序，越近越优先；仅限受信任项目 - 用户配置：
~/.codex/config.toml - 系统配置（如果存在）：Unix 上的
/etc/codex/config.toml - 内置默认值
这套顺序适合这样分工：顶层放共享默认值，profile 只放那些需要差异化的值。
如果你把项目标记为不受信任，Codex 会跳过项目范围的 .codex/ 层，包括项目本地配置、hooks 和 rules。用户配置和系统配置仍会加载，包括用户级或全局的 hooks 和 rules。
关于一次性覆盖参数的 -c / --config 用法，包括 TOML 引号规则，见 Advanced Config。
在受管机器上，你的组织也可能通过 requirements.toml 强制约束某些配置，例如禁止 approval_policy = "never" 或 sandbox_mode = "danger-full-access"。详见 Managed configuration 和 Admin-enforced requirements。
常用配置项
下面这些是最常见的修改项。
默认模型
选择 CLI 和 IDE 默认使用的模型。
model = "gpt-5.5"审批提示
控制 Codex 何时会暂停并在运行生成的命令前询问你。
approval_policy = "on-request"关于 untrusted、on-request 和 never 的行为差异，见 Run without approval prompts 和 Common sandbox and approval combinations。
沙箱级别
控制 Codex 在执行命令时拥有多少文件系统和网络访问权限。
sandbox_mode = "workspace-write"关于不同模式的行为，包括受保护的 .git/.codex 路径和网络默认值，见 Sandbox and approvals、Protected paths in writable roots 和 Network access。
权限配置文件
Codex 还支持命名的 permission profiles，用来复用文件系统和网络策略。内置 profile 有 :read-only、:workspace 和 :danger-full-access。自定义 profile 使用 [permissions.<name>] 表和匹配的 default_permissions 值。见 Permissions。
Windows sandbox 模式
在 Windows 上原生运行 Codex 时，把 windows 表里的 native sandbox mode 设为 elevated。只有在你没有管理员权限，或者 elevated 设置失败时，才使用 unelevated。
[windows]
sandbox = "elevated" # Recommended
# sandbox = "unelevated" # Fallback if admin permissions/setup are unavailableWeb search 模式
Codex 默认会为本地任务开启 web search，并从 web search cache 提供结果。这个 cache 是 OpenAI 维护的网页结果索引，所以 cached 模式返回的是已预索引结果，不会实时抓取页面。这样能减少来自实时网页内容的 prompt injection 风险，但 web 结果仍然要按不可信内容处理。如果你使用 --yolo 或其他 full access sandbox setting，web search 默认会改用 live results。用 web_search 选择模式：
"cached"（默认）从 web search cache 返回结果。"live"抓取最新网页数据，效果等同--search。"disabled"关闭 web search 工具。
web_search = "cached" # default; serves results from the web search cache
# web_search = "live" # fetch the most recent data from the web (same as --search)
# web_search = "disabled"Reasoning effort
在模型支持时，调节模型使用的 reasoning effort。
model_reasoning_effort = "high"通信风格
为支持的模型设置默认 communication style。
personality = "friendly" # or "pragmatic" or "none"你也可以在活跃会话里用 /personality 覆盖，或者在使用 app-server APIs 时按 thread 或 turn 单独设置。
TUI keymap
在 tui.keymap 下自定义终端快捷键。上下文相关的绑定会覆盖 tui.keymap.global，空列表会取消绑定。
[tui.keymap.global]
open_transcript = "ctrl-t"
[tui.keymap.composer]
submit = ["enter", "ctrl-m"]命令环境
控制 Codex 会向哪些环境变量透传给启动的命令。
[shell_environment_policy]
include_only = ["PATH", "HOME"]日志目录
覆盖 Codex 写本地日志文件的位置，例如 codex-tui.log。
log_dir = "/absolute/path/to/codex-logs"对于一次性运行，也可以从 CLI 设置：
codex -c log_dir=./.codex-logFeature flags
使用 config.toml 里的 [features] 表来打开或关闭可选和实验性能力。
[features]
shell_snapshot = true # Speed up repeated commands支持的 features
| Key | Default | Maturity | Description |
|---|---|---|---|
apps |
false | Experimental | Enable ChatGPT Apps/connectors support |
codex_git_commit |
false | Experimental | Enable Codex-generated git commits and commit attribution trailers |
hooks |
true | Stable | Enable lifecycle hooks from hooks.json or inline [hooks]. See Hooks. |
fast_mode |
true | Stable | Enable Fast mode selection and the service_tier = "fast" path |
memories |
false | Stable | Enable Memories |
multi_agent |
true | Stable | Enable subagent collaboration tools |
personality |
true | Stable | Enable personality selection controls |
shell_snapshot |
true | Stable | Snapshot your shell environment to speed up repeated commands |
shell_tool |
true | Stable | Enable the default shell tool |
unified_exec |
true except Windows |
Stable | Use the unified PTY-backed exec tool |
undo |
false | Stable | Enable undo via per-turn git ghost snapshots |
web_search |
true | Deprecated | Legacy toggle; prefer the top-level web_search setting |
web_search_cached |
false | Deprecated | Legacy toggle that maps to web_search = "cached" when unset |
web_search_request |
false | Deprecated | Legacy toggle that maps to web_search = "live" when unset |
表里的 Maturity 表示 feature 的成熟度标签，例如 Experimental、Beta、Stable。怎么理解这些标签，见 Feature Maturity。
如果不写某个 feature key，就保留默认值。
关于 lifecycle hook 配置，见 Hooks。
怎么启用 features
- 在
config.toml里，把feature_name = true加到[features]下。 - 从 CLI 运行
codex --enable feature_name。 - 如果要同时启用多个 feature，使用
codex --enable feature_a --enable feature_b。 - 要关闭某个 feature，在
config.toml中把对应 key 设为false。
自定义 Provider（接入第三方 / 国内中转）
Codex 支持接入任何 OpenAI 兼容 API。两个配置段必须同时出现，且名称完全一致（包括大小写）：
model_provider = "myproxy"
model = "gpt-4.1"
disable_response_storage = true
preferred_auth_method = "apikey"
[model_providers.myproxy]
name = "myproxy"
base_url = "https://your-proxy.example.com/v1"
env_key = "MYPROXY_API_KEY"model_provider和[model_providers.xxx]段名必须完全一致，否则 Codex 无法识别，直接回落到默认 OpenAI 地址env_key指定读取 API Key 的环境变量名；如果省略，Codex 会读OPENAI_API_KEYwire_api可选，大多数兼容服务不需要填；使用 Responses API 的服务填"responses"
对应的环境变量：
export MYPROXY_API_KEY="sk-xxxx"Windows 用 setx 持久化（需重启终端生效）：
setx MYPROXY_API_KEY "sk-xxxx"接入 Azure OpenAI、Ollama（本地模型）、OpenRouter 等的写法相同，只需替换 base_url 和 env_key。国内中转的完整配置步骤见 Codex 国内使用指南。
常见问题
OpenAI Codex 项目配置不生效怎么排查？
先看项目是否被标记为 untrusted。只要项目不受信任，Codex 就会跳过项目 .codex/ 层，项目级 config.toml、hooks 和 rules 都不会加载。用户配置和系统配置仍会继续生效。
OpenAI Codex 怎么临时覆盖一个配置项？
用 CLI 的 -c 或 --config，例如 codex -c log_dir=./.codex-log。这种覆盖只对当前这次运行有效，且要按 TOML 语法写值。
OpenAI Codex 的 web_search 默认是什么？
默认是 cached。它会从 OpenAI 维护的 web search cache 里返回结果，不会实时抓取页面；如果你启用 --yolo 或其他 full access sandbox setting，默认会切到 live。