config.toml 基础配置

7.1 配置文件位置

Codex 将其配置存储在:

~/.codex/config.toml

这个文件是 Codex 的核心配置,CLI、IDE 扩展、Codex App 三端共用同一个 config.toml。你可以用它来:

• 设置默认模型与提供商
• 配置审批策略与沙箱设置
• 配置 MCP 服务器
• 开启实验性功能

从 IDE 打开 config.toml

1. 点击编辑器右上角的齿轮图标
2. 选择 Codex Settings(Codex 设置)
3. 选择 Open config.toml(打开 config.toml)

7.2 配置优先级

Codex 的配置按以下优先级从高到低加载,后者被前者覆盖:

优先级	来源	说明
1(最高)	命令行参数	一次性覆盖,如 --model --sandbox
2	项目级 .codex/config.toml	当前项目目录下的配置
3	个人 ~/.codex/config.toml	用户全局默认

💡 一个良好习惯:个人默认放 ~/.codex/config.toml,项目级行为放 .codex/config.toml,命令行参数只用于一次性场景。

7.3 常见配置选项

以下是最常修改的配置项,都在 config.toml 顶层设置:

~/.codex/config.toml

# 默认模型
model = "gpt-5.3-codex"

# 审批策略
approval_policy = "on-request"

# 沙箱模式
sandbox_mode = "workspace-write"

# 模型推理强度(影响速度与质量)
model_reasoning_effort = "medium"

配置项说明

配置项	作用	常见取值
model	默认模型	gpt-5.3-codex、gpt-5-codex、gpt-5.4-mini 等
approval_policy	审批策略(何时请求人工确认)	untrusted / on-failure / on-request / never
sandbox_mode	沙箱模式(文件读写边界)	read-only / workspace-write / danger-full-access
model_reasoning_effort	推理强度	low / medium / high / extra high

⚠️ 安全约束:某些组合被禁止,例如不允许同时设置 approval_policy = "never" 与 sandbox_mode = "danger-full-access"(这等于让 AI 完全无人值守地修改任何文件,太危险)。

7.4 功能开关(features)

features 字段用于开启实验性或可选功能:

[features]
# 开启 hooks 钩子(见第 18 章)
hooks = true

/experimental 斜杠命令可以查看和切换实验特性,切换后会自动写入 config.toml。

7.5 沙箱模式的块状写法

除了顶层 sandbox_mode = "..." 写法,也可以用块状写法(等价):

[sandbox]
mode = "workspace-write"

IDE 插件(VS Code/JetBrains)在 settings.json 中对应配置项:

{
  "codex.sandbox_mode": "auto-review"
}

7.6 一个可直接用的起点配置

来自「Codex CLI 深度指南」的实战配置,可直接复制作为起点:

~/.codex/config.toml

# 默认模型
model = "gpt-5.3-codex"

# 审批策略:on-request 表示关键操作前人工确认,其余自动推进
approval_policy = "on-request"

# 沙箱模式:workspace-write 表示只能在工作区写入
sandbox_mode = "workspace-write"

# 推理强度
model_reasoning_effort = "medium"

资料来源

• CSDN《Codex 完整指南(五):config.toml 配置详解》——配置优先级、常见配置项、安全约束
• 掘金《Codex 接哪个模型效果最好》——model_reasoning_effort、approval_policy 实战配置
• 头条《Codex CLI 深度指南》——可直接用的 config.toml 起点
• 掘金《八万字长文深度解析 Codex》——[sandbox] mode 块状写法与 IDE settings.json
• 官方文档 developers.openai.com/codex/config-basic