Codex Agent 配置实战：彻底搞懂角色与模型调度优先级

文章目录1. 先聊聊我踩的坑2. 设置入口 Agent 的默认模型2.1 前两项是啥2.2 第三项是啥3. 新建一个只读 Agent3.1 放哪儿3.2 写什么4. 固定模型适合职责稳定的角色5. 动态模型让同一角色处理不同难度的任务6. 多处都配了模型到底谁说了算7. 验证配置与排错7.1 先查语法7.2 再开新任务试7.3 三大经典翻车现场P.S. 无意间发现了一个巨牛的人工智能教程非常通俗易懂对AI感兴趣的朋友强烈推荐去看看 传送门https://blog.csdn.net/qq_344193121. 先聊聊我踩的坑给 Codex 加个代码分析员“评审员这种角色我以为跟点外卖一样简单想加什么点什么下单就完事。结果配完一看Agent 纹丝不动模型该换的没换代码该乱的还是乱。那一刻我深刻体会到了什么叫你以为你在配置其实你在给代码写情书——人家根本不回。”后来我把文档翻了个底朝天终于悟了Codex 本地配置就三层跟咱家三层小别墅似的一层住模型一层住角色还有一层管调度。问题是你永远不知道哪层说了算别墅越大吵架的人越多。我把这套配置归纳成一张表看完你就知道谁管谁了文件职责~/.codex/config.toml设置入口 Agent 的默认模型和子 Agent 的全局选项~/.codex/agents/*.toml定义一个可调用的角色也可以固定该角色的模型AGENTS.md规定任务如何分派、何时使用某个角色一句话总结**TOML 定义角色AGENTS.md 定义调度。**创建一个角色文件并不等于启动了一个常驻 Agent。这就跟你办了张健身卡肉不会自己掉一样。2. 设置入口 Agent 的默认模型编辑~/.codex/config.tomlmodel gpt-6-sol model_reasoning_effort medium [agents] max_concurrent_threads_per_session 32.1 前两项是啥前两项就是入口任务的默认模型和推理强度相当于给整个 Codex 定了个出厂设置。2.2 第三项是啥max_concurrent_threads_per_session限制的是同时打开的子 Agent 线程数不包含入口 Agent 自己。注意入口 Agent 本人不算数——这跟老板永远不算在加班人数里是一个道理。这里的3只是入门的示例值别当真。你以为你的项目能扛住 3 个并发先问问你的显卡答不答应再问问你的钱包答不答应。另外提醒一句模型名称和推理强度得用你当前账号和客户端支持的组合显式选择的任务模型也可能覆盖入口默认值。具体字段以官方配置参考为准。3. 新建一个只读 Agent3.1 放哪儿个人角色放~/.codex/agents/只给一个项目用的角色放那个项目的.codex/agents/。别问我为什么这么设计反正我没权限问。3.2 写什么比如新建~/.codex/agents/code_explorer.tomlname code_explorer description 只读追踪代码调用链、数据来源和模块归属。 sandbox_mode read-only developer_instructions 追踪实际调用路径引用具体文件和代码证据。 只做分析不修改文件。 每个独立 Agent 文件至少要有name、description、developer_instructions三件套缺一个就跟你出门忘带钥匙一样尴尬。文件名最好和name一致方便查找Codex 识别角色时以name字段为准。这个例子没写模型主打一个看人下菜碟创建 Agent 的时候任务简单就用便宜的任务复杂就用贵的灵活得很。4. 固定模型适合职责稳定的角色如果一个角色每天干的活一模一样比如永远只做代码评审那就在角色文件里直接把模型焊死省得每次创建还要纠结。例如~/.codex/agents/reviewer.tomlname 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 按下面的顺序解析就四条记不住就背下来自定义 Agent TOML 中的值最大的创建子 Agent 时显式指定的值config.toml中对应的[agents]默认值父 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