一份 config.toml 讲透 Codex：从最小配置到最佳实践一份 config.toml 讲透 Codex：从最

一份 config.toml 讲透 Codex：从最小配置到最佳实践

很多人第一次用 Codex，先改 prompt。

改半天，效果还是不稳。

同样一句“帮我修这个 bug”，为什么它有时会自己找文件、改代码、跑检查，有时又像个高级聊天框？问题通常不在 prompt，而在 config.toml。

你如果把 Codex 当补全工具来配，体验大概率一般。因为它本来就不是普通补全工具。官方文档写得很明确：你发出 prompt 后，它会进入一个循环，先调用模型，再执行文件读取、文件修改、工具调用，直到任务完成或者你取消。说白了，它是个会行动的 coding agent。

所以这篇文章不聊功能盘点，也不聊“10 个神级 prompt”。只讲 3 件事：

Codex 为什么一定要配
一份最小可用的 config.toml 该怎么写
哪些配置真的会影响你每天的使用体验

信息源都来自 OpenAI 官方 Codex 文档。

先给结论：Codex 的效果，很多时候是“配置问题”，不是“模型问题”

很多人觉得 Codex 不稳定，不是因为模型忽好忽坏，而是运行边界没定义清楚。

比如：

它到底能不能写文件
它跑命令前要不要先问你
它默认用哪个模型
它能不能联网
它执行子命令时会继承哪些环境变量
它是不是应该在这个仓库里开子代理并行处理

这些都不是 prompt 能补救的事。

官方在 Config basics 和 Best practices 里反复强调一件事：Codex 更适合被当成一个需要持续配置、持续改进的队友，而不是一次性的问答助手。

先接受这个前提，后面的配置就顺了。

从最小配置开始

如果你现在还没系统配过 Codex，我建议先用这一版。

# ~/.codex/config.toml

model = "gpt-5.4"
model_provider = "openai"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

[sandbox_workspace_write]
network_access = false
writable_roots = []

[shell_environment_policy]
inherit = "all"
exclude = []
include_only = []

为什么先给这版？

因为它够用，而且边界清楚。

model = "gpt-5.4"：官方样例里给的大多数用户推荐值
approval_policy = "on-request"：让 Codex 在需要时主动请求权限，不会默认无脑放行
sandbox_mode = "workspace-write"：允许它改当前工作区，但不会直接给整台机器全开
web_search = "cached"：默认先走缓存搜索，够稳
network_access = false：先关着，等你真有需要再开

核心思路就一句话：

先让 Codex 能干活，再把权限收在可控范围里。

先理解配置优先级，不然你会以为配置失效了

这一段很容易被忽略，但很关键。

根据官方 Config basics，Codex 的配置优先级从高到低是：

CLI flags 和 --config 临时覆盖
--profile <name> 指定的 profile
项目级 .codex/config.toml
用户级 ~/.codex/config.toml
系统级 /etc/codex/config.toml
内建默认值

比如你明明在 ~/.codex/config.toml 里把 sandbox_mode 改成了 workspace-write，结果当前项目还是只读，很可能不是 Codex 抽风，而是仓库里的 .codex/config.toml 把它覆盖掉了。

还有一个细节。

官方文档提到，Codex 只有在你信任项目时，才会加载项目级 .codex/config.toml。如果项目被标记为不可信，它会跳过项目级配置，退回用户级、系统级和默认值。

所以你碰到“为什么这个仓库跟别的仓库行为不一样”，先查配置层级。

3 个最关键的字段，决定了 Codex 是工具还是风险源

如果你只想抓重点，看这 3 个字段就够了。

1. `model`：决定它的上限

官方 Sample Configuration 里给的推荐示例是：

model = "gpt-5.4"
model_provider = "openai"

这不只是“选个模型”。

它还会影响：

推理强度该怎么配
输出密度是什么风格
长任务时的稳定性

官方样例里还有这些字段：

model_reasoning_effort = "medium"
plan_mode_reasoning_effort = "high"
model_verbosity = "medium"

实战上我会这么配：

日常改小 bug、查代码、写小功能，用 medium
跨模块重构、复杂排错、长链路任务，再往上调
不要默认拉满。高推理强度不是免费午餐，成本和等待时间都会上去

对大多数人来说，先把默认模型配对，比研究 prompt 修辞有用。

2. `approval_policy`：决定它什么时候该停下来问你

官方样例里写得很清楚，常见模式包括：

untrusted
on-request
never

含义也很直白：

