P.S. 无意间发现了一个巨牛的人工智能教程，非常通俗易懂，对AI感兴趣的朋友强烈推荐去看看， 传送门https://blog.csdn.net/qq_34419312

1. 先聊聊我踩的坑

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

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

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

文件	职责
~/.codex/config.toml	设置入口 Agent 的默认模型和子 Agent 的全局选项
~/.codex/agents/*.toml	定义一个可调用的角色，也可以固定该角色的模型
AGENTS.md	规定任务如何分派、何时使用某个角色

一句话总结：**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