codex-plugin-cc 精读：Claude × Codex 协同的上下文与控制面设计
代码快照：v1.0.6 · 2026-08-21OpenAI 官方项目 · Apache-2.0🎯 这篇研究解决什么
codex-plugin-cc 不只是“在 Claude Code 里再调用一个模型”。它真正解决的是四个工程问题：谁做主控、什么上下文交给 Codex、谁可以写工作区，以及长任务如何追踪和续接。
本文先还原项目当前实现，再从其架构与行为边界中提炼可复用的协同工作法。重点不是比较两个模型谁更强，而是减少重复读文件、上下文搬运、双写冲突和无人负责的评审结论。
⚠️ 证据边界
本文基于 openai/codex-plugin-cc v1.0.6、提交 db52e28 的代码快照。研究时重新克隆上游并运行其测试，结果为 91 项通过、0 项失败。
一、先给结论：它是 Claude 主控下的 Codex 执行桥
codex-plugin-cc 的主从关系非常明确：
Claude Code 是控制面，Codex 是按需启动的审查者、执行者或接管者。
插件没有让 Claude 与 Codex 实时共享一个“大脑”，也没有建立双向自动同步。它把不同上下文需求拆成四条路径：
| 需求 | 入口 | 上下文策略 | 写入能力 |
|---|---|---|---|
| 只检查当前代码改动 | /codex:review | 新建临时 Codex review thread | 只读 |
| 带项目判据质疑方案 | /codex:adversarial-review | 新建临时 thread，并注入 focus 与结构化输出约束 | 只读 |
| 调查、实现、测试并继续修复 | /codex:rescue | 新建或恢复持久 Codex task thread | 默认可写 |
| 长讨论后把整段工作迁往 Codex | /codex:transfer | 一次性导入 Claude transcript，生成可恢复 Codex thread | 转移后由 Codex 决定 |
这四条路径最有价值的地方，不是命令数量，而是没有把所有任务都塞进一个永久膨胀的共享上下文。普通 review 用完即弃；连续执行才保留 thread；只有完整对话确实不可替代时才 transfer。
二、项目是什么
| 维度 | 当前事实 |
|---|---|
| 仓库 | openai/codex-plugin-cc |
| 定位 | 在 Claude Code 中调用 Codex 做代码审查、对抗审查、任务委派与会话转移 |
| 当前版本 | v1.0.6，2026-07-08 发布 |
| 许可证 | Apache-2.0 |
| 运行要求 | Node.js 18.18+；本机安装并完成认证的 Codex CLI |
| Codex 接口 | 本地 Codex App Server，而非插件自建的第二套 agent runtime |
| 工作区 | Claude 与 Codex 使用同一台机器、同一个仓库 checkout |
Claude Code 官方把插件定义为由 skills、agents、hooks、MCP 等组件组成的自包含扩展目录；该项目正好使用了其中三类：
commands/：提供/codex:*命令；agents/codex-rescue.md：把复杂任务转交给 Codex；hooks/hooks.json：记录会话身份、清理后台任务，并可选启用 Stop review gate。
插件内部的 Node.js companion runtime 再连接本地 Codex App Server。OpenAI 将 App Server 定义为面向深度客户端集成的协议层，提供认证、conversation history、approval、thread/turn 与流式事件；插件复用了这套原语，而不是通过 shell 文本抓取 Codex TUI 输出。Claude Code 插件参考 · Codex App Server
三、架构：两个 Agent，共享仓库，不共享全部上下文
这张图揭示了三个关键边界。
3.1 Claude 是编排者，不代表 Claude 必须亲自执行
Claude 主会话负责理解需求、保存讨论历史、选择命令、解释 Codex 结果。真正的仓库搜索、代码修改、测试和第二视角 review 可以交给 Codex。主控权与劳动量不是同一个概念。
3.2 Git 工作区是共享事实，不是隔离沙箱
插件把 App Server 的 cwd 指向当前仓库。Claude 与 Codex 看到的是同一份文件和 Git 状态，没有自动创建 worktree。优点是交接简单、结果立即可见；代价是两个写者并发修改同一 checkout 会产生竞态。
因此，可靠协作的第一条不是“多开几个 Agent”，而是：
同一时刻只有一个写者；另一个 Agent 只读、等待或评审。
3.3 状态按 Claude session 隔离
插件在 SessionStart 时记录 Claude session ID 与 transcript 路径，status、result 和默认 resume 会优先限定在当前 Claude session。SessionEnd 会终止该 session 仍在运行的 job 并清理索引。
所以 --background 表示“当前 Claude 会话内非阻塞”，不等于跨会话、跨机器的持久任务队列。需要真正长期运行或 CI 自动化时，应改用 Codex SDK、云端任务或 CI 集成，而不是把本地插件当作调度平台。
实现依据：session-lifecycle-hook.mjs · state.mjs
四、四条上下文路径分别解决什么
4.1 /codex:review：把 diff 交给 Codex 内置 reviewer
这个入口直接调用 App Server 的 review/start。OpenAI 官方 review 支持未提交改动、基准分支和指定 commit；插件当前暴露的是 working tree 与 base branch 两类目标。Codex Code Review · App Server review/start
当前行为：
- dirty working tree 默认审查未提交改动；
- clean working tree 默认对比推断出的主分支；
- thread 为
ephemeral: true； - sandbox 为
read-only； - 不接受 focus text，也不支持 staged-only / unstaged-only；
- 结果只报告 findings，不修改工作区。
它适合回答“这份 diff 有没有具体缺陷”，不适合回答“这个方案是否违反我们三个月前定下的项目原则”。
4.2 /codex:adversarial-review：把项目判据注入第二视角
对抗审查不是“更严厉的普通 review”。插件给 Codex 一份明确的攻击式提示词：质疑实现方向、假设、失败路径、回滚、并发、权限与数据风险，并用 JSON Schema 约束 verdict、severity、文件、行号、置信度和建议。
它仍然是只读临时 thread，但允许在命令末尾写 focus：
/codex:adversarial-review --background --scope working-tree \
重点核对是否违反项目既有契约、是否遗漏跨文件同步、是否把主观判断误写成硬规则；不要报告风格与命名问题。小 diff 会作为上下文直接提供；改动较大时，插件只给轻量摘要，让 Codex 在只读 sandbox 中自行检查目标 diff。这样避免把大段补丁先复制进桥接 prompt。
实现依据：adversarial-review.md · review-output.schema.json
4.3 /codex:rescue：真正把劳动交给 Codex
rescue 经由一个很薄的 Claude subagent 调用 companion runtime。这个 subagent 不应自己读仓库或解决问题，只负责整理并转发任务。首次调用创建持久 Codex task thread；后续可用 --resume 延续同一 thread，也可用 --fresh 明确开新线程。
最重要的安全事实是：
通过 rescue agent 发起的任务，除非用户明确要求只读诊断、研究或 review，否则默认带
--write，Codex 运行在workspace-write。
因此，任务说明必须明确写出目标、可改范围、禁止事项和验收标准。不要假设后台 Codex 会在危险动作前回到 Claude 里追问：插件创建 App Server thread 时使用 approvalPolicy: never，需要额外授权的动作应失败或绕回安全路径，而不是形成交互审批闭环。
模型与 reasoning effort 也只有 task/rescue 路径支持显式参数。若不传，插件沿用本地 Codex 配置；这比把易变的模型名写死在团队工作流里更稳。
实现依据：codex-rescue.md · codex.mjs
4.4 /codex:transfer：迁移完整会话，而不是实时同步
transfer 使用 App Server 的 external-agent import，把当前 Claude transcript 转换为一个带可见 turn history 的 Codex thread，并返回：
codex resume <session-id>源文件必须位于 ~/.claude/projects/ 且为 JSONL。这个路径限制能防止命令随意导入任意本地文件，但它不改变数据边界：完整 transcript 中的需求、代码片段、日志和可能出现的敏感信息都会进入 Codex 会话。执行前仍应判断是否真的需要整段迁移。
还要特别注意：transfer 是一次性复制，不是双向共享。导入后 Claude 与 Codex 各自继续，只有 Git 工作区保持共享；后续对话不会自动互相同步。App Server external-agent import
五、可复用的协同工作法
下面这套规则是对前述实现边界的实践性归纳。它是工作法，不是插件强制执行的机制。
5.1 单一主控：上下文在哪里，控制面就在哪里
如果需求讨论、项目记忆和历史裁决主要沉淀在 Claude，Claude 就应保持主控；如果主要沉淀在 Codex，则不必为了使用这个插件强行把 Claude 设为主控。
不要同时维护两个不断增长、都自称权威的主会话。双主架构最常见的结果不是更聪明，而是：
- 同一决策被解释两遍；
- 两边各自持有不同版本的约束；
- 发现冲突后，不知道哪一份结论应覆盖另一份；
- 为同步上下文消耗的成本超过第二模型带来的收益。
5.2 Claude 做判断，Codex 做劳动
当 Claude 主会话承载需求历史与项目裁决，而 Codex 负责仓库执行时，职责可以这样划分：
| 角色 | 主要职责 |
|---|---|
| Claude | 明确目标、非目标、历史裁决、风险边界和验收标准；裁决 Codex finding 是否应采纳 |
| Codex | 阅读仓库、调查根因、修改文件、运行测试、做机械 sweep、产生可核验结果 |
| Git 与测试 | 提供双方共同的当前事实，不依赖任何一方对旧对话的记忆 |
| 用户 | 批准提交、推送、删除、部署及其他高影响动作；对最终结果做接受判断 |
“判断”和“劳动”不是模型能力排名，而是上下文归属。Codex 可以给出逻辑自洽的修改，但如果它没有收到项目历史，就无法凭空知道某条 MUST 为什么不能降级、某个示例为什么只作启示而非枚举。
5.3 Plan 是委派合同，不是文件内容的复制品
给 Codex 的 plan 应包含：
- 目标：解决什么问题；
- 范围：允许修改哪些路径；
- 约束：不能改变什么行为；
- 验收：运行哪些检查，看到什么才算完成；
- 交付：列出改动文件、验证结果与残余风险。
不要为了写 plan 先把大段源码、日志和文档复制进 Claude 上下文。告诉 Codex 去哪里读、用什么判据判断，通常更精确，也减少重复搬运。
5.4 Focus 写项目不变量，不写“仔细一点”
adversarial-review 已经负责“怀疑”。focus 应补充 Codex 从 diff 推不出来的内容，例如：
- 哪些约束是不可降级的项目契约；
- 哪些模块发生规则变化时必须同步；
- 哪些曾被明确拒绝的方案不能重新引入；
- 哪些检查器只能保持 advisory，不能升级成 hard error；
- 哪类建议属于风格噪音，不应报告。
一份高质量 focus 相当于把维护者判断压缩成 review rubric，而不是把全部历史对话导入第二个模型。
5.5 Background 是上下文准入控制，不只是速度选项
非平凡任务默认后台运行的核心收益，是 Claude 当前 turn 不等待并吞入完整执行输出。需要时再用：
/codex:status
/codex:result <job-id>
/codex:cancel <job-id>这让进入主会话的是“最终结论与必要证据”，而不是每条搜索、命令和测试日志。等待多久是延迟问题；把多少无复用价值的工具输出带回主上下文，才是上下文工程问题。
六、推荐的三段式闭环
6.1 第一步：Claude 定义交接包
/codex:rescue --fresh --background \
在 <路径> 解决 <问题>。允许修改 <范围>；不得改变 <边界>。\
完成后运行 <验证命令>，并报告改动文件、实际结果和未验证事项。\
不要提交、推送或扩大任务范围。同一问题继续修复时使用 --resume；任务目标改变时使用 --fresh。不要让一个长期 task thread 混入多个无关目标。
6.2 第二步：Codex 自证，Claude 只读关键结果
Codex 应给出：
- 实际修改了什么；
- 运行了什么验证；
- 哪些结论是事实，哪些只是推断；
- 哪些风险仍需人工判断。
Claude 复核当前 git diff、验证摘要和项目裁决，不需要重新扮演第二个执行者。若结果不完整，优先让同一 Codex thread 继续补证，而不是 Claude 重新从头调查。
6.3 第三步：把“代码正确”与“方向正确”分开审
普通缺陷检查：
/codex:review --background --scope working-tree契约、架构或高风险改动：
/codex:adversarial-review --background --scope working-tree <项目不变量与风险重点>Codex 的 finding 是证据输入，不是自动执行指令。Claude 或维护者必须判断：finding 是否真实、是否属于本次范围、是否与已确立路线冲突。未经确认，不应因为 reviewer 给出建议就自动修改。
七、最容易踩的边界
7.1 review 不能带 focus
/codex:review 映射 Codex 内置 reviewer，传 focus 会直接报错。需要定向质疑时用 adversarial-review，不要把二者理解成同一命令的“普通档/高级档”。
7.2 rescue 默认可写
只想研究、诊断或审查时，任务中必须明确写“只读，不修改文件”。否则 rescue agent 的默认行为是加入 --write。
7.3 Background 不允许双写
Codex 在后台改文件时，Claude 不应同时编辑相同 checkout。可以继续讨论或读取无冲突信息，但真正修改应等待当前写任务结束或先取消它。
7.4 Transfer 不是默认交接方式
完整 transcript 信息量最大，也最容易带入过时讨论、无关日志和敏感内容。只有“关键决策主要存在于对话、压缩成 brief 会显著失真”时才值得 transfer。多数任务使用一份自足 brief 更清晰。
7.5 Stop review gate 不是安全证明
/codex:setup --enable-review-gate 会在 Claude 准备停止时审查上一轮是否真的产生了代码改动，并依据 ALLOW / BLOCK 决定是否放行。它能兜住“Claude 临时自己改了文件却没复核”的场景，但仓库 README 明确警告：gate 可能形成长时间 Claude/Codex 循环并快速消耗额度。
因此更稳的使用方式是：
- 默认保持关闭；
- 只在高风险、有人监控的短会话中启用；
- 不用它替代测试、Git diff、权限边界和人工验收；
- 会话结束前确认没有仍在运行的 background job。
7.6 Changelog 不是完整版本史
当前仓库的 CHANGELOG.md 只记录 1.0.0，而实际版本已到 1.0.6。排查命令差异时应查 GitHub release、tag 与提交历史，不能只读 changelog。
八、项目设计的优点与限制
| 设计 | 优点 | 限制与使用含义 |
|---|---|---|
| Claude Code 作为单一控制面 | 用户不必在两个终端复制粘贴普通任务 | Codex 作为主控的用户会觉得方向相反 |
| review 使用临时只读 thread | 上下文干净，不污染长期执行会话 | 不了解未显式传入的历史裁决 |
| rescue 使用持久 task thread | 可连续调查、修改和复核 | 长 thread 仍会积累旧假设，应按任务切分 |
| background job + status/result | 长任务不阻塞主会话，过程可追踪 | job 生命周期受本地 Claude session 约束 |
| transfer 导入完整会话 | 复杂前情无需人工复述 | 单向、信息面大、需要额外隐私判断 |
| 共享本地 Codex 配置与认证 | 无第二套账户与 runtime 配置 | 本机配置漂移会直接改变插件行为 |
| Stop review gate | 可自动阻止带明显问题的结束动作 | 可能循环、误阻塞，也不是确定性安全边界 |
这个项目最成熟的地方，是把“第二模型”从一个模糊概念拆成了审查、对抗审查、执行续接和完整迁移四种不同协议。它最明显的限制也来自同一选择：这是 Claude Code 的 Codex companion，不是一个对称的双 Agent 调度平台。
九、什么时候不该用它
- 任务只有一次小修改：单 Agent 完成并检查 diff，通常更快。
- Codex 本来就是主控：直接在 Codex 中工作，按需调用 Claude 做只读复核，比反向绕进 Claude Code 更自然。
- 需要两个 Agent 并行写代码：使用独立 worktree 或隔离 checkout；不要共享同一工作区并发修改。
- 任务必须跨会话、跨机器持续运行：使用 Codex SDK、云端任务或 CI，而不是依赖本地 Claude session。
- 对话包含不应迁移的数据：不要使用
transfer，改写成经过脱敏的最小交接包。 - 只有“想多一个模型看看”而没有独立判据：第二个模型往往只会重复第一份分析，不能自动带来有效审查。
十、最终判断：协同质量取决于交接协议，不取决于 Agent 数量
codex-plugin-cc 的核心贡献不是证明“Claude + Codex 一定比单模型好”，而是给出了一个可检查的交接协议：
- 只看代码，用临时只读 review；
- 需要项目判断，用带 focus 的 adversarial review；
- 需要劳动与连续修复，用可恢复的 rescue thread；
- 关键上下文无法压缩，才迁移完整 transcript；
- 所有路径共享一个 Git 事实源，但任何时刻只保留一个写者；
- 提交、推送、删除和部署仍由人类明确授权。
这套协同关系可以概括为：
Claude 负责带历史的判断，Codex 负责可验证的劳动；Git 保存当前事实，人类保留最终授权。
一旦目标、上下文、写权限和验收责任都被明确，第二个 Agent 才是能力放大器。否则，多 Agent 只会更快地产生两份互相不完全理解的答案。
参考资料
- OpenAI：openai/codex-plugin-cc
- OpenAI：codex-plugin-cc v1.0.6
- OpenAI：Codex App Server
- OpenAI：Codex Code Review
- Anthropic：Claude Code Plugins Reference
- Anthropic：Claude Code Subagents
- Anthropic：Claude Code Hooks Reference
站内相关：AI Agent 完全指南 · AI Skills 与 Function Calling 指南 · learn-claude-code 精读 · 常用 Workflow 指南