Codex 使用指南

搜索全站

输入关键词开始搜索。
页面更新：事实核验：

概念

Subagents

Subagent 的价值不是“看起来并行”，而是隔离上下文、分离职责、让主线程保持整合和最终判断。

是什么

它是什么

Subagent 是被分配明确子任务的代理。它会执行自己的 model / tool work，可以做只读调查、审查、并行测试或互不重叠的实现切片。Codex app 会显示每个 subagent 的独立线程，并把结果摘要返回主线程，方便查看进度与整合。

不要假定 subagent 自动继承主线程的完整私密对话历史。主线程应显式传入目标、必要上下文、允许和禁止的写域、输出格式及验收标准，只提供完成子任务所需的信息。本地 custom agents 可以配置不同的 model、config 与 instructions，但其权限和可用工具仍受当前环境、沙箱、审批与组织策略约束。

flowchart LR A["主线程定义目标"] --> B["Agent A: 只读审查"] A --> C["Agent B: 测试缺口"] A --> D["Agent C: 文档/可维护性"] B --> E["主线程整合"] C --> E D --> E E --> F["统一验证和最终判断"]
Subagent 只负责边界清晰的子任务；主线程保留目标、取舍和最终验收。

何时使用

什么时候用 / 不用

  • 适合只读审查、并行资料检索、互不重叠的测试、独立实现切片。
  • 不适合共享同一文件的高频编辑、需要实时产品判断、权限边界不清的外部操作。
  • 主线程责任整合结果、处理冲突、决定最终方案、给用户报告证据。
三个小黑在互不重叠的写域内完成窄任务，主线程把结果缝合后交给最后一道统一验证
图意：并行的前提不是“多派人”，而是任务足够窄、写域互不重叠；主线程必须整合真实工作区状态，并用同一套标准完成最终验证。

示例

可复制示例

请用并行 subagents 审查当前分支。
Agent 1: security risks，只读，不改文件。
Agent 2: missing tests，只读，不改文件。
Agent 3: maintainability，只读，不改文件。
最后由主线程整合 findings。

协作关系

Worktree 与 Subagent 如何配合

Worktree 隔离 Git checkout 和工作目录；Subagent 隔离上下文、职责和写域。两者可以组合，但不能互相替代：独立目录不会自动消除逻辑冲突，独立代理也不一定拥有自己的 Worktree。同一工作区内的文件修改通常彼此可见，但文字结论、风险和未验证项仍必须明确回传，由主线程检查真实 diff、整合结论并统一验收。

Worktree解决目录与 Git 状态干扰适合并行试验和后台任务仍共享仓库元数据与外部资源
Subagent解决上下文与责任边界适合只读审查或互斥写域主线程保留整合与最终判断

单独阅读 Worktrees 指南

共享 contract、同一文件或强依赖任务仍应串行；并行拆分方式见 Issue lanes。

委派契约

Subagent 任务合同

Subagent 最常见的失败是边界不清：多个代理同时改同一批文件，或者把需要主线程判断的产品决策交出去。给 subagent 的任务应当像小型工单。

输入

显式给目标、仓库路径、必要背景、只读或可写范围、必须读取的文件、禁止触碰的路径和验收标准；不要依赖它猜测主线程历史。

输出

要求固定格式：findings、改动文件、证据、风险级别、建议修复、未验证项，并把文本结果回传主线程。不要只让它“看看”。

整合

主线程负责检查共享文件的真实状态、去重、冲突处理、最终判断和用户报告。Subagent 的摘要和结论不是自动真理。

第三方模型路由

用 OpenCodex 调用 Luna 子代理

先分清责任：OpenCodex 是第三方本地 provider proxy。它可以把 gpt-5.6-luna 放进 Codex 的 subagent model override 清单，并注入委派指引或同步新任务的原生 [agents] 默认值；它不是逐次 spawn 的代理侧路由器，也不会替你触发委派。需要逐次、可审计地指定 Luna 时，仍应让 Codex 在 spawn_agent 调用中显式传入 model override。

# 需要 Node.js 18+；先审查第三方包，再在测试环境安装
npm install -g @bitkyc08/opencodex
ocx init
ocx start
ocx gui
1. 准备路由

安装后运行 ocx init、ocx start 和 ocx gui。在 Models 确认 bare native id gpt-5.6-luna 已启用；在 Subagents 把它放进最多五个 featured models。

2. 设置委派

在 Dashboard 的 Sub-agent delegation 选择 Luna 和 reasoning effort，开启 OpenCodex multi-agent guidance。需要让新建 Codex 任务默认采用该子代理时，再启用 Use as native Codex subagent defaults。

3. 同步并新建任务

运行 ocx sync --restart-codex，检查 ocx status 与 ocx v2 status，然后新建 Codex 任务。已有任务不会自动换用新默认值。

也可以把下列顶层字段合并进 ~/.opencodex/config.json；syncCodexSubagentDefaults 是可选开关，不会自动创建 subagent：

{
  "subagentModels": ["gpt-5.6-luna", "gpt-5.6-terra", "gpt-5.6-sol"],
  "injectionModel": "gpt-5.6-luna",
  "injectionEffort": "medium",
  "syncCodexSubagentDefaults": true
}

