1. 主题概述（What）
openai-codex-cc 是一个为 Claude Code CLI 定制的插件，将 Codex CLI（OpenAI 的代码专项 AI 代理）嵌入 Claude Code 的工作流中，使其成为 Claude 的协作编程者。Codex 不是一个独立工具，而是以插件方式挂载在 Claude Code 会话中，通过 codex-companion.mjs 脚本桥接本地 Claude Code 和远程 Codex 运行时。这个方案值得研究的原因在于：它提供了一种”双 AI 分工”的工程实践范式——Claude 负责编排、分析和 review，Codex 负责具体的代码实现和深度 rescue 调查——并围绕这一分工构建了完整的接口协议和操作规范。
2. 架构/结构分析
插件目录结构
插件安装于 ~/.claude/plugins/marketplaces/openai-codex/plugins/codex/，核心组成：
- commands/：公开 slash 命令（用户可直接调用）
rescue.md：委托实现/调查任务（对应/codex:rescue）review.md：代码 review，基于 git diff（对应/codex:review）adversarial-review.md：质疑实现方式和设计假设（对应/codex:adversarial-review）setup.md：可用性检测 + Codex 安装引导status.md：当前/历史 job 状态查询result.md、cancel.md：结果获取和取消
- agents/：
codex-rescue.md（内部 subagent 定义，薄转发器） - skills/：
codex-cli-runtime、gpt-5-4-prompting、codex-result-handling（内部技能） - scripts/：
codex-companion.mjs（核心运行时桥梁，所有命令的底层实现）
companion 脚本子命令
| 子命令 | 用途 | 输出格式 |
|---|---|---|
task "<prompt>" | 委托 Codex 实现/调查任务 | stdout 原文 |
review [args] | 代码 review | 渲染文本 |
review --json [args] | 代码 review（结构化） | JSON（verdict/findings/severity/confidence） |
adversarial-review --json [args] | 对抗性 review（结构化） | JSON |
setup --json | 检测 Codex 是否就绪 | {"ready": true/false, ...} |
task-resume-candidate --json | 检测是否有可续接 thread | {"available": true/false} |
status [job-id] | 查询 job 状态 | 文本 |
Thread/Session 模型
每次 task 调用创建一个 Codex thread。--resume-last 续接 session 内最近一次 task thread（非全局历史）；不带该参数则开启全新 thread。通过 task-resume-candidate --json 可在调用前检测是否有可续接 thread，由此实现交互式询问（Continue / Start new）。
3. 设计哲学 / 核心思想（重点）
原则一：薄转发器（Thin Forwarder）
codex-rescue subagent 的设计原则是”一个 Bash 调用，返回 stdout 原文”。subagent 不读文件、不分析问题、不做任何独立工作——仅将用户请求转发给 companion 脚本，并把输出原样返回。这与传统 AI agent 的”工具调用 + 综合分析”范式完全相反。
为什么这样设计：Codex 本身具备强大的推理能力和工具调用能力（含内部 spawn_agent、multi_tool_use.parallel），它不需要 Claude 帮它拆解任务或做预处理分析。Claude 的过度介入只会稀释上下文、引入误解。薄转发器让 Codex 在自己的运行时中保持完整的上下文和自主性。
原则二：接口契约高于实现细节
公开 skill 接口（/codex:rescue、/codex:review）是规范合约，而 codex-companion.mjs 是实现细节。所有外部集成应通过公开接口，不直接调用 companion 脚本。
为什么重要：companion 是私有 API，未来可能变更。直接依赖私有 API 相当于依赖实现而非合约——当插件升级时，调用方会静默失效。在 HAT-259 实践中，task-end 执行阶段曾直接调用 companion.mjs，被识别为架构违规并记录为偏差（见 final.md Problems Encountered）。
原则三：角色分离——Claude 编排，Codex 实现
在 codex-execute 模式中，“Claude 永远不直接修改目标代码”是核心约束。Claude 的职责：给出清晰的任务描述（what，不要 how）、review Codex 的输出、对每条 finding 独立评估（applied/deferred/disputed）。Codex 的职责：按 plan.md 实现代码、决定是否启用内部并行（spawn_agent）。
可迁移的思想：这是”决策与执行分离”的系统设计原则——决策者（Claude）负责规格和验收标准，执行者（Codex）负责实现路径。（主观解读：类比微服务中的 orchestrator/worker 模式。）
原则四：评估独立性——disputed findings 是 review 的核心价值
多轮 review 中，Claude 对每条 Codex finding 的正确回应是三选一：applied（同意并修复）、deferred（同意但暂缓）、disputed（不同意，给出反驳）。Codex 可以回应反驳、坚持 finding 或撤回。
为什么重要：盲目接受所有 finding 会让 Claude 退化为”被动转录员”，无法发挥判断力。Codex 也会出错，尤其在理解业务约束和上下文方面。独立评估使两个 AI 的推理形成真正的交叉验证。
原则五：努力等级与成本的显式权衡
--effort none/minimal/low/medium/high/xhigh 是对”推理深度 vs 成本”的显式控制。[已核实：来自 codex-cli-runtime SKILL.md] 建议：document review Round 1 用 high（彻底分析），fix pass 用 medium（已知问题范围，无需重新探索）。
4. 核心机制详解
三层可用性检测（Availability Check）
以下检测适用于 codex-reviewer skill；codex-execute skill 仅含前两层（不含 setup —json 检测）。[已核实：来自各 skill SKILL.md]
# 层 1：插件安装（codex-reviewer 和 codex-execute 均有）
test -f "$PLUGIN_ROOT/scripts/codex-companion.mjs" || echo "FALLBACK: plugin not installed"
# 层 2：Node.js 可用（codex-reviewer 和 codex-execute 均有）
which node > /dev/null 2>&1 || echo "FALLBACK: node not available"
# 层 3：Codex 认证就绪（仅 codex-reviewer）
# 区分"插件存在"和"Codex 已登录"两个前置条件
node "$COMPANION" setup --json 2>/dev/null | grep -q '"ready":true' \
|| echo "FALLBACK: codex not ready (run /codex:setup)"任一层失败 → 输出以 FALLBACK: 开头 → 调用方立即降级到 Claude reviewer，不重试 Codex 路径。
三种使用模式（HAT 系统集成）
| 模式 | 触发场景 | 接口路径 | 输出格式 |
|---|---|---|---|
| document | design.md / plan.md review | /codex:rescue --fresh/--resume | 自由文本（[HIGH]/[MEDIUM]/[LOW] 前缀） |
| code | Phase 4 代码变更 review | companion review --json 直接调用 | 结构化 JSON（verdict/findings/severity/confidence） |
| code-adversarial | 质疑实现方式和设计假设 | companion adversarial-review --json | 结构化 JSON |
关键设计说明：code 和 code-adversarial 模式直接调用 companion --json，而非通过公开的 /codex:review 技能——这是 codex-reviewer skill 的设计决策，因为公开命令只返回渲染文本，不暴露 JSON 结构；而 severity/confidence 映射需要结构化数据。[已核实：来自 review.md 命令文档和 codex-reviewer SKILL.md]
多轮对话协议（document 模式）
- Round 1：
/codex:rescue --wait --fresh --effort high（全新 thread，彻底分析） - Claude 评估每条 finding → applied / deferred / disputed
- Round N+1：
/codex:rescue --wait --resume --effort medium（续接 thread，发送 Claude 响应摘要） - 终止条件：Critical = 0 且 Important = 0（不以
verdict: approve为准，Codex 可能在问题未解决时给出 approve） - 最大轮次：5 轮（含 Round 1）
轮次计数规则：document 模式每次调用算 1 轮；code 模式 + code-adversarial 模式合计算 1 轮（见 codex-reviewer SKILL.md Multi-Round Dialogue Protocol）。[已核实]
每轮结束后追加到 {task-folder}/codex-dialogue.md，格式：
---
## {YYYY-MM-DD} Round {N} — {mode}
**Verdict**: approve / needs-attention
**Codex Job ID**: {UUID}（从 companion stdout `[codex] Thread ready (UUID)` 解析）
**Findings**: Critical N, Important N, Suggestion N
**Claude Response**:
- Applied: [title] → [what changed]
- Deferred: [title] → [reason]
- Disputed: [title] → [rebuttal]jobId 出现在 companion 的 stdout（格式 [codex] Thread ready (UUID)），而非 Codex 的回复内容中。[已核实：来自 codex-reviewer SKILL.md]
Codex 内部并行能力
Codex 具备自己的并行执行机制，Claude 不需要替它拆分任务。[来源：codex-execute SKILL.md Codex Internal Parallelism 章节]
| 内部工具 | 说明 |
|---|---|
spawn_agent(agent_type, message) | 创建 worker 子 agent 处理独立子任务 |
multi_tool_use.parallel(tool_uses[]) | 并发调用多个工具（读文件、搜索等） |
wait_agent / send_input | 等待子 agent 结果 / 与其通信 |
Claude 的职责是给出清晰的 what（“实现哪些功能，按照这个 plan”），而不是拆解 how（“先读文件 A，再写文件 B”）。
5. 对 hatcloud 的启示
启示一：在 Phase 4 代码实现场景中，可以将整批 task 委托给 Codex，Claude 专注于编排与 review。
具体做法：在 task-execute 执行循环中，当 task 满足 codex-execute 条件时，通过 Skill("codex:rescue", "--wait --fresh --effort medium ...") 委托实现；Codex 完成后 Claude 做 code review；发现 Critical/Important 问题则通过 --resume 发起 fix pass。（主观解读：Codex 在自己的运行时中维护完整上下文，Claude 主 context 不被实现细节污染；注：此路径端到端验收尚未完成，见第 6 段局限。）
启示二：在 design/plan review 场景中，可以使用 Codex 的 document review 模式做多轮”对话式 review”。
具体做法：Round 1 --fresh --effort high 彻底分析，Claude 评估每条 finding 后通过 --resume 续接，将 applied/deferred/disputed 响应反馈给 Codex，Codex 对被 disputed 的 finding 进行回应和仲裁。（主观解读：对话式 review 能发现孤立 review pass 容易忽视的接口契约不一致和边界条件，因为 Claude 对 finding 的反驳本身也会暴露新的盲区。）
启示三：在长时间任务场景中，可以使用 --background 标志将 Codex 任务放入后台，Claude 继续响应用户。
具体做法：Bash({ run_in_background: true }) 启动 Codex subagent 后，Claude Code 后台 task 完成后可在会话中查看结果（具体通知机制依赖 Claude Code runtime 的后台 task 完成回调）。适合 design review、大型实现任务等耗时操作。
6. 局限与不足
Thread Identity 的并发风险：--resume-last 绑定的是”session 内最近一次 rescue thread”，而非特定 jobId。如果在多轮 review 进行中穿插执行了另一个 rescue 调用，--resume 会续接错误的 thread。多轮期间必须序列化所有 rescue 调用，限制了并发效率。
公开 skill 输出契约限制：/codex:review 和 /codex:adversarial-review 只返回渲染文本，不提供结构化 JSON。code 模式集成必须直接调用 companion --json，产生对私有 API 的隐式依赖。插件未来版本若修改 companion 接口，code 模式的集成会悄然失效。
端到端验收尚未完成：codex-execute skill 集成到 task-execute 的完整执行路径在 HAT-259 中延至后续任务，结论基于局部 dogfooding 实验。第 5 段启示一中的优势描述为预期推断，而非已验证的实测结论。
依赖外部服务：Codex 需要 OpenAI 认证（codex login），网络中断或 API 配额耗尽会触发 FALLBACK 降级。降级到 Claude reviewer 能保证任务不中断，但失去多轮对话和结构化 JSON 输出能力。
参考
- rescue.md 命令文档 — Tier 1
- review.md 命令文档 — Tier 1
- adversarial-review.md 命令文档 — Tier 1
- codex-rescue.md agent 定义 — Tier 1
- codex-cli-runtime SKILL.md — Tier 1
- codex-reviewer SKILL.md — Tier 1（本系统集成文档）
- codex-execute SKILL.md — Tier 1
- 2026-04-01-codex-runner final.md — Tier 1（本次实践记录）