说实话，刚接触 Codex 的时候，我也差点把它当成一个带点代码高亮的 ChatGPT 换皮版。你发个指令，它回两行字，kan着挺唬人，真要上手干活，经常这就卡壳，那也报错。后来我才发现，这根本不是模型笨，是我们把路走窄了。

官方文档其实把底牌亮得hen清楚：Codex 不是那种你问一句它答一句的应声虫，它是一个会行动的 Coding Agent。你发出 Prompt，它进入一个循环——调用模型、读文件、改代码、跑工具、验证结果，直到任务完成或者你喊停。既然是“Agent”，它就需要一套运行规则，而这套规则的“宪法”，就是 config.toml。

Ru果你只盯着怎么写 Prompt，却忽略了配置文件，那就像是买了一辆法拉利却只敢在小区里推着走。今天咱们不整那些虚头巴脑的理论，直接扒开 config.toml 的里子，kankan怎么把这个队友调教成你的Zui佳辅助。

别把配置当“偏好设置”，那是它的“操作系统”

hen多人习惯把所有规则dou塞进 Prompt 里。结果呢？Prompt 越写越长，像裹脚布一样，每次对话还得重复一遍，Zui后连自己dou不想kan。geng糟糕的是Prompt hen容易被上下文截断或者被模型忽略。

这时候就该上 config.toml 了。它解决的不是“我想让它Zuo什么”，而是“它NengZuo什么”。

举个Zui简单的例子，为什么有时候 Codex Neng自己找文件、改代码、跑测试，像个老司机；有时候又像个只会说“我不会”的实习生？问题通常不在你的 Prompt 写得不够深情，而在 sandbox_mode没配对。Ru果你的模式还是只读，它就算想帮你修 Bug，也没权限动刀子。

配置的优先级：为什么你的设置“不生效”？

在动手改之前，必须得搞清楚 Codex 的配置层级。hen多人踩过这个坑：明明在 ~/.codex/config.toml 里把权限放开了结果切到某个项目里它还是一副“莫挨老子”的只读姿态。

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

项目级配置.codex/config.toml

用户级配置~/.codex/config.toml

系统级配置/etc/codex/config.toml

默认值代码里写死的

这意味着什么？意味着项目级的配置会覆盖你的全局设置。官方也说了Codex 只有在信任项目时才会加载项目级配置。Ru果项目被标记为不可信，它会直接跳过项目级配置，退回到用户级或系统级。所以当你发现“这个仓库跟别的仓库行为不一样”时别急着骂 Codex 抽风，先去查查项目目录下是不是藏着个 .codex/config.toml 把你给“背刺”了。

核心实战：从“只读”到“全权委托”的进阶之路

Ru果你今天就想把 Codex 配起来我建议按这个顺序来。这条路径不激进，但hen稳。别一上来就追求什么“全自动”，先把“读代码、改代码、跑本地命令”这条链打通。

第一步：给它一把“手术刀”

hen多人第一次用 Codex，默认配置往往是 read-only。这hen安全，但也hen没用。它只Nengkan，不Neng改，体验大概率一般。

Ru果你的目标是让它真正参与改代码，workspace-write 才是geng实用的起点。这条hen多人会忽略，但它是分水岭。

approval_policy = "on-request"
sandbox_mode = "workspace-write"
network_access = false
writable_roots = 

这里面的逻辑hen直白：approval_policy = "on-request" 意味着它要干大事之前会先问你，这给了你安全感；而 sandbox_mode = "workspace-write" 则赋予了它动刀的权力。

注意 下面的细分配置。比如 network_access = false，默认切断网络是个好习惯，防止它乱下东西或者把代码传到不知名的地方。至于 writable_roots，你Ke以留空让它管整个工作区，也Ke以指定目录，比如只让它改 ./src，别动 ./config。

第二步：环境变量，别让它在“真空”里跑

hen多所谓“Codex 不稳定”，其实是子命令根本没拿到正确环境。它想跑 npm test，结果连 NODE_ENV dou没加载，当然报错。

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

inherit = "all"
exclude = 
include_only = 
set = {}

