配置

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	活躍的配置文件名稱。