在 Codex 中为本地开发环境添加“代码分析员”“评审员”等角色时，很多开发者容易遇到几个共性疑问：角色配置应该写在哪里？模型由哪一层决定？为什么创建了 Agent 文件，却没有自动运行？掘金近日一篇实战文章给出了较清晰的答案：Codex 的本地自定义 Agent 配置可以分为三层——TOML 定义角色，AGENTS.md 定义调度，而创建角色文件本身并不等于启动一个常驻 Agent。
这篇题为《Codex 本地自定义 Agent 与模型配置实战：TOML、AGENTS.md 和优先级》的文章，通过一套最小配置示例，梳理了 Codex 本地 Agent 的角色创建、模型选择与配置解析顺序，对正在尝试多 Agent 协作的开发者具有实际参考价值。
config.toml 负责入口默认值
文章首先从全局配置文件入手。开发者可以编辑 ~/.codex/config.toml，设置入口任务默认使用的模型与推理强度。例如：
model = "gpt-6-sol"：设置入口任务默认模型；model_reasoning_effort = "medium"：设置默认推理强度；max_concurrent_threads_per_session = 3：限制同时打开的子 Agent 线程数。
需要注意的是，这里的线程数限制不包含入口 Agent。文章中使用的 3 只是便于入门的示例，实际数值可以根据任务量和可用资源调整。模型名称和推理强度需要使用当前账号、客户端支持的组合；如果显式选择了任务模型，也可能覆盖入口默认值。
这一层配置的意义在于为 Codex 提供一个稳定入口。当后续角色没有单独指定模型时，系统可以继续回落到全局默认配置。
角色 TOML 描述专长与权限
在角色层面，Codex 区分了个人角色和项目角色。个人角色通常放在 ~/.codex/agents/ 目录；如果某个角色只服务于一个项目，则可以放在该项目的 .codex/agents/ 目录下。
文章给出了一个名为 code_explorer.toml 的示例角色，用于只读追踪代码调用链、数据来源和模块归属。该文件至少包含三个字段：name、description 和 developer_instructions。其中，name 是 Codex 识别角色的关键字段，文件名最好与 name 保持一致，方便查找。
示例中的 code_explorer 没有写模型字段。文章认为，这种配置更适合在创建 Agent 时按任务难度动态选择模型。例如，有时该角色只需要定位一个函数，有时又需要追踪跨模块调用链，不同任务对模型能力的要求并不相同。
对于职责更固定的角色，文章则给出了 reviewer.toml 示例。该角色用于只读检查代码正确性、回归和安全风险，并直接在角色文件中固定使用 gpt-5.6-terra 模型，推理强度为 medium。文章建议，如果固定模型，最好把 model 和 model_reasoning_effort 一起写入配置。若只固定模型而遗漏推理强度，推理强度可能沿用其他配置层已经解析出的值，两者未必匹配。
从这两个示例可以看出，TOML 角色文件更像是对某个 Agent 的“岗位说明书”：它说明这个角色擅长什么、能做什么、是否只读，以及是否需要固定模型。
AGENTS.md 决定何时调用与如何调度
文章进一步指出，仅有角色 TOML 文件，并不意味着 Agent 会自动运行。真正的调度规则需要写在 AGENTS.md 中。
以 code_explorer 为例，由于不同任务复杂度差异较大，文章建议在 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 时，仍需要提供具体任务。如果希望明确委派，直接在任务中说明角色和范围会更清楚。
模型优先级：角色固定配置优先于创建时指定
对于模型究竟由谁决定，文章给出了 Codex 的解析思路：每个设置项会按照配置层级解析。基于这一规则，如果 reviewer.toml 中已经写入固定模型，那么该模型优先于创建时传入的模型；而 code_explorer.toml 没有写模型，就可以在创建时使用指定模型。如果都没有指定，才会继续使用全局默认配置或继承父 Agent。
这也是文章区分“固定角色”和“动态角色”的关键原因：固定职责可以写进 TOML，而随任务变化的模型选择则留在调用处。对于需要稳定输出的评审、检查类角色，固定模型有助于保持一致行为；对于探索、分析类角色，动态选择模型则更灵活。
文章还给出了简单的验证方法：先检查 TOML 语法，例如使用 Python 的 tomllib 加载角色文件，确认配置格式无误；再打开新的 Codex 任务，尝试让 reviewer 只读检查当前分支并列出有证据的风险。如果遇到问题，则按顺序检查配置语法、路径、字段和模型支持情况。
整体来看，这套配置方法的核心并不复杂：config.toml 给入口设置默认值，角色 TOML 描述专长，AGENTS.md 规定调用时机。文章建议开发者先从一两个职责清楚的 Agent 开始，确认调度和模型生效后，再逐步增加角色。对于正在探索 Codex 多 Agent 协作的开发者而言，这种分层配置思路有助于减少角色不生效、模型不符合预期等常见问题。
原创文章，作者：点点，如若转载，请注明出处：https://www.dian8dian.com/codex-ben-di-agent-pei-zhi-zhi-nan-toml-agents-md-yu-mo
