Codex 分层用模型完整教程：让 GPT-6.1 Sol 拍板、GPT-6 Luna 跑侦察

发布日期：2026-10-21

Codex 分层用模型，是把复杂决策和重复执行交给不同模型：主线程用 GPT-6.1 Sol 负责理解需求、制定方案和最终判断，子代理用 GPT-6 Luna 负责查文件、读代码、跑检查和执行已经确定的小改动。OpenAI 文档在 2026 年 10 月明确把 Sol 定位为复杂、长流程工作，把 Luna 定位为清晰、重复、高频任务；但子代理会独立调用模型和工具，所以分层的价值是把推理预算放在关键节点，不能直接承诺总 Token 一定下降。

最近一条 X 上的 Codex 实践帖，把“主线用强模型、杂活交给轻量子代理”拆成了配置、角色文件和日常派活提示词。这个思路值得保留，但其中的额度和价格说法不应直接照搬。下面按 OpenAI 2026 年 10 月官方文档重写一套可验证的配置。

先理解分层：主线做判断，子代理做有限责任的工作

Codex 的子代理适合探索、测试、日志分析和摘要等读多写少的任务。官方文档提醒，每个子代理都会进行自己的模型推理和工具调用，因此并行任务的总消耗可能高于单代理；只有当工作可以清楚拆分，分层才有意义。

建议把职责拆成三层：

• 主线代理：澄清目标、决定架构、处理取舍、合并结论。
• 侦察代理：搜索文件、追踪调用链、读取日志、汇总现状，不改变代码。
• 修理代理：只执行主线已经确认的小改动，并运行针对性检查。

这种分工比“所有任务都自动派给 Luna”更稳。需求不清、涉及架构或需要权衡的任务，仍然应该留在主线；查找文件、整理测试输出和批量改文案，才适合交给子代理。

第一步：把主线和子代理的默认模型写进配置

Codex 的用户级配置文件是 ~/.codex/config.toml，项目级配置可以放在仓库内的 .codex/config.toml。官方配置文档说明，项目配置只有在项目受信任时才会加载，且更靠近当前目录的项目配置优先级更高。

先备份文件，再加入下面的最小配置：

# ~/.codex/config.toml
model = "gpt-6.1-sol"

[agents]
default_subagent_model = "gpt-6-luna"
default_subagent_reasoning_effort = "high"

截至 2026 年 10 月 20 日，OpenAI 对模型的官方分工是：GPT-6.1 Sol 用于复杂工作和长流程任务，GPT-6 Luna 用于清晰、重复、高频的任务。Luna 的推理强度可以从 High 起步，再按结果调整。

如果配置文件里还保留 gpt-5.5，应一并检查并替换。OpenAI 文档记录了 ChatGPT 登录的 Codex 会话在 2026 年 10 月 14 日停止提供 GPT-5.5；API Key 会话不受这次变更影响。具体可用模型仍取决于账号、客户端和工作区设置。

第二步：建立两个窄职责 Agent

默认模型只决定“没有明确指定时用什么”。如果希望工作方式稳定，还应给角色写清边界。官方自定义 Agent 文件要求至少包含 name、description 和 developer_instructions，模型和推理强度可以单独设置。

创建 ~/.codex/agents/scout.toml：

name = "scout"
description = "只读侦察：定位文件、追踪代码、读取日志并汇总证据。"
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
只做调查，不编辑文件。
先用搜索定位，再读取相关文件和符号，不要整库扫描。
返回相关文件路径、关键函数、发现的问题和证据；不要粘贴整段日志。
除非主线明确要求，不提出未经验证的修改方案。
"""

创建 ~/.codex/agents/fixer.toml：

name = "fixer"
description = "执行已经确认的小改动，并运行针对性检查。"
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
只执行主线已经确认的方案，保持改动最小。
不要改变架构，不碰无关文件；遇到方案没有覆盖的情况先停下报告。
改完只运行与改动直接相关的检查，并返回文件路径、改动摘要和检查结果。
"""

这里的“只读”是角色指令，不等于新的安全沙箱。OpenAI 文档明确说明，自定义 Agent 文件不能覆盖父会话的沙箱、审批策略和 MCP 设置；需要真正的权限边界时，要在父会话配置中设置只读或工作区权限。

