配置 Codex 基础选项

Codex 会从多个位置读取配置。

你的个人默认配置位于 ~/.codex/config.toml。你也可以在项目里添加 .codex/config.toml，用来覆盖项目内的设置。出于安全考虑，Codex 只会在你 trust the project（信任项目）之后加载项目里的 .codex/ 配置层。

Codex 配置文件

Codex 会把用户级配置存储在：

~/.codex/config.toml

如果你想把某些设置限定在某个项目或子目录里，可以在仓库里添加：

.codex/config.toml

如果你在 Codex IDE extension 里打开配置文件，可以点击右上角齿轮图标，然后选择：

Codex Settings > Open config.toml

CLI 和 IDE extension 共享同一套配置层。你可以用这些配置做三类常见事情：

设置默认 model（模型）和 provider（供应商）。
配置 approval policies（审批策略）和 sandbox settings（沙箱设置）：https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals
配置 MCP servers（MCP 服务器）：https://developers.openai.com/codex/mcp

配置优先级

Codex 按下面顺序解析配置值，越靠前优先级越高：

CLI flags（CLI 参数）和 --config overrides（覆盖项）。
Profile values（配置档案值），来自 --profile <name>。
Project config files（项目配置文件）：.codex/config.toml。顺序是从项目根目录到当前工作目录，越靠近当前位置越优先；只适用于受信任项目。
User config（用户配置）：~/.codex/config.toml。
System config（系统配置，如果存在）：Unix 系统上的 /etc/codex/config.toml。
Built-in defaults（内置默认值）。

利用这个优先级，你可以把共享默认值放在上层，把 profiles 只用于那些确实不同的值。

如果你把一个项目标记为 untrusted（不受信任），Codex 会跳过项目范围内的 .codex/ 配置层，包括项目本地 config、hooks 和 rules。用户级和系统级配置仍然会加载，包括用户 / 全局 hooks 和 rules。

一次性用 -c 或 --config 覆盖配置时，需要注意 TOML 引号规则。参考 Advanced Config：

https://developers.openai.com/codex/config-advanced#one-off-overrides-from-the-cli

在 managed machines（受管理机器）上，你的组织还可以通过 requirements.toml 强制约束配置。例如禁止 approval_policy = "never" 或 sandbox_mode = "danger-full-access"。

常见配置项

下面是用户最常改的几个配置项。

Default model（默认模型）

选择 CLI 和 IDE 默认使用的模型：

model = "gpt-5.5"

Approval prompts（审批提示）

控制 Codex 在运行生成命令前，什么时候暂停并询问你：

approval_policy = "on-request"

关于 untrusted、on-request 和 never 的行为差异，参考：

Run without approval prompts：https://developers.openai.com/codex/agent-approvals-security#run-without-approval-prompts
Common sandbox and approval combinations：https://developers.openai.com/codex/agent-approvals-security#common-sandbox-and-approval-combinations

Sandbox level（沙箱级别）

调整 Codex 执行命令时拥有多少文件系统和网络访问权限：

sandbox_mode = "workspace-write"

逐模式行为见：

Sandbox and approvals：https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals
Protected paths in writable roots：https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots
Network access：https://developers.openai.com/codex/agent-approvals-security#network-access

Permission profiles（权限档案）

当你希望在多个会话里复用同一个文件系统或网络策略时，可以使用 named permission profile（命名权限档案）：

default_permissions = ":workspace"

内置 profiles 包括：

:read-only
:workspace
:danger-no-sandbox

如果需要自定义文件系统或网络规则，可以定义 [permissions.<name>] tables，然后把 default_permissions 设置为这个名称。

Windows sandbox mode（Windows 沙箱模式）

原生运行在 Windows 上时，在 windows table 里把 native sandbox mode（原生沙箱模式）设为 elevated。只有在没有管理员权限，或 elevated 设置失败时，才使用 unelevated。

[windows]
sandbox = "elevated"   # Recommended
# sandbox = "unelevated" # Fallback if admin permissions/setup are unavailable

网页搜索 mode（网页搜索模式）

Codex 默认会为本地任务启用 web search（网页搜索），并从 web search cache（网页搜索缓存）返回结果。这个缓存是 OpenAI 维护的网页结果索引，所以 cached mode 会返回预索引结果，而不是直接抓取实时页面。

这样可以减少来自任意实时网页内容的 prompt injection（提示注入）风险。但你仍然应该把网页结果当作不可信内容处理。

如果你使用 --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（推理强度）

当模型支持时，可以调节模型使用多少推理强度：

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"]

Command environment（命令环境）

控制 Codex 会把哪些环境变量转发给它生成并运行的命令：

[shell_environment_policy]
include_only = ["PATH", "HOME"]

Log directory（日志目录）

覆盖 Codex 写入本地日志文件的位置，例如 codex-tui.log：

log_dir = "/absolute/path/to/codex-logs"

一次性运行时，也可以从 CLI 设置：

codex -c log_dir=./.codex-log

功能开关（功能开关）

使用 config.toml 里的 [features] table，可以打开或关闭 optional（可选）和 experimental（实验性）能力。

[features]
shell_snapshot = true           # Speed up repeated commands

支持的功能

Key	Default	Maturity	Description
`apps`	`false`	Experimental	启用 ChatGPT Apps/connectors 支持。
`codex_hooks`	`true`	Stable	启用来自 `hooks.json` 或 inline `[hooks]` 的 lifecycle hooks。见 Hooks。
`fast_mode`	`true`	Stable	启用 Fast mode selection 和 `service_tier = "fast"` 路径。
`memories`	`false`	Stable	启用 Memories。
`multi_agent`	`true`	Stable	启用 subagent collaboration tools（子 Agent 协作工具）。
`personality`	`true`	Stable	启用 personality selection controls（人格 / 沟通风格选择控件）。
`shell_snapshot`	`true`	Stable	对 shell environment 做快照，加快重复命令。
`shell_tool`	`true`	Stable	启用默认 `shell` tool。
`unified_exec`	`true` except Windows	Stable	使用统一的 PTY-backed exec tool。
`undo`	`false`	Stable	通过每轮 git ghost snapshots 启用 undo。
`web_search`	`true`	Deprecated	旧开关；优先使用顶层 `web_search` 设置。
`web_search_cached`	`false`	Deprecated	旧开关；未设置时会映射到 `web_search = "cached"`。
`web_search_request`	`false`	Deprecated	旧开关；未设置时会映射到 `web_search = "live"`。

Maturity（成熟度）列使用 Experimental、Beta、Stable 等成熟度标签。如何理解这些标签，见 Feature Maturity：

https://developers.openai.com/codex/feature-maturity

省略某个 feature key 时，会保留它的默认值。

当前 lifecycle hooks MVP 见 Hooks：

https://developers.openai.com/codex/hooks

启用功能

在 config.toml 中，把 feature_name = true 添加到 [features] 下。
从 CLI 启用：codex --enable feature_name。
启用多个功能：codex --enable feature_a --enable feature_b。
禁用某个功能：在 config.toml 中把对应 key 设为 false。

On this page