配置基础

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 server。

配置优先级

要求用于约束行为；配置值用于提供默认值。通过 Work Cloud 访问本地计算机时，遵循以下要求：

• 跨策略： 优先级较高的策略优先于优先级较低的策略，即使后者更具体也是如此。
• 同一策略内： 特定操作系统的环境覆盖设置优先于适用于所有操作系统的环境覆盖设置，最后是 Global。
• 本地执行： MDM 和旧版受管设备要求的优先级高于 Agent Security。设备的系统要求文件的优先级低于 Agent Security。
• Work Cloud： Work 云容器保留现有的 Work Cloud 策略。对于具有本地访问权限的 Work 和 dots，启用受管策略后，受支持的 Global 策略约束共享的云端编排器；适用的本地执行要求约束所连接的计算机。

某些要求具有特定字段的合并规则。有关策略作用域和运行时限制，请参阅受管配置；有关 Work 兼容性，请参阅配置参考。

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-6.1-sol"

审批提示

控制 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 = "medium"

沟通风格

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

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。