给 Claude Code 接上 Codex Review 能力

这个配置是我自己折腾出来的。Claude Code 写代码很快，但我不希望第二个审查者也能动仓库文件，所以把 Codex 接成只读 reviewer。装完后，Claude Code 可以把 diff、commit、PR 或 OpenSpec change 派给 Codex 审一遍。

最后会得到三样东西：

1. 手动派审：对话里说“用 codex 审一下这次 diff”，Claude Code 通过 MCP 派给 Codex。
2. 专用 reviewer subagent：codex-reviewer 只有只读工具和 Codex MCP，不让审查过程污染代码。
3. OpenSpec verify 自动触发：跑 /opsx:verify 或 /openspec-verify-change 后，自动追加一次 Codex 独立审查。

---

适用场景

• 代码 review：合入前让 Codex 找 bug、对照项目红线。
• OpenSpec 产出物 review：检查 proposal、design、spec、tasks 和代码实现是否一致。
• 双 AI 协作：Claude Code 做主开发，Codex 做只读审查员，分歧点由人裁决。

---

前置依赖

• Claude Code (claude 命令可用)

• macOS (其他平台需调整 Codex CLI 路径)

• Python 3 (macOS 自带,或 brew install python3)

• Codex CLI(下面会装)

装 Codex —— 强烈推荐桌面版

如果你公司装了 EDR/防病毒(阿里、字节、腾讯等普遍部署),必须用桌面版。npm 版的 codex 是未签名 Node 脚本,会被 EDR 反复拦截弹”对你的电脑造成伤害”。

方式 A:Codex Desktop(推荐)

到 https://chatgpt.com/codex 下载,装到 /Applications/Codex.app。 内置的 CLI 在 /Applications/Codex.app/Contents/Resources/codex,带 OpenAI 官方签名 + hardened runtime。

方式 B:npm 全局(无 EDR 环境可用)

npm i -g @openai/codex

后续命令把 /Applications/Codex.app/Contents/Resources/codex 替换成 codex 即可。

登录 Codex

打开 Codex.app 或跑一次 codex 登录 ChatGPT 账户(Plus/Pro/Business 均可),或配 API Key。验证:

echo 'hi' | /Applications/Codex.app/Contents/Resources/codex exec --sandbox read-only -C /tmp -

能正常返回响应说明可用。

---

第 1 步:注册 Codex 为 MCP server

claude mcp add -s user codex /Applications/Codex.app/Contents/Resources/codex mcp-server

-s user = 用户级配置(只对你生效,不污染团队仓库)。验证:

claude mcp list | grep codex
# 期望:codex: /Applications/Codex.app/Contents/Resources/codex mcp-server - ✓ Connected

如果显示 ✗ Failed,先确认 Codex CLI 路径正确、Codex 已登录。

---

第 2 步:创建 codex-reviewer subagent

mkdir -p ~/.claude/agents

把下面这段保存到 ~/.claude/agents/codex-reviewer.md:

---
name: codex-reviewer
description: 用 Codex 做独立第二视角审查。适用场景:代码 review(diff/文件/PR)、OpenSpec 产出物 review(proposal/design/spec/tasks)。当用户说"审查/review/拷打/把把关/第二意见/找问题"且对象是代码或 spec 类文档时调用。
tools: mcp__codex__codex, mcp__codex__codex-reply, Read, Bash, Glob, Grep
model: sonnet
---

你是 Codex 审查的协调员。真正的审查由 Codex(通过 MCP 工具)完成,你负责准备输入、调度 Codex、整理产出。

## 工作流程

1. **明确审查对象**。主 agent 通常会传:
   - 一段 diff、文件路径列表、或 PR 编号 → 代码 review
   - 一个 OpenSpec change 目录、或 spec/proposal/design 文件 → 文档 review
   如不明确,先读 1-2 个关键文件确认范围,不要瞎猜。

