【Codex CLI 配置指南（小白速通版）】

Codex CLI 配置指南（小白速通版）

想把 Codex CLI 调到最顺手？这篇入门文用实例讲清三件事：怎么“设”、设“在哪”、常见场景怎么写配置最省心。内容基于官方 docs/config.md，做了通俗化整理。

---

一句话总览

• 配置有三种入口，优先级从高到低：
  1. 命令行专用参数（如 --model o3）
  2. 通用 -c/--config key=value（TOML 值）
  3. 配置文件 $CODEX_HOME/config.toml（默认 ~/.codex/config.toml）
• 再往下才是 Codex 内置缺省值（如模型默认 gpt-5）。

---

最快上手：3 种设置方式

• 直接旗标（最高优先级）

  codex --model o3
  

• 通用 --config key=value（值用 TOML 语法，注意引号）

  codex -c model="o3"
  codex --config shell_environment_policy.include_only='["PATH","HOME"]'
  

  小提醒：
  • -c key='{a = 1, b = 2}' 是 TOML，别写 JSON 格式。
  • 无法解析成合法 TOML 的值会当作字符串处理（-c model=o3 等价 -c model='"o3"'）。
• 配置文件（持续生效，最适合沉淀）
  文件：~/.codex/config.toml

  model = "o3"
  approval_policy = "on-failure"
  

---

常用核心项（一看就会）

1) 模型与提供商

• 选模型

  model = "o3"  # 覆盖默认 gpt-5
  

• 切换提供商（与 model_providers 搭配）

  model_provider = "openai"  # 默认是 openai
  

• 典型组合：用本地 Ollama 的 Mistral

  model_provider = "ollama"
  model = "mistral"
  

2) 扩展/自定义提供商（model_providers）

• OpenAI Chat Completions 例子

  model = "gpt-4o"
  model_provider = "openai-chat-completions"[model_providers.openai-chat-completions]
  name = "OpenAI using Chat Completions"
  base_url = "https://api.openai.com/v1"
  env_key = "OPENAI_API_KEY"
  wire_api = "chat"  # 或 responses
  query_params = {}
  

• 本地 Ollama

  [model_providers.ollama]
  name = "Ollama"
  base_url = "http://localhost:11434/v1"
  

• 第三方（示例：Mistral）

  [model_providers.mistral]
  name = "Mistral"
  base_url = "https://api.mistral.ai/v1"
  env_key = "MISTRAL_API_KEY"
  

• 附加 HTTP 头

  [model_providers.example]
  http_headers = { "X-Example-Header" = "example-value" }
  env_http_headers = { "X-Features" = "EXAMPLE_FEATURES" }  # 从环境变量读
  

• 每提供商网络调优（写在其块内）

  [model_providers.openai]
  request_max_retries = 4
  stream_max_retries = 10
  stream_idle_timeout_ms = 300000
  

• Azure（记得带 api-version）

  [model_providers.azure]
  name = "Azure"
  base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
  env_key = "AZURE_OPENAI_API_KEY"
  query_params = { api-version = "2025-04-01-preview" }
  wire_api = "responses"
  

3) 批准策略（approval_policy）

• 何时弹窗让你同意命令执行：

  approval_policy = "untrusted"   # 非信任命令需批准（默认更谨慎）
  approval_policy = "on-failure"  # 失败后请求“无沙箱”重试
  approval_policy = "on-request"  # 模型认为需要时再请求升级
  approval_policy = "never"       # 从不请求升级（风险自担）
  

4) 沙箱策略（sandbox_mode）

• 读多写少（默认更安全）

  sandbox_mode = "read-only"
  

• 仅工作目录可写（含 /tmp 等），可细化：

  sandbox_mode = "workspace-write"
  [sandbox_workspace_write]
  writable_roots = ["/Users/YOU/.pyenv/shims"]
  network_access = false
  

• 完全关闭沙箱（仅限你清楚环境已隔离，或平台不支持沙箱）

  sandbox_mode = "danger-full-access"
  

5) 配置档（profiles）一键切换

• 在 config.toml 里定义多个档位，并用 --profile 切换：

  profile = "o3"  # 默认档[profiles.o3]
  model = "o3"
  model_provider = "openai"
  approval_policy = "never"[profiles.fast]
  model = "gpt-3.5-turbo"
  model_provider = "openai-chat-completions"
  

• 优先级回顾：命令行 > profile（被选中后生效） > config.toml > 默认值

6) 推理与输出细节

• 推理强度（Responses API）

  model_reasoning_effort = "minimal"  # minimal/low/medium(default)/high
  

• 推理小结

  model_reasoning_summary = "auto"    # auto/concise/detailed/none
  

• 文字详略度（Responses API）

  model = "gpt-5"
  model_verbosity = "low"             # low/medium(default)/high
  

• 强制当作“支持推理小结”的模型

  model_supports_reasoning_summaries = true
  

7) MCP servers（工具接入）

• JSON 配置在 TOML 中的写法：

  [mcp_servers.docs]
  command = "npx"
  args = ["-y", "mcp-server"]
  env = { "API_KEY" = "value" }
  startup_timeout_ms = 20000
  

• CLI 管理（实验性）：

  codex mcp add docs -- docs-server --port 4000
  codex mcp list --json
  codex mcp get docs
  codex mcp remove docs
  

8) 子进程环境（shell_environment_policy）

• 精简继承 + 强制设置：

  [shell_environment_policy]
  inherit = "core"           # all/core/none（默认 all）
  exclude = ["AWS_*", "AZURE_*"]
  include_only = ["PATH", "HOME"]
  set = { CI = "1" }
  

• 纯净环境：

  [shell_environment_policy]
  inherit = "none"
  set = { PATH = "/usr/bin", MY_FLAG = "1" }
  

9) 通知与历史

• 外部通知脚本：

  notify = ["python3", "/Users/me/.codex/notify.py"]
  

• 仅 TUI 内轻量提醒：

  [tui]
  notifications = ["agent-turn-complete", "approval-requested"]
  

• 历史记录：

  [history]
  persistence = "none"  # 默认 save-all
  

10) 其他常用项

• 文件跳转协议（让终端里的文件引用可点开）

  file_opener = "vscode"   # vscode/vscode-insiders/windsurf/cursor/none
  

• 隐藏模型“思考”过程事件

  hide_agent_reasoning = true
  

---

易错与小技巧

• --config 的值是 TOML，遇到空格记得整体加引号（避免 shell 分词）。
• 切换到自定义 model_provider 时，通常也要同时设置对应的 model。
• workspace-write 下，包含 .git/ 的仓库会默认把 .git/ 目录设为只读；需要写入（如 git commit）时会触发批准流程。
• 如果你的运行环境本身已是容器/沙箱，danger-full-access 可能更方便（但要确认外部隔离已足够安全）。

---

参考配置清单（可直接改）

model = "o3"
approval_policy = "on-failure"
sandbox_mode = "workspace-write"[model_providers.openai]
name = "OpenAI"
base_url = "https://api.openai.com/v1"
env_key = "OPENAI_API_KEY"
request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 300000[shell_environment_policy]
inherit = "core"
exclude = ["AWS_*", "AZURE_*"]
include_only = ["PATH", "HOME", "USER"]
set = { CI = "1" }[tui]
notifications = ["agent-turn-complete"]

以上就是把 config.md 的关键点转成易上手的操作说明。先用命令行尝试，再把你的偏好沉淀进 ~/.codex/config.toml，效率会越来越高。