untrusted：只有已知安全的只读命令自动跑，其他都要确认
on-request：由模型判断什么时候请求审批。这也是官方样例里的默认示例
never：不弹审批，风险最高

如果你刚开始用 Codex，别碰 never。

官方在 Best practices 里也明确建议：新手先保持默认权限，先把审批和沙箱收紧，只对可信仓库或明确工作流逐步放开。

这条建议很实用。开发者最容易犯的错，不是“权限太少”，而是“还没摸清工作流就把整台机器交出去”。

3. `sandbox_mode`：决定它能碰到哪一层系统

这是最影响体验上限的字段。

官方样例里给出的模式有 3 个：

read-only
workspace-write
danger-full-access
read-only：只能看，不能改
workspace-write：能改当前工作区
danger-full-access：基本不设沙箱，风险极高

很多人第一次用 Codex 时，觉得它“不会干活”，其实就是因为还停留在 read-only。

如果你的目标是让它真正参与改代码，workspace-write 才是更实用的起点。

而且 workspace-write 不是一句开关结束，后面还有细分表可以继续限制：

[sandbox_workspace_write]
writable_roots = []
network_access = false

这里要注意两点。

writable_roots 可以给当前工作区之外再加额外可写目录。
network_access 在这个模式下默认是 false。也就是说，就算你让 Codex 能写工作区，它也不等于自动能联网。

所以配置不是装饰品。它定义的是 agent 的边界。

这些配置项不一定最常改，但很值得早点知道

`web_search`：决定它拿到的是缓存信息还是实时信息

官方样例里的写法是：

web_search = "cached"

可选值有：

disabled
cached
live

默认先用 cached 没问题。

如果你的任务是代码分析、仓库内开发、文档查阅，缓存搜索通常够用了。

但如果你在查最新 API 行为、版本变化或者刚发布的东西，live 才更稳。

更稳的用法是：

平时默认 cached
只在明确需要最新信息的任务里切 live

不要什么都开实时。没必要。

`shell_environment_policy`：决定子命令继承什么环境

这一块很容易被忽略，但很容易踩坑。

官方样例支持这样配：

[shell_environment_policy]
inherit = "all"
exclude = []
include_only = []
set = {}

这块控制的是 Codex 在执行 shell 工具时，会继承哪些环境变量。

如果你们团队依赖：

代理设置
私有镜像地址
内部 API 地址
特定语言运行时变量

那这里就很关键。

很多所谓“Codex 不稳定”，其实是子命令根本没拿到正确环境。

`[agents]`：决定你要不要把它用成多代理系统

官方 Subagents 文档里说明，Codex 支持内建的 default、worker、explorer 等 agent，也支持你在 ~/.codex/agents/ 或 .codex/agents/ 下定义自定义 agent。

全局限制写在 [agents] 下面，例如：

[agents]
max_threads = 6
max_depth = 1

这里官方给出的默认值是：

max_threads = 6
max_depth = 1

大多数人先别急着改。

子代理不是“越多越快”的开关。官方也特别提醒了，max_depth 往上调会增加 token 消耗、延迟和本地资源消耗。

一句话总结就是：

并行适合天然可拆分的任务，不适合所有任务。

真正影响结果的，不只是 config.toml，还有 AGENTS.md

如果只讲配置，不讲 AGENTS.md，这篇文章就缺一块。

因为官方在 Best practices 里讲得很明确：Codex 最好和 AGENTS.md 配合使用。

config.toml 解决的是运行边界。

AGENTS.md 解决的是项目规则。

这两个东西分工不同：

config.toml：决定它能不能改、能不能跑、能不能联网、默认用什么模型
AGENTS.md：告诉它项目结构、测试命令、lint 规则、代码约束、什么叫完成

官方建议一个好的 AGENTS.md 至少要覆盖这些内容：

仓库目录结构
项目怎么跑
build、test、lint 命令
工程约定和 PR 预期
限制项和禁止项
完成标准，以及怎么验证

很多人喜欢把所有规则都塞进 prompt。结果就是每次都要重复，而且越写越长，最后连自己都不想看。

更稳的做法是：

稳定规则放进 AGENTS.md
运行边界放进 config.toml
当前任务目标放进 prompt

分层清楚，Codex 才稳定。

Prompt 也要配合配置来写，不然它没法自证结果

官方 Prompting 和 Best practices 有一个共同观点：Codex 在“能验证自己工作”的情况下，效果会明显更好。

官方给的建议包括：