主线程真正委派时，模型 override 必须出现在 spawn 调用里。完整历史 fork 会继承父模型并拒绝 model / effort override，因此要用 fork_turns: "none"（或明确的部分历史）；由于子代理不继承完整历史，message 必须包含可独立执行的目标、上下文、边界和验收：

spawn_agent({
  "task_name": "routine_checks",
  "agent_type": "worker",
  "fork_turns": "none",
  "model": "gpt-5.6-luna",
  "reasoning_effort": "medium",
  "message": "在共享工作区只读检查目标模块；返回 finding、证据路径和未验证项。"
})

给 Codex 的可复制请求：

请把边界清晰、成本敏感的检查交给 Luna subagent。
调用 spawn_agent 时显式设置 model="gpt-5.6-luna"、
reasoning_effort="medium"、fork_turns="none"；
子代理只读，主线程核对真实文件并完成最终验收。
  • bare id 优先从原生 Codex / ChatGPT 父代理委派时，优先使用 gpt-5.6-luna。OpenCodex 不能替账号增加模型权限；按 OpenAI 当前说明，Plus、Pro、Business 与 Enterprise 可在 Codex 选择 Luna。
  • 用户配置仍优先syncCodexSubagentDefaults: true 只会尝试为新任务同步原生默认值，不覆盖用户已有的 [agents] 默认键。配置显示 sync 已开启，不等于写入已成功；应在同步后核对 OpenCodex 日志、Codex 配置和实际 child model。
  • 先确认 v1 / v2OpenCodex 的 base/default 模式中，Sol 与 Terra 使用 v2，Luna 使用 v1；强制 v2 才会让所有模型都走 v2。模式修改只影响新任务。Luna 的精确 effort 阶梯最高为 max，不提供 ultra。
  • v2 加密任务边界只有原生父代理向非原生 routed provider 委派、且 v2 task body 仅含加密内容时，才会出现这一限制；bare gpt-5.6-luna 不属于该外部 provider 场景。遇到 unreadable_encrypted_agent_task 时，改用 bare native Luna，或运行 ocx v2 mode v1 后新建任务进行异构 provider 委派。
  • 成本仍取决于 tokenLuna 的 API 标价已于 2026-07-30 下调 80%，但 reasoning effort 越高通常消耗越多 token。先用 medium；只有代表性任务证明质量收益时再升到 max。价格详情见 Terra / Luna 降价。
  • 恢复原生配置测试结束可运行 ocx stop 停止代理并恢复原生 Codex，或用 ocx restore 只恢复配置。先备份并审查 provider 凭据、账号与服务条款边界。

（外部链接）OpenCodex 子代理界面 · （外部链接）配置参考

模式

推荐和不推荐的拆法

推荐：并行只读审查

请并行审查当前分支，但不要改文件。
Agent A: 查安全和权限风险。
Agent B: 查测试缺口和回归风险。
Agent C: 查文档、命名和可维护性。
每个 agent 返回：finding、证据文件、严重程度、建议。

推荐：互不重叠实现

Agent A
Goal: 补齐一页指南的案例标签。
Writable scope: 只改 docs-page.html。
Forbidden: CSS、导航、Git 操作、其他页面。
Required output: changed files、局部检查、未验证项。
Wait point: 共享锚点未由主线程确认时停止。

Agent B
Goal: 为语义校验器增加负向测试。
Writable scope: 只改 tests/test_check_site.py。
Forbidden: 生产校验器、HTML、Git 操作。
Required output: red evidence、测试结果、缺口。
Wait point: parser contract 变化时停止。

Integration owner: 主线程；等待两者返回后检查真实 diff，
按依赖顺序集成并统一运行 make check。

不推荐：共享核心文件

不要让多个 subagent 同时改同一个状态管理文件、同一个数据库 schema、同一个 API contract。冲突成本高，主线程很难判断谁对。

不推荐：外部写操作

不要让 subagent 独立创建 release、改生产配置、推送分支或调用有副作用的 MCP。外部写操作应由主线程显式确认。

Bad split → repaired split

Bad:
三个 subagents 同时修改共享 schema、同一页面和校验器，然后各自提交。

Repaired:
1. 共享 schema / API contract 由主线程串行完成并验证。
2. 不同任务使用独立 Worktree，避免干扰 Local checkout。
3. 同一任务内只把互斥写域交给不同 subagent；共享文件保持串行。
4. 每个 subagent 在 wait point 返回文件和证据，不执行 Git 操作。
5. 主线程更新依赖、检查真实 diff、统一验证和集成。

真实实例

真实实例：历史复合案例

历史复合案例完整案例的 Worktree 摘录

请求：在保留主工作区既有修改的前提下，让执行者完成互不重叠的文档切片。角色：主线程选择 base、登记隔离目录、整合 Git；subagent 只修改被分配页面并返回证据；独立 reviewer 只读检查合同与 diff。

写域：按互不重叠的页面组分配；共享契约和校验逻辑保持串行。
验证证据：changed files、局部检查、真实 diff、主线程全站检查。
重要恢复：主 checkout 有无关 dirty 修改时不清理或覆盖，改用隔离写域。
教学规则：只有依赖、review、验证和授权满足后，主线程才可集成。
停止条件：写域重叠、基线过期、依赖/资源不足或外部写入未授权。

这些是已核验边界与条件式教学规则的组合，不表示具体 lane 拓扑或每一步发生在同一次任务。完整的请求、Goal、授权、PR 与 receipt 见 团队协作历史复合案例。