给 Codex 增加“代码分析员”“评审员”等角色时，最容易混淆的是：角色写在哪里、模型由谁决定，以及写好文件后为什么 Agent 没有自动运行。
我把本地配置归纳为三层：
| 文件 | 职责 |
|---|---|
~/.codex/config.toml | 设置入口 Agent 的默认模型和子 Agent 的全局选项 |
~/.codex/agents/*.toml | 定义一个可调用的角色，也可以固定该角色的模型 |
AGENTS.md | 规定任务如何分派、何时使用某个角色 |
TOML 定义角色，AGENTS.md 定义调度。 创建一个角色文件，并不等于启动了一个常驻 Agent。下面用一套最小配置把这三层串起来。
1. 设置入口 Agent 的默认模型
编辑 ~/.codex/config.toml：
model = "gpt-6-sol"
model_reasoning_effort = "medium"
[agents]
max_concurrent_threads_per_session = 3
前两项是入口任务的默认模型与推理强度。max_concurrent_threads_per_session 限制同时打开的子 Agent 线程数，不包含入口 Agent。这里的 3 只是便于入门的示例，按任务量和可用资源调整即可。
模型名称和推理强度需要使用当前账号、客户端支持的组合；显式选择的任务模型也可能覆盖入口默认值。具体字段可查 Codex 配置参考。
2. 新建一个只读 Agent
个人角色放在 ~/.codex/agents/；只给一个项目使用的角色，放在该项目的 .codex/agents/。
例如，新建 ~/.codex/agents/code_explorer.toml：
name = "code_explorer"
description = "只读追踪代码调用链、数据来源和模块归属。"
sandbox_mode = "read-only"
developer_instructions = """
追踪实际调用路径，引用具体文件和代码证据。
只做分析，不修改文件。
"""
每个独立 Agent 文件至少需要 name、description、developer_instructions。文件名最好与 name 一致，方便查找；Codex 识别角色时以 name 字段为准。
这个例子没有写模型，适合在创建 Agent 时按任务难度选择模型。
3. 固定模型：适合职责稳定的角色
如果一个角色总是执行同类任务，可以直接在角色文件中固定模型。例如 ~/.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 一起写。只固定模型、遗漏推理强度时，推理强度可能沿用其他配置层已经解析出的值；两者未必匹配。
4. 动态模型：让同一角色处理不同难度的任务
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 时还要提供具体任务；希望明确委派时，直接在任务中说出角色和范围最清楚。
5. 多处都配置了模型，谁生效？
对每个设置项，Codex 按下面的顺序解析：
- 自定义 Agent TOML 中的值；
- 创建子 Agent 时显式指定的值；
config.toml中对应的[agents]默认值；- 父 Agent 的值。
因此，reviewer.toml 已写入的固定模型，优先于创建时传入的模型；code_explorer.toml 没写模型，就可以使用创建时指定的模型。若什么都不指定，才继续使用全局默认或继承父 Agent。
这也是我区分“固定角色”和“动态角色”的原因：固定职责放进 TOML，随任务变化的模型选择留在调用处。官方 Subagents 文档给出了完整的配置层级。
6. 验证配置与排错
先检查 TOML 语法；将路径换成自己的文件：
python3 -c 'import tomllib; tomllib.load(open("/Users/你的用户名/.codex/agents/reviewer.toml", "rb")); print("TOML OK")'
再打开一个新的 Codex 任务，尝试：
请使用
reviewer只读检查当前分支，列出有证据的风险。
遇到问题时，按顺序检查：
unknown agent_type：确认文件位置、name和 TOML 语法；在新任务中重试，仍无法识别再重启 Codex。- 模型没有按预期切换：先看角色 TOML 是否已固定
model或model_reasoning_effort，再看创建时指定值和[agents]默认值。 - 角色能启动却不能写入：角色名称或
sandbox_mode不会自动授予权限；以当前任务的实际工具权限和审批设置为准。
至此，最小配置已经齐了：config.toml 给入口设置默认值，角色 TOML 描述专长，AGENTS.md 规定调用时机。先从一两个职责清楚的 Agent 开始，确认调度和模型生效后，再增加角色。