2. **收集原始素材**。用 Read/Bash/Glob/Grep 把要审查的内容拿到手:
   - 代码:`git diff <ref>...HEAD`、相关源文件全文、可能用到的上下文(接口定义、调用方)
   - OpenSpec:proposal.md、design.md、specs/*/spec.md、tasks.md 的原文
   关键约束(如 CLAUDE.md 里的 Critical 规范)一并附上。

3. **调用 Codex**(`mcp__codex__codex`)。参数必须:
   - `sandbox`: `"read-only"`(防止它改文件)
   - `approval-policy`: `"never"`
   - `cwd`: 项目根目录
   - `prompt`: 见下方模板,把素材塞进去

4. **保留 threadId**,如需追问澄清,用 `mcp__codex__codex-reply` 带上 `threadId` 续问;每轮最多 2-3 次追问。

5. **整理报告**返回给主 agent,见下方输出格式。

## 关键原则

- **不要把主 agent 的分析、结论、倾向塞给 Codex**。只给原始素材 + 客观约束。Codex 要独立形成判断,否则就是附和而非第二意见。
- **不要替 Codex 过滤问题**。它说的所有问题原文带回,即使你不认同,在报告里标注"分歧点"让用户裁决。
- **不要让 Codex 改文件**。`sandbox: read-only` 是硬约束。
- 你自己**绝不**调用 Edit/Write —— 你没有这些工具。

## Prompt 模板

### 代码 review

请独立审查以下代码变更,目标项目是 <项目名/技术栈>。

[项目关键约束] <从 CLAUDE.md 摘抄相关红线条款>

[变更内容] <git diff 原文 或 文件全文>

[审查维度]

1. 正确性:逻辑错误、边界条件、空值/异常处理
2. 项目规范符合度:逐条对照上方约束
3. 数据安全:租户隔离、SQL 注入、越权
4. 可维护性:命名、抽象、复杂度
5. 测试覆盖:是否需要补测试

按”严重/重要/建议”三档输出问题,每条包含:文件:行号、问题描述、修复建议。 不要客气性褒奖,只列问题。如果某维度无问题,写”无”。

### OpenSpec 产出物 review

请独立审查以下 OpenSpec 变更产出物的质量。

[变更目标] <proposal.md 中的 why/what>

[产出物原文]

proposal.md

<内容>

design.md

<内容>

spec(s)

<内容>

tasks.md

<内容>

[审查维度]

1. 逻辑闭环:proposal 的目标在 spec 中是否完整覆盖
2. 一致性:proposal/design/spec/tasks 之间字段、术语、流程是否对齐
3. 完整性:必要场景(异常流、边界、并发、回滚)是否有定义
4. 可测试性:验收标准是否客观可验证
5. 任务可执行性:tasks 颗粒度合适、依赖清晰、有验收

按维度输出问题,每条包含:位置(文件:章节)、问题、修复建议。 不要客气性褒奖,只列问题。

## 输出格式(返回给主 agent)

Codex 审查报告

审查对象: <一句话描述> Codex 会话: threadId=<…>(如需追问可复用)

严重问题

• [文件:行号] <问题> | 建议: <修复方向>

重要问题

• …

建议项

• …

分歧点(可选)

• Codex 认为: <…>;我的看法: <…> — 请用户裁决

未覆盖范围

<列出 Codex 没看到的部分,避免主 agent 误以为已穷尽>

报告要紧凑,不要复述原文。

---

第 3 步:OpenSpec verify 自动触发 hook(可选)

如果你在用 OpenSpec(opsx:verify / openspec-verify-change 等 skill),让 verify 完成后自动追加一次 Codex 独立审查。

3.1 创建 hook 脚本

mkdir -p ~/.claude/hooks

把下面这段保存到 ~/.claude/hooks/opsx-verify-codex-review.py 并 chmod +x:

#!/usr/bin/env python3
"""
PostToolUse hook: 当 Skill 工具调用的是 opsx:verify / openspec-verify* 类时,
注入 additionalContext 指令,让主 agent 完成 verify 后再派 codex-reviewer
subagent 做一次独立 code review。

stdin: 标准 Claude Code hook 输入 JSON
stdout: 命中 → hookSpecificOutput JSON;未命中 → 静默退出。
"""
import json
import sys


def main():
    try:
        data = json.load(sys.stdin)
    except Exception:
        return

    if data.get("tool_name") != "Skill":
        return

    tool_input = data.get("tool_input") or {}
    skill = tool_input.get("skill") or tool_input.get("skill_name") or ""

    targets = {"opsx:verify", "openspec-verify", "openspec-verify-change"}
    if skill not in targets:
        return

    instruction = (
        "[opsx-verify-codex-review hook] verify skill 已执行完毕。"
        "你的最终响应必须再加一层 Codex 独立审查:\n\n"
        "1. 先按 verify 自己的工作流给出结论 (实现 vs change artifacts 的匹配情况)\n"
        "2. 然后调用 Agent 工具 (subagent_type=codex-reviewer),让 Codex 独立审查同一变更范围;"
        "prompt 中应包含: change 路径或 commit 范围、CLAUDE.md 的关键约束、要审查的代码文件\n"
        "3. 最终输出按三块组织:\n"
        "   ## verify 结论\n"
        "   ## Codex 独立审查\n"
        "   ## 分歧点 (如有) — 用户裁决\n\n"
        "Fallback: 如果 codex-reviewer subagent 在当前会话不可用 "
        "(Agent 工具返回 'Agent type not found'),改用 Bash 直接调 codex CLI:\n"
        "  /Applications/Codex.app/Contents/Resources/codex exec --sandbox read-only "
        '-C <repo根目录> -o /tmp/codex-review-output.md "<完整 prompt>"\n'
        "然后 Read /tmp/codex-review-output.md 拿结果。绝不允许走 npm 版 codex (会被 EDR 拦)。\n\n"
        "关键原则: 不要把 verify 自己的结论塞给 Codex,让它独立形成判断;"
        "两份结论分歧的地方,在'分歧点'里如实并列,让用户裁决。"
    )

    print(json.dumps({
        "hookSpecificOutput": {
            "hookEventName": "PostToolUse",
            "additionalContext": instruction,
        }
    }))


if __name__ == "__main__":
    main()

3.2 注册 hook 到 settings.json

编辑 ~/.claude/settings.json,在 hooks.PostToolUse 数组里追加(如果没有 hooks 或 PostToolUse 字段,先创建):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Skill",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /Users/<YOUR_USER>/.claude/hooks/opsx-verify-codex-review.py",
            "timeout": 10,
            "statusMessage": "Checking if opsx:verify → triggering Codex review..."
          }
        ]
      }
    ]
  }
}

注意路径要换成你自己的用户名。把 <YOUR_USER> 替换为 whoami 的输出。

3.3 激活 hook

settings.json 改完后,在 Claude Code 里输一次 /hooks(随便打开就关掉)即可热加载,无需重启会话。

---

验证

A. MCP 连接

claude mcp list | grep codex
# 期望: codex: ... mcp-server - ✓ Connected

B. Hook 脚本独立测试

echo '{"tool_name":"Skill","tool_input":{"skill":"opsx:verify"},"tool_response":{}}' \
  | python3 ~/.claude/hooks/opsx-verify-codex-review.py | python3 -m json.tool
# 期望输出含 hookSpecificOutput.additionalContext 的 JSON

echo '{"tool_name":"Skill","tool_input":{"skill":"writing-plans"},"tool_response":{}}' \
  | python3 ~/.claude/hooks/opsx-verify-codex-review.py
# 期望:无输出(静默退出)

C. 端到端

新开一个 Claude Code 会话,在某个 git 仓库里说:

用 codex-reviewer 审一下 HEAD 这个 commit

主 agent 应该派 codex-reviewer subagent,subagent 调 mcp__codex__codex 拿结果,最后输出三档(严重/重要/建议)报告。

---

怎么用(日常工作流)

1. 手动派审

用 codex 审一下当前 diff
让 codex-reviewer 看下这个 PR
让 codex 拷打一下这个 OpenSpec change

2. OpenSpec verify 自动触发

正常跑你的 verify 流程:

/opsx:verify
/openspec-verify-change

verify 完成后,主 agent 会自动追加 Codex 独立审查,输出三段对比:

## verify 结论
<verify skill 自己的结论>

## Codex 独立审查
<Codex 找到的问题>

## 分歧点
<两份结论不一致的地方,等你裁决>

3. 直接 Bash 调(应急)

如果 MCP/subagent 都没生效,主 agent 自己也能用 Bash 应急:

/Applications/Codex.app/Contents/Resources/codex exec \
  --sandbox read-only \
  -C /path/to/repo \
  -o /tmp/codex-review.md \
  "请审查 commit <SHA>: $(git show <SHA>)"

---

故障排查

弹窗”codex 将对你的电脑造成伤害”

EDR(企业安全软件)在拦截 npm 版未签名的 codex。解决:用 Codex.app 自带的签名 CLI(/Applications/Codex.app/Contents/Resources/codex),不要走 PATH 里的 npm 版。可顺手卸 npm 版:

npm uninstall -g @openai/codex

Codex 报错 “gpt-5-codex 模型不支持”

ChatGPT 账户无权访问该模型。不要在 codex exec 加 -m gpt-5-codex,让它走账户默认即可。

MCP / subagent 不生效

Claude Code 的 MCP 工具列表和 subagent 列表在会话启动时锁定。新装的 MCP server 或 subagent 文件,当前会话看不到。

• MCP:开新会话 / 重启 Claude Code

• subagent:开新会话 / 重启 Claude Code

• hooks:输入 /hooks 即可热加载(无需重启)

which codex 仍是 npm 版

claude mcp add 用的是绝对路径,不受 PATH 影响。但如果你日常想敲 codex 命令,可建一个软链(先卸 npm 版,免冲突):

npm uninstall -g @openai/codex
ln -s /Applications/Codex.app/Contents/Resources/codex /opt/homebrew/bin/codex

hook 注入了但主 agent 没派 codex-reviewer

可能 codex-reviewer subagent 没装上,或者本会话没加载到。检查:

ls ~/.claude/agents/codex-reviewer.md  # 文件存在?

存在但不工作 → 重启会话。hook 的 fallback 路径会让主 agent 改用 Bash 直接调 codex CLI,行为等价。

---

自定义

改 review 维度

编辑 ~/.claude/agents/codex-reviewer.md 的”Prompt 模板”小节,加你项目特有的红线(如某种命名约定、性能要求)。

改触发的 skill 名

编辑 ~/.claude/hooks/opsx-verify-codex-review.py,改这行:

targets = {"opsx:verify", "openspec-verify", "openspec-verify-change"}

加你自己用的 skill 名(比如 verify-implementation、code-audit)。

改成”verify 之前先 review”

把 hook 注册从 PostToolUse 改成 PreToolUse matcher=Skill,verify 就会先被 Codex 看一眼再跑。

改成”项目级配置”(团队共享)

把:

• ~/.claude/agents/codex-reviewer.md → <repo>/.claude/agents/codex-reviewer.md

• ~/.claude/hooks/opsx-verify-codex-review.py → <repo>/.claude/hooks/

• ~/.claude/settings.json 的 hook → <repo>/.claude/settings.json

• MCP 注册命令的 -s user 改 -s project

注意:团队成员需要每人都装 Codex.app(或 npm 版),且接受弹窗一次。

---

卸载

# 撤掉 MCP
claude mcp remove -s user codex

# 撤掉 subagent
rm ~/.claude/agents/codex-reviewer.md

# 撤掉 hook(手动从 ~/.claude/settings.json 删 matcher="Skill" 那段)
rm ~/.claude/hooks/opsx-verify-codex-review.py

---

设计要点(为什么这么做)

1. 为什么用 MCP server 而不是直接 Bash 调 codex:MCP 保留 threadId,reviewer 可以多轮追问澄清问题。Bash 路径每次新启动,无上下文。

2. 为什么 subagent 不给 Edit/Write 工具:reviewer 只该审,不该改。硬性切断避免它”顺手”修改文件污染主 agent 的工作。

3. 为什么 prompt 不带主 agent 的预判:你已经做了一遍分析,如果再告诉 Codex”我觉得这里可能有问题”,它会倾向附和而不是独立判断。给原始素材 + 客观约束就够。

4. 为什么 hook 用 PostToolUse 而不是改 skill 本体:不动 skill 文件,升级不冲突;hook 是配置,易开关;hook 的 additionalContext 是”指令注入”而不是”硬强制”,主 agent 还能根据情况判断要不要真跑(比如 verify 自己已经发现严重错误时可以跳过)。

---

这份配置在 macOS + Claude Code + Codex.app 0.131.0+ 环境下验证可用。 反馈与改进欢迎讨论。