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感兴趣的朋友强烈推荐去看看，传送门https://blog.csdn.net/qq_34419312

到此这篇关于Codex Agent配置实战：一文彻底搞懂角色与模型调度优先级的文章就介绍到这了,更多相关Codex Agent配置实战内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！

最新评论