对大多数人来说inherit = "all" 是Zui省事的方案。这意味着 Codex 会继承你当前终端的所有环境变量。Ru果你有特殊的密钥或者敏感路径，再考虑用 exclude 把它们踢出去。别一上来就搞复杂的白名单，先让它Neng跑起来再说。

第三步：模型与搜索，平衡速度与智商

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

model = "gpt-4o"
model_provider = "openai"
web_search = "cached"

这不只是“选个模型”。web_search 这个字段hen有意思。可选值有 livecacheddisabled。

Ru果你的任务是代码分析、仓库内开发、文档查阅，cached 通常够用了而且速度快，省 token。但Ru果你在查Zui新 API 行为、版本变化或者刚发布的东西，live 才geng稳。别什么dou开实时没必要，那是在烧钱。

被忽视的细节：子代理与并发

这一块hen容易被忽略，但hen容易踩坑。Codex 支持内建的 defaultworkerexplorer 等 agent，也支持你在 ~/.codex/agents/ 或 .codex/agents/ 下定义自定义 agent。

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

max_threads = 4
max_depth = 2

这里官方给出的默认值通常比较保守，是有道理的。并行适合天然可拆分的任务，不适合所有任务。Ru果你的任务依赖性强，线程开多了反而乱。geng稳的Zuo法是：先接受这个前提，后面的配置就顺了。

配置不是终点，AGENTS.md 才是灵魂

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

官方在 Prompting 和 Best practices 有一个共同观点：Codex 在“Neng验证自己工作”的情况下效果会明显geng好。而怎么让它验证？怎么让它知道这个项目的特殊规范？光靠 config.toml 是不够的，因为那是“硬约束”，不是“软知识”。

这时候就该把内容写进 AGENTS.md

官方建议一个好的 AGENTS.md 至少要覆盖这些内容：项目背景、代码风格规范、测试命令怎么跑、哪些目录是禁区。

比如你Ke以在 AGENTS.md 里写：“本项目使用 Go 语言，提交前必须运行 make lint 和 make test。” 这比你在 Prompt 里每次dou喊“记得跑测试”要靠谱一万倍。

Ru果一条规则你Yi经说过两遍了就不要继续在 Prompt 里重复。该沉淀成文档就沉淀成文档。这也解释了为什么配置重要——因为你不是在“训练自己geng会提示”，而是在“把经验变成系统Neng力”。

给新手的“保命”配置模版

说了这么多，Ru果你现在还没系统配过 Codex，我建议先用这一版。别急着改，先让它Neng干活，再把权限收在可控范围里。

# ~/.codex/config.toml
model = "gpt-4o"
model_provider = "openai"
# 核心策略：请求批准 + 工作区写入
approval_policy = "on-request"
sandbox_mode = "workspace-write"
# 网络搜索：默认缓存，省流省时
web_search = "cached"
# 沙箱细节：禁止联网，防止乱跑
network_access = false
writable_roots = 
# 环境变量：全盘继承，保证命令Neng跑
inherit = "all"
exclude = 
include_only = 

为什么先给这版？重点是低阻力上手。因为它够用，而且边界清楚。等你把项目边界摸清，再逐步开放到geng高级的功Neng，甚至尝试自定义 MCP工具，dou比一开始开 danger-full-access 靠谱得多。

稳比“全自动”geng重要

Zui后想唠叨两句。开发者Zui容易犯的错，不是“权限太少”，而是“还没摸清工作流就把整台机器交出去”。

danger-full-access 这种模式，基本不设沙箱，风险极高，除非你是在一个完全隔离的容器里玩，否则别碰。官方在 Best practices 里也明确建议：新手先保持默认权限，先把审批和沙箱收紧，只对可信仓库或明确工作流逐步放开。

Codex geng适合被当成一个需要持续配置、持续改进的队友，而不是一次性的问答助手。当你把 config.toml 和 AGENTS.md 打磨好了你会发现，它不再是一个需要你时刻盯着的小孩，而是一个Neng真正帮你分担工作的老伙计。

所以别再纠结“为什么它不听话”了去检查一下你的配置吧。那才是它“大脑”的底层代码。

---