配置

Codex 配置为您提供对 CLI 可用的模型、执行环境和集成的细粒度控制。使用本指南配合 codex exec 中的工作流、沙箱和批准中的护栏，以及来自 AGENTS.md 发现的项目指导。

快速导航

• 功能标志
• 模型选择
• 执行环境
• 项目根目录检测
• MCP 集成
• 可观测性和遥测
• 配置文件和覆盖
• 参考表

Codex 支持多种设置配置值的机制：

• 特定于配置的命令行标志，如 --model o3（最高优先级）。
• 通用的 -c/--config 标志，接受 key=value 对，如 --config model="o3"。
  • 键可以包含点来设置根目录更深处的值，例如 --config model_providers.openai.wire_api="chat"。
  • 为了与 config.toml 一致，值是 TOML 格式的字符串而不是 JSON 格式，所以使用 key='{a = 1, b = 2}' 而不是 key='{"a": 1, "b": 2}'。
    • 值周围的引号是必需的，因为没有它们，您的 shell 会在空格上分割配置参数，导致 codex 接收 -c key={a 和（无效的）附加参数 =、1,、b、=、2}。
  • 值可以包含任何 TOML 对象，如 --config shell_environment_policy.include_only='["PATH", "HOME", "USER"]'。
  • 如果 value 无法解析为有效的 TOML 值，它被视为字符串值。这意味着 -c model='"o3"' 和 -c model=o3 是等价的。
    • 在第一种情况下，值是 TOML 字符串 "o3"，而在第二种情况下，值是 o3，这不是有效的 TOML，因此被视为 TOML 字符串 "o3"。
    • 因为引号由 shell 解释，-c key="true" 将在 TOML 中被正确解释为 key = true（布尔值）而不是 key = "true"（字符串）。如果出于某种原因您需要字符串 "true"，您需要使用 -c key='"true"'（注意两组引号）。
• $CODEX_HOME/config.toml 配置文件，其中 CODEX_HOME 环境值默认为 ~/.codex。（注意 CODEX_HOME 也将是日志和其他 Codex 相关信息的存储位置。）

--config 标志和 config.toml 文件都支持以下选项：

功能标志

可选和实验性功能通过 $CODEX_HOME/config.toml 中的 [features] 表切换。如果您看到提及旧键的弃用通知（例如 experimental_use_exec_command_tool），请将设置移至 [features] 或传递 --enable <feature>。

[features]
web_search_request = true        # 允许模型请求网络搜索
# view_image_tool 默认为 true；省略以保持默认值

支持的功能：

键	默认值	阶段	描述
unified_exec	false	实验性	使用统一的 PTY 支持的 exec 工具
apply_patch_freeform	false	Beta	包含自由格式 apply_patch 工具
view_image_tool	true	稳定	包含 view_image 工具
web_search_request	false	稳定	允许模型发出网络搜索
enable_experimental_windows_sandbox	false	实验性	使用 Windows 受限令牌沙箱
tui2	false	实验性	使用实验性 TUI v2（视口）实现
skills	false	实验性	启用技能的发现和注入

注意：

• 省略键以接受其默认值。
• 旧版布尔值如 experimental_use_exec_command_tool、experimental_use_unified_exec_tool、include_apply_patch_tool 和类似的 experimental_use_* 键已弃用；设置相应的 [features].<key> 避免重复警告。

模型选择

model

Codex 应该使用的模型。

model = "gpt-5.1"  # 覆盖默认值（所有平台上的 "gpt-5.1-codex-max"）

model_provider

识别要从 model_providers 映射中使用的提供商。默认为 "openai"。您可以通过 OPENAI_BASE_URL 环境变量为内置的 openai 提供商覆盖 base_url。

approval_policy

确定何时应提示用户批准 Codex 是否可以执行命令：

approval_policy = "untrusted"  # 或 "on-failure"、"on-request"、"never"

sandbox_mode

Codex 在操作系统级沙箱中执行模型生成的 shell 命令。

sandbox_mode = "read-only"        # 或 "workspace-write"、"danger-full-access"

执行环境

更多详细配置选项，请参考原英文文档。配置文件支持以下主要选项：

• Model Context Protocol (MCP) 服务器配置
• 批准和沙箱策略
• Shell 环境变量策略
• 项目根目录检测
• 可观测性和遥测
• 配置文件和覆盖

完整参考

有关所有可用配置选项的完整列表和详细说明，请参考英文原始文档。

关键配置项包括：

键	类型 / 值	说明
model	string	要使用的模型（例如 gpt-5.1-codex-max）。
model_provider	string	来自 model_providers 的提供商 ID（默认：openai）。
approval_policy	untrusted | on-failure | on-request | never	何时提示批准。
sandbox_mode	read-only | workspace-write | danger-full-access	操作系统沙箱策略。
profile	string	活跃的配置文件名称。