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.tomlname 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规定调用时机。以上均为社区实践整理请以当前客户端版本与官方文档为准。