Codex Agent配置实践：一文彻底搞懂角色与模型调度优先级实用指南

平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“Codex Agent配置实践：一文彻底搞懂角色与模型调度优先级”来说，它看着像小点，放到项目里常会牵出环境、配置、兼容性和维护成本。下面按实际采用顺序，把思路、关键写法和容易踩坑的地方讲清楚，便于大家直接对照操作。

1. 先聊聊我踩的坑

实际处理时，给 Codex 加个"代码分析员"“评审员"这种角色，我以为跟点外卖一样轻松：想加什么点什么，下单就完事。结果配完一看，Agent 纹丝不动，模型该换的没换，代码该乱的还是乱。那一刻我深刻体会到了什么叫"你以为你在设置，其实你在给代码写情书——人家根本不回。”

理解这一步时，后来我把文档翻了个底朝天，终于悟了：Codex 本地设置就三层，跟咱家三层小别墅似的，一层住模型，一层住角色，还有一层管调度。问题是你永远不知道哪层说了算，别墅越大，吵架的人越多。

我把这套设置归纳成一张表，看完你就知道谁管谁了：

一句话总结：**TOML 定义角色，AGENTS.md 定义调度。**新建一个角色文件，同时不等于启动了一个常驻 Agent。这就跟你办了张 健身卡，肉不会自己掉一样。

2. 设置入口 Agent 的默认模型

编辑 ~/.codex/config.toml：

model = "gpt-6-sol"
model_reasoning_effort = "medium"
[agents]
max_concurrent_threads_per_session = 3

2.1 前两项是啥

结合项目来看，前两项就是入口任务的默认模型和推理强度，相当于给整个 Codex 定了个"出厂设置"。

2.2 第三项是啥

max_concurrent_threads_per_session 限制的是同时打开的子 Agent 线程数，不包含入口 Agent 自己。注意，入口 Agent 本人不算数——这跟老板永远不算在加班人数里是一个道理。

这里的 3 只是入门的示例值，别当真。你以为你的项目能扛住 3 个同时发？先问问你的显卡答不答应，再问问你的钱包答不答应。

另外提醒一句：模型名称和推理强度得用你当前账号和客户端兼容的组合；显式选择的任务模型也可能覆盖入口默认值。具体字段以官方设置参考为准。

3. 新建一个只读 Agent

3.1 放哪儿

个人角色放 ~/.codex/agents/；只给一个项目用的角色，放那个项目的 .codex/agents/。别问我为什么这么设计，反正我没权限问。

3.2 写什么

比如新建 ~/.codex/agents/code_explorer.toml：

name = "code_explorer"
description = "只读追踪代码调用链、数据来源和模块归属。"
sandbox_mode = "read-only"
developer_instructions = """
追踪实际调用路径，引用具体文件和代码证据。
只做分析，不修改文件。
"""

落到代码里，每个独立 Agent 文件至少要有 name、description、developer_instructions 三件套，缺一个就跟你出门忘带钥匙一样尴尬。文件名最好和 name 一致，便于查找；Codex 识别角色时以 name 字段为准。

落到代码里，这个例子没写模型，主打一个"看人下菜碟"：新建 Agent 的时候，任务轻松就用便宜的，任务复杂就用贵的，灵活得很。

4. 固定模型：适合职责稳定的角色

结合项目来看，若一个角色每天干的活一模一样，比如永远只做代码评审，那就在角色文件里直接把模型焊死，省得每次新建还要纠结。比如 ~/.codex/agents/reviewer.toml：

name = "reviewer"
description = "只读检查代码正确性、回归和安全风险。"
model = "gpt-5.6-terra"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
优先报告有证据的实际风险，给出文件位置与触发条件。
不修改代码。
"""

固定模型时建议 model 和 model_reasoning_effort 一起写。只写模型不写推理强度？推理强度就会跑到别的设置层随便找个值凑合，就像你只点了主食忘了点配菜，最后端上来一盘光秃秃的米饭。

5. 动态模型：让同一角色处理不同难度的任务

code_explorer 有时候只需定位一个函数，有时候要追踪跨模块的调用链。这种时候别在 TOML 里锁死模型，直接在 AGENTS.md 里写清楚选择规则：

- 简单、低风险的调查：使用 gpt-5.6-luna，推理强度 low。
- 普通代码分析和测试：使用 gpt-5.6-terra，推理强度 medium。
- 复杂、跨系统或高风险调查：使用 gpt-5.6-sol，推理强度 high。
- 创建子 Agent 时，在任务描述中记录所选模型与推理强度。

然后给 Codex 一个明确任务：

请用 code_explorer 只读追踪这个接口的数据来源，按 AGENTS.md 的规则选择模型，同时得到文件和调用链证据。

AGENTS.md 表达的是调度规则。实际新建子 Agent 时还得提供具体任务；希望明确委派的话，直接在任务里说出角色和范围最清楚。写完规则 Agent 不会自己跑起来——你写了张 健身计划贴在墙上，肉也不会自己掉，道理一模一样。

6. 多处都配了模型，到底谁说了算？

对每个设置项，Codex 按下面的顺序解析，就四条，记不住就背下来：

1. 自定义 Agent TOML 中的值（最大的）；
2. 新建子 Agent 时显式指定的值；
3. config.toml 中对应的 [agents] 默认值；
4. 父 Agent 的值（最后兜底的）。

所以 reviewer.toml 里焊死的固定模型，优先于新建时传入的模型；code_explorer.toml 没写模型，就能够用新建时指定的模型。啥都不指定，才轮到全局默认或继承父 Agent。

结合项目来看，这也是我区分"固定角色"和"动态角色"的原因：固定职责放进 TOML，随任务变化的模型选择留在调用处。跟公司考勤一个道理——规则是规则，执行是执行，中间隔着八百个心眼子。

7. 验证设置与排错

7.1 先查语法

先检查 TOML 语法，路径换成你自己的文件：

python3 -c 'import tomllib; tomllib.load(open("/Users/你的用户名/.codex/agents/reviewer.toml", "rb")); print("TOML OK")'

7.2 再开新任务试

打开一个新的 Codex 任务，试一下：

请采用 reviewer 只读检查当前分支，列出有证据的风险。

7.3 三大经典翻车现场

遇到问题按顺序查，别慌，慌也没用：

• unknown agent_type：先确认文件位置、name 和 TOML 语法；在新任务里重试，还识别不了就重启 Codex。重启解决不了的问题，就再重启一次，这是程序员最后的倔强。
• 模型没有按预期切换：先看角色 TOML 是否已固定 model 或 model_reasoning_effort，再看新建时指定值和 [agents] 默认值。层层排查，跟查户口一样，一个都不能放过。
• 角色能启动却不能写入：角色名称或 sandbox_mode 不会自动授予权限，以当前任务的实际工具权限和审批设置为准。说白了，给了你"评审员"的头衔，不代表你就有批款的权限。

至此，最小设置就齐了：config.toml 给入口设置默认值，角色 TOML 描述专长，AGENTS.md 规定调用时机。建议先从一两个职责清楚的 Agent 开始，确认调度和模型都生效了，再慢慢加角色。别一上来就配十个八个，最后自己都分不清谁是谁——那场面，比公司开全员大会还混乱，台上讲的是 Java，台下写的是 Python。

理解这一步时，P.S. 无意间发现了一个巨牛的人工智能教程，很通俗易懂，对AI感兴趣的朋友强烈建议去看看，传送门（链接已移除）

从实现思路看，总的来说，Codex适合结合实际项目边做边理解。先抓住核心思路，再逐步补上细节和边界处理，最后效果会更稳定，也更容易复用。