提供复现问题的步骤
提供验证特性的方式
告诉它该跑哪些 lint、test、pre-commit 检查
复杂任务拆成更小的步骤

这也解释了为什么配置重要。

如果你的 sandbox_mode 还是只读，它就没法改文件。如果你的审批策略太严，它可能关键一步就停住。如果环境变量没配好，它跑测试就失败。

所以 prompt、配置、项目规则，本来就是一套东西。

不要分开看。

我更推荐的 3 套配置思路

下面这部分是我按官方文档整理出来的实战建议。不是唯一答案，但比较稳。

1. 个人项目：先让它真的能干活

适合场景：

个人 side project
本地实验仓库
你能接受它直接改代码

建议：

model = "gpt-5.4"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

[sandbox_workspace_write]
network_access = false

重点是低阻力上手。

先把“读代码、改代码、跑本地命令”这条链打通。别一开始就搞得像审计系统。

2. 团队仓库：默认保守，按项目覆盖

适合场景：

多人协作仓库
规则多
测试和 review 流程比较正式

建议：

在 ~/.codex/config.toml 放个人默认值
在仓库里放 .codex/config.toml
配套写 AGENTS.md

项目级配置可以更保守一点：

approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

然后把这些内容写进 AGENTS.md：

测试命令
lint 命令
PR 规则
禁止直接改的目录
完成标准

这套比天天在 prompt 里手动提醒可靠得多。

3. 高风险仓库：先保命，再谈提效

适合场景：

生产环境脚本
基础设施仓库
涉及密钥、账单、权限系统的项目

建议：

approval_policy = "untrusted"
sandbox_mode = "read-only"
web_search = "disabled"

先让它做这些事：

查代码
解释逻辑
给修改方案
生成 patch 建议

别急着让它直接执行。

等你把项目边界摸清，再逐步开放到 workspace-write。这比一开始开 danger-full-access 靠谱得多。

再讲 5 条真正有用的最佳实践

这部分不说空话，只说最值得执行的。

1. 先配边界，再谈效率

别一上来追求“自动化程度高不高”。

先确认这几个问题：

它默认能不能写当前仓库
它跑命令前会不会先问你
它能不能联网
它能不能拿到正确环境变量

这 4 个问题没配清楚，后面都不稳。

2. 把持久规则移出 prompt

官方明确建议把稳定规则放进 AGENTS.md。

如果一条规则你已经说过两遍了，就不要继续在 prompt 里重复。该沉淀成文档就沉淀成文档。

3. 任务一定要可验证

不要只说“帮我修一下”。

要说：

改哪个行为
哪些文件相关
跑哪个测试
什么结果算完成

官方把这件事说得很清楚。Codex 能验证自己时，结果会更可靠。

4. MCP 解决的是“仓库外上下文”问题

如果任务依赖 Jira、GitHub、设计稿、线上文档、内部平台，别反复复制粘贴。

官方建议很实用：

外部信息在仓库外
数据变化频繁
你希望它直接用工具而不是读一坨贴进去的文本

这时候就该上 MCP。

也别贪多。先接 1 到 2 个真能减少手工循环的工具就够了。

5. 重复流程就做成 skill

这条很多人会忽略。

官方建议，如果一个工作流开始重复出现，就不要继续依赖长 prompt 和来回纠正，而应该把它沉淀成 skill。

因为这意味着你不是在“训练自己更会提示”，而是在“把经验变成系统能力”。

一个我更推荐的使用心智

如果只看文档字段，你很容易把 Codex 理解成“一个带很多选项的 CLI 工具”。

我更愿意把它理解成一个受配置约束的代理运行时。

config.toml 不是偏好设置。

它定义的是：

代理默认用哪个脑子
代理什么时候该停下来问你
代理可以进入多大的系统边界
代理能不能访问外部世界
代理能不能继续拆成多代理协作

从这个角度看，配置就不是可选项了。

它更像 Codex 的操作系统。

最后给一个简单的落地顺序

如果你今天就想把 Codex 配起来，我建议按这个顺序来：

在 ~/.codex/config.toml 写最小配置
把 approval_policy 保持在 on-request
把 sandbox_mode 调到 workspace-write
暂时保持 network_access = false
给仓库补一份 AGENTS.md
后续再按项目加 .codex/config.toml
真有外部上下文需求，再接 MCP
真有重复流程，再做 skill

这条路径不激进，但很稳。

对大多数开发者来说，稳比“全自动”更重要。

一份 config.toml 讲透 Codex：从最小配置到最佳实践