第三步：用 AGENTS.md 固定派活规则

如果每次都手动解释分工，模型很快会回到“所有事情一起做”。把稳定规则写入项目根目录的 AGENTS.md：

## Agent 分工

- 主线负责理解需求、定方案、最终判断和汇总。
- 找文件、读代码、搜关键词、看日志和整理测试结果时，交给 scout。
- 方案已经确定的小改动交给 fixer。
- 子代理只返回结论、文件路径和证据，不粘贴原始输出。
- 多个子代理不能同时修改同一个文件。
- 架构决策、需求不清和有明显取舍的问题由主线处理。

官方最佳实践建议把重复的工作方式放进 AGENTS.md，把一次性的任务细节留在提示词里。这样做的重点不是让 Codex 盲目自动派活，而是让它在每次分工时都遵守同一组边界。

第四步：用一个可审计的提示词启动任务

一个适合分层执行的提示词，至少写清目标、上下文、约束和完成条件。可以直接改下面的模板：

任务：修复设置页保存后刷新丢失的问题。

执行顺序：
1. 先让 scout 查找设置页、保存接口、存储键和相关测试，最多返回 20 行结论。
2. 主线根据证据判断根因，列出准备修改的文件和验收标准。
3. 等我确认方案后，再让 fixer 执行最小改动。
4. 让 scout 运行最小相关测试并汇总结果。
5. 主线最后报告：改了什么、测试证明了什么、还有哪些风险。

约束：不改 API 形状，不重写无关模块，不提交或推送远程分支。
完成条件：刷新页面后设置仍保留，相关测试通过，工作区 diff 只包含本次改动。

如果任务可以独立拆成多个读操作，可以明确要求并行；如果多个代理会写同一个文件，就保持串行。官方文档把“并行探索、测试、分诊和摘要”列为适合的起点，同时提醒并行写入会带来冲突。

怎么判断真的省了，而不是多开了几个代理

先用同一个小任务做基线，再启用分层配置。比较时记录四项：主线完成时间、子代理数量、最终输出长度和用量面板显示的消耗。不要只看某一次回复变短，因为子代理会重复读取上下文并调用工具。

下面三种情况通常不适合派子代理：

1. 一句话就能回答的问题。
2. 需要主线持续掌握上下文的连续修改。
3. 多个代理必须同时编辑同一文件的任务。

打开 Codex 的 /status 查看会话状态，再展开子代理线程，核对它实际使用的模型和返回内容。验证重点是“主线是否少读了噪声、结果是否更容易审核”，而不是追求一个固定的额度倍数。

常见失效点

子代理仍然使用主线模型。 先检查 [agents] 的键名和 TOML 层级，model 必须位于 [agents] 之前；然后重启 Codex 并确认当前项目没有更近的 .codex/config.toml 覆盖用户级配置。

Luna 在账号里不可选。 OpenAI 文档说明，模型可用性取决于登录方式、计划、客户端和分阶段发布；不要把配置文件中的模型名当成授权。此时换成账号可用的轻量模型，或保留主线模型并缩小子代理任务。

“只读”代理改了文件。 角色指令不是沙箱。把父会话切换到只读权限，或在独立工作区验证；不要仅依赖 developer_instructions 保护重要仓库。

总消耗反而上涨。 减少子代理数量，限制返回长度，让侦察代理只返回路径、符号和证据；能由主线一次完成的小任务不要拆分。

这套方法的核心不是“让便宜模型接管一切”，而是让每种模型承担它更容易验证的工作。主线保留目标和取舍，子代理处理边界明确的重复劳动，最后由主线用测试和 diff 收口。

参考资料

• OpenAI Codex 模型说明（2026-10-20）：developers.openai.com/codex/models
• OpenAI Codex 子代理配置（2026-10-20）：developers.openai.com/codex/agent-configuration/subagents
• OpenAI Codex 配置基础：developers.openai.com/codex/config-file/config-basic
• OpenAI Codex 配置参考：developers.openai.com/codex/config-reference
• OpenAI Codex 最佳实践：developers.openai.com/codex/learn/best-practices
• 七牛云Token Plan（deepseek低至1.2折）：https://www.qiniu.com/ai/plan