配置基础

Codex 从多个位置读取配置。你的个人默认设置保存在 ~/.codex/config.toml 中，也可以通过 .codex/config.toml 文件添加项目级覆盖配置。出于安全考虑，Codex 仅在你信任项目时加载项目的 .codex/ 配置层。

Codex 配置文件

Codex 将用户级配置存储在 ~/.codex/config.toml。要将设置限定于特定项目或子文件夹，请在仓库中添加 .codex/config.toml 文件。

要从 Codex IDE 扩展打开配置文件，请选择右上角的齿轮图标，然后选择 Codex 设置 > 打开 config.toml。

CLI 和 IDE 扩展共用相同的配置层。你可以用它们来：

• 设置默认模型和提供商。
• 配置审批策略和沙箱设置。
• 配置 MCP 服务器。

配置优先级

Codex 按以下顺序解析配置值（优先级从高到低）：

1. CLI 标志和 --config 覆盖设置
2. 项目配置文件：.codex/config.toml，按项目根目录到当前工作目录的顺序排列（距离最近的优先；仅适用于受信任项目）
3. 通过 --profile profile-name 选择的配置档案文件（~/.codex/profile-name.config.toml）
4. 用户配置：~/.codex/config.toml
5. 云端管理的 config.toml 默认设置（如果已为登录的工作区下发）
6. 系统配置（如果存在）：Unix 上的 /etc/codex/config.toml
7. 内置默认设置

利用这一优先级顺序，在 config.toml 中设置共用的默认值，让配置档案文件只包含存在差异的值。

云端管理的配置和系统配置可以定义插件市场，并设置 是否默认启用插件。这些设置独立于强制执行的 requirements.toml 策略。请参阅配置插件市场和默认设置。

如果你将项目标记为不受信任，Codex 会跳过项目范围内的 .codex/ 配置层，包括项目本地配置、钩子和规则。用户配置和系统配置仍会加载，包括用户级/全局钩子和规则。

有关通过 -c/--config 进行一次性覆盖的说明（包括 TOML 引号规则），请参阅高级配置。

常用配置选项

以下是一些最常调整的选项：

默认模型

选择 Codex 在 CLI 和 IDE 中默认使用的模型。

model = "gpt-5.6"

审批提示

控制 Codex 何时在运行生成的命令之前暂停并请求批准。

approval_policy = "on-request"

有关 on-request 和 never 的行为差异，请参阅不显示审批提示的运行方式和常见沙箱与审批组合。如果现有配置使用 approval_policy = "untrusted"，请参阅从已停用的 untrusted 审批策略迁移。

沙箱级别

调整 Codex 执行命令时对文件系统和网络的访问权限。

sandbox_mode = "workspace-write"

有关各模式的行为（包括受保护的 .git/.codex 路径和网络默认设置），请参阅沙箱与审批、可写根目录中的受保护路径和网络访问。

权限配置档案

Codex 还支持命名的权限配置档案，用于复用文件系统和 网络策略。内置档案包括 :read-only、:workspace 和 :danger-full-access。自定义档案使用 [permissions.<name>] 表和 匹配的 default_permissions 值。请参阅权限。

Windows 沙箱模式

在 Windows 上原生运行 Codex 时，请在 windows 表中将原生沙箱模式设为 elevated。仅当你没有管理员权限或提权设置失败时，才使用 unelevated。

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

网页搜索模式

Codex 默认为本地聊天启用网页搜索，并从网页搜索缓存中提供结果。该缓存是 OpenAI 维护的网页结果索引，因此缓存模式返回预先索引的结果，而非获取实时页面。这可以减少来自任意实时内容的提示注入风险，但你仍应将网页结果视为不受信任的内容。如果你使用 --yolo 或其他完全访问沙箱设置，网页搜索默认返回实时结果。通过 web_search 选择模式：

• "cached"（默认）从网页搜索缓存中提供结果。
• "indexed" 仅在搜索索引允许请求通过时才允许访问外部网页。
• "live" 从网页获取最新数据（与 --search 相同）。
• "disabled" 关闭网页搜索工具。

web_search = "cached"  # default; serves results from the web search cache
# web_search = "indexed" # gate external web access through the search index
# web_search = "live"  # fetch the most recent data from the web (same as --search)
# web_search = "disabled"

思考强度

在模型支持时，调整其思考强度。

model_reasoning_effort = "high"

沟通风格

为支持的模型设置默认沟通风格。

personality = "friendly" # or "pragmatic" or "none"

之后，你可以在活动会话中使用 /personality 覆盖此设置，也可以在使用 app-server API 时按线程或轮次覆盖。

TUI 按键映射

在 tui.keymap 下自定义终端快捷键。部分输入框操作会回退到匹配的 tui.keymap.global 按键绑定；如果支持特定上下文的绑定，则优先使用该绑定。空列表会解除该操作的按键绑定。

[tui.keymap.global]
open_transcript = "ctrl-t"

[tui.keymap.composer]
submit = ["enter", "ctrl-m"]

[tui.keymap.chat]
interrupt_turn = "f12"

命令环境

控制 Codex 向启动的命令传递哪些环境变量。使用 按键名筛选的过滤器，仅保留所需变量：

[shell_environment_policy]
ignore_default_excludes = false

[shell_environment_policy.filters]
"PATH" = "include"
"HOME" = "include"

ignore_default_excludes 默认为 true，这会跳过自动过滤， 不再过滤名称包含 KEY、SECRET 或 TOKEN 的变量。将其设为 false 即可启用该自动过滤功能。有关排除规则、优先级和 旧版配置，请参阅 Shell 环境 策略。

日志目录

覆盖 Codex 写入本地日志文件的位置。显式设置 log_dir 还会 在该目录中启用需主动开启的纯文本 TUI 日志 codex-tui.log。

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

对于单次运行，你也可以通过 CLI 设置：

codex -c log_dir=./.codex-log

功能标志

使用 config.toml 中的 [features] 表开启或关闭可选功能和实验性功能。

常用功能标志

有关生命周期钩子的配置，请参阅钩子。

启用功能

• 在 config.toml 中，将 feature_name = true 添加到 [features] 下。
• 在 CLI 中运行 codex --enable feature_name。
• 要启用多个功能，请运行 codex --enable feature_a --enable feature_b。
• 要禁用某个功能，请在 config.toml 中将该键设为 false。