一句话看懂：掘金作者杨杨杨大侠在 2026 年 9 月发布实战文章，梳理了 Codex 本地自定义 Agent 的三层配置结构：config.toml 定默认模型、agents/*.toml 定义角色、AGENTS.md 规定调度时机。核心价值在于说清了“角色写在哪、模型谁决定、为什么 Agent 不自动跑”这三个高频踩坑点。
事件核心：发生了什么
这篇文章把 Codex 的本地自定义配置拆成三层。第一层是 ~/.codex/config.toml，负责设置入口 Agent 的默认模型（如 gpt-6-sol）与推理强度（medium），并用 max_concurrent_threads_per_session 限制子 Agent 并发线程数，作者示例值为 3。第二层是 ~/.codex/agents/*.toml，每个文件定义一个可调用角色，至少要有 name、description、developer_instructions，可选的 sandbox_mode 设为 read-only 即可实现只读分析；角色文件可不写模型（动态），也可固定 model 与 model_reasoning_effort（静态）。第三层是 AGENTS.md，只写“何时用哪个角色、按什么规则选模型”的调度逻辑。
文中明确了一条容易混淆的结论：创建一个角色文件不等于启动常驻 Agent，必须由任务显式调用。模型优先级顺序为：角色 TOML 中的值 > 创建子 Agent 时显式指定值 > config.toml 的 [agents] 默认值 > 父 Agent 值。作者建议把职责稳定的角色固定模型，把难度波动大的角色留给调用处动态选择。
为什么重要
多 Agent 协作正从演示走向日常工程实践，但配置层级混乱是当前工具链的普遍痛点。Codex 用“TOML 描述能力、AGENTS.md 描述编排”的分工，本质上把角色定义与调度策略解耦，这与业界主流的 Agent 编排思路一致。对闭源商业产品而言，这种配置化路线降低了用户自定义工作流的门槛，但也意味着模型选型、推理强度、沙箱权限被拆散在多个文件中，理解成本随之上升。目前公开信息显示，Codex 官方 Subagents 文档给出了完整配置层级，说明这已是被官方支持的稳定能力，而非临时技巧。
对用户/开发者/创作者的影响
对日常使用 Codex 的开发者，最直接的变化是：可以把“代码分析员”“评审员”这类角色沉淀成可复用文件，避免每次重复描述。只读角色配合 sandbox_mode 能降低误改代码的风险。但要注意，角色名称和 sandbox_mode 不会自动授予权限，实际写入能力仍受当前任务的工具权限与审批设置约束。对团队协作而言，把角色 TOML 与 AGENTS.md 纳入版本管理，可能成为提示词与工作流资产化的新形态。模型名称和推理强度必须使用当前账号、客户端支持的组合，显式任务模型也可能覆盖入口默认值。
AI 工具推荐
想把多个 AI 模型放在一个入口？
GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。
推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。
值得关注的后续
一是配置层级是否会被进一步简化，目前四层优先级对新手仍偏复杂，官方若提供可视化或校验工具会明显降低门槛。二是 AGENTS.md 这类编排文件是否会形成跨工具的通用约定，若被更多 AI 编程工具采纳，开发者资产的可迁移性将提升。三是模型固定与动态选择的边界实践，社区是否会沉淀出更明确的角色分类标准，值得观察。
来源：juejin
