Codex 本地自定义 Agent 配置：社区实践整理
说明：本文基于社区实践整理，非官方文档。文中涉及的配置字段、模型名称、优先级顺序与行为描述均来自社区经验，可能随客户端版本变化，请以当前客户端版本与官方文档为准，并自行验证。
给 Codex 增加“代码分析员”“评审员”等角色时，最容易混淆的是：角色写在哪里、模型由谁决定，以及写好文件后为什么 Agent 没有自动运行。社区实践中常把本地配置拆成三层结构。
第一层：~/.codex/config.toml
社区实践认为，该文件用于设置入口 Agent 的默认模型和子 Agent 的全局选项。示意示例：
model = "gpt-6-sol"
model_reasoning_effort = "medium"
[agents]
max_concurrent_threads_per_session = 3
注意：
gpt-6-sol等模型名仅为示意示例值，不代表真实可用或已验证的模型。
按社区说法，前两项是入口任务的默认模型与推理强度；max_concurrent_threads_per_session 限制同时打开的子 Agent 线程数，不包含入口 Agent。这里的 3 只是便于入门的示例，按任务量和可用资源调整即可。模型名称和推理强度需要使用当前账号、客户端支持的组合；显式选择的任务模型也可能覆盖入口默认值。具体字段请以当前客户端版本与官方文档为准。
第二层：~/.codex/agents/*.toml
社区实践建议：个人角色放在 ~/.codex/agents/；只给一个项目使用的角色，放在该项目的 .codex/agents/。
按社区说法，每个独立 Agent 文件至少需要 name、description、developer_instructions。文件名最好与 name 一致，方便查找；Codex 识别角色时以 name 字段为准。
只读角色示意示例：
name = "code_explorer"
description = "只读追踪代码调用链、数据来源和模块归属。"
sandbox_mode = "read-only"
developer_instructions = """
追踪实际调用路径，引用具体文件和代码证据。
只做分析，不修改文件。
"""
这个例子没有写模型，适合在创建 Agent 时按任务难度选择模型。
固定模型适合职责稳定的角色。例如 reviewer.toml：
name = "reviewer"
description = "只读检查代码正确性、回归和安全风险。"
model = "gpt-5.6-terra"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
优先报告有证据的实际风险，给出文件位置与触发条件。
不修改代码。
"""
注意：
gpt-5.6-terra等模型名仅为示意示例值，不代表真实可用或已验证的模型。
社区经验提示：固定模型时，建议把 model 和 model_reasoning_effort 一起写。只固定模型、遗漏推理强度时，推理强度可能沿用其他配置层已经解析出的值，两者未必匹配。
第三层：AGENTS.md
社区实践认为，AGENTS.md 规定任务如何分派、何时使用某个角色。TOML 定义角色，AGENTS.md 定义调度。创建一个角色文件，并不等于启动了一个常驻 Agent。
动态模型让同一角色处理不同难度的任务。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 时还要提供具体任务；希望明确委派时，直接在任务中说出角色和范围最清楚。
模型优先级：谁生效？
按社区说法，对每个设置项，Codex 按下面的顺序解析：
- 自定义 Agent TOML 中的值；
- 创建子 Agent 时显式指定的值；
config.toml中对应的[agents]默认值；- 父 Agent 的值。
因此，reviewer.toml 已写入的固定模型，优先于创建时传入的模型；code_explorer.toml 没写模型，就可以使用创建时指定的模型。若什么都不指定，才继续使用全局默认或继承父 Agent。
注意：以上优先级顺序为社区经验总结，可能随客户端版本变化，请以当前客户端版本与官方文档为准，并自行验证。
这也是区分“固定角色”和“动态角色”的原因：固定职责放进 TOML，随任务变化的模型选择留在调用处。
验证与排错
先检查 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不会自动授予权限；以当前任务的实际工具权限和审批设置为准。
工程分析（与社区事实分开）
从这套机制看，它把“角色能力”与“模型选择”解耦：TOML 描述稳定的职责边界，AGENTS.md 描述动态调度。固定模型适合审查、安全扫描这类职责稳定的角色；动态模型适合探索、分析这类任务难度跨度大的角色。优先级顺序实际上让角色 TOML 成为最高优先级的显式声明，调用处次之，全局默认和父 Agent 兜底。验证时优先检查 TOML 语法和角色 name，再检查模型优先级链，最后确认权限与审批设置——因为 sandbox_mode 不会自动授予权限。实践上，先从一两个职责清楚的 Agent 开始，确认调度和模型生效后，再增加角色。
至此，最小配置已经齐了：config.toml 给入口设置默认值，角色 TOML 描述专长，AGENTS.md 规定调用时机。以上均为社区实践整理，请以当前客户端版本与官方文档为准。