Codex Plugin for Claude Code

这是什么？适合谁？

Codex Plugin for Claude Code 是 OpenAI 官方开源（Apache-2.0）的 Claude Code 插件，仓库地址 openai/codex-plugin-cc。它的价值主张很直接：让习惯 Claude Code 工作流的开发者，在不离开当前环境的情况下，把”审查代码”和”委派任务”这两类活交给 OpenAI Codex 去干，实现 Claude 与 Codex 双模型协作。

它提供的核心命令是一组 /codex:* 斜杠命令：/codex:review（普通只读审查）、/codex:adversarial-review（可定向挑战的对抗式审查）、/codex:rescue（把 bug 排查/修复任务委派给 Codex）、/codex:transfer（把当前 Claude 会话转成 Codex 线程继续）、以及 /codex:status、/codex:result、/codex:cancel 管理后台任务。它并不另起炉灶——底层复用你本机的 Codex CLI 和 Codex app server，用你已有的 Codex 登录态和配置。

适合谁：已经同时使用 Claude Code 和 Codex、想在一个界面里取两者之长的开发者；想用”另一个模型”给 Claude 的产出做交叉审查、减少单模型盲点的团队；以及想把手头修 bug 的活甩给后台任务、自己继续往前写的重度使用者。不适合谁：只用一个模型的人，或只想在终端裸跑 Codex CLI 的人——对他们来说直接 codex 更简单。

和同类方案对比：Claude Code 原生的 /review 是”Claude 审 Claude”，而 codex-plugin-cc 用 Codex 这个”异源模型”来做审查和委派，交叉验证能力是它不可替代的地方；和 claude-code-router 这类”路由切换模型”工具相比，本插件不是换模型，而是把 Codex 作为一个可委派、可后台、可迁移会话的”第二 Agent”；和直接开两个终端（一个 Claude 一个 Codex）相比，它省掉了上下文搬运的手工成本，/codex:transfer 还能把会话平滑接续过去。

使用前提：已安装并登录 Claude Code；本机要有 Codex（或愿意让插件帮你装）；需要一个 ChatGPT 订阅（含 Free）或 OpenAI API Key 来登录 Codex。

准备工作

1. 环境要求：Node.js 18.18 或更高（插件运行时依赖，README 明确要求）；已安装 Claude Code 并能在仓库里正常启动。

2. Codex 账号/密钥来源：使用本机 Codex CLI 的认证。要么用 ChatGPT 订阅（Free/Plus/Pro 均可，用量计入 Codex 使用额度），要么用 OpenAI API Key。登录方式：codex login 同时支持 ChatGPT 账号与 API Key 两种。定价与额度见 Codex pricing。

3. 安装 Codex CLI（可选，插件可代装）：如果本机还没有 Codex，可先 npm install -g @openai/codex；不装也行，/codex:setup 检测到缺失且 npm 可用时会询问是否帮你装。

4. 前置知识：熟悉 Claude Code 的 /plugin（插件系统）、/reload-plugins、斜杠命令与 /agents 子 Agent 概念；了解 Codex 的 codex resume 会话续跑概念（用于迁移后继续）。

5. 替代方案：只想切模型不改工作流 → claude-code-router；只想要 Claude 原生审查 → Claude Code 自带 /review；想完全在 Codex 里工作 → 直接用 Codex CLI / Codex IDE 扩展。本插件适合”留在 Claude Code + 借 Codex 之力”的场景。

快速上手（4 步）

第一步：添加 marketplace 并安装插件

在 Claude Code 里依次执行：

/plugin marketplace add openai/codex-plugin-cc
/plugin install codex@openai-codex
/reload-plugins

预期结果：插件加载后，/ 菜单出现 /codex:* 系列命令，/agents 里出现 codex:codex-rescue 子 Agent。

第二步：跑一次环境自检

/codex:setup

预期结果：报告 Codex 是否已安装、是否已登录。若未登录，按提示执行：

!codex login

登录（ChatGPT 或 API Key）后重新 /codex:setup，看到 “ready” 即就绪。

第三步：跑第一次只读审查

/codex:review

预期结果：Codex 对当前未提交改动做一次只读审查并给出意见（不改代码）。多文件改动可能较慢，建议加 --background 后台跑。

第四步：委派一个任务给 Codex

/codex:rescue investigate why the tests started failing

预期结果：任务经 codex:codex-rescue 子 Agent 交给 Codex 执行，完成后可查看结论。用 /codex:status 查进度、/codex:result 取结果。

常见踩坑

踩坑 1：后台 rescue 任务静默死亡、任务卡住

• 现象：通过后台 Bash 启动的 rescue 任务跑着跑着没动静了，/codex:status 一直不更新，像”卡死”（issue #432）。
• 原因：后台任务的 shell 进程树被回收（reap）后，Codex 子进程被连带终止，任务陷入 wedge 状态。
• 解决：优先用插件正式的 --background 参数而非手动 nohup/后台符号；升级插件到修复版本；用 /codex:cancel 清理卡住任务后重跑。

踩坑 2：多会话并发时共享 broker 被拆毁、其他任务中断

• 现象：同时开多个 Claude Code 会话跑 Codex 任务时，一个会话结束把共享的 broker 进程树带崩，导致其他会话正在跑的任务中断（issue #439、#623）。
• 原因：多会话共享同一个 broker 与状态生命周期，会话结束时触发了对共享资源的清理，误伤了他人任务。
• 解决：避免在多个会话里同时跑 Codex 后台任务，或串行执行；升级到修复了 broker 生命周期管理的版本。

踩坑 3：改了 model 配置却不生效

• 现象：在 config.toml 或 --model 里指定的模型没有真正生效，Codex 用了默认模型（issue #408）。
• 原因：启动 codex app-server 时未把 -c model="..." 参数正确传递，导致 options.model 被忽略。
• 解决：确认 config.toml 位置正确（用户级 ~/.codex/config.toml、项目级 .codex/config.toml），项目级配置需先信任该项目；仍不生效则升级插件。

踩坑 4：/codex:setup 提示 Codex 未就绪

• 现象：跑 /codex:* 命令报错，/codex:setup 显示 Codex 缺失或未登录。
• 原因：本机没有 Codex CLI，或 Codex 未登录（未跑 !codex login），或 Node 版本低于 18.18。
• 解决：npm install -g @openai/codex 装 CLI → !codex login 登录 → 确认 node -v ≥ 18.18 → 重新 /codex:setup。

踩坑 5：开启 review gate 后用量被快速耗尽

• 现象：开了 review gate 后，Codex/ChatGPT 的用量额度消耗异常快，会话陷入”Claude 写 → Codex 审 → 打回重写”的长循环。
• 原因：review gate 用 Stop hook 在 Claude 每次响应后都触发一次 Codex 定向审查，发现问题就阻止 stop，可能形成长期 Claude/Codex 往返循环（README 明确警告）。
• 解决：只在主动监控会话时用 /codex:setup --enable-review-gate 开启，用完 /codex:setup --disable-review-gate 关闭；不要无人在场时长期开启。

踩坑 6：/codex:transfer 迁移失败或源不可用

• 现象：transfer 报错，或迁移出的会话在 Codex 里打不开。
• 原因：源会话文件必须在 ~/.claude/projects 之下；较老版本的 Codex 不暴露 session import 能力。
• 解决：用插件自动提供的 transcript 路径（别乱指 --source）；升级 Codex 到支持 external-agent session importer 的版本再迁移。

踩坑 7：分不清审查命令会不会改代码

• 现象：担心 /codex:review 或 /codex:adversarial-review 会偷偷改文件。
• 原因：对命令边界理解不清。
• 解决：/codex:review 与 /codex:adversarial-review 都是只读、绝不改代码；只有 /codex:rescue（以及 review gate 触发的后续动作）才会让 Codex 尝试改代码。要”只审不改”就用 review 系列，要”让它动手修”才用 rescue。

初级用法

1. 审当前未提交改动：/codex:review，快速拿到一次异源模型的外部意见。
2. 审分支相对主干的 diff：/codex:review --base main，用于合并前的分支级审查。
3. 后台审查长任务：/codex:review --background，多文件改动不阻塞你的主会话。
4. 派 Codex 修 bug：/codex:rescue fix the failing test with the smallest safe patch，把具体修复交给 Codex 后台做。
5. 迁移会话到 Codex 继续：/codex:transfer，把当前调试上下文转成 Codex 线程，用 codex resume <session-id> 在 Codex 里接着干。

高级玩法

1. 对抗式定向审查：/codex:adversarial-review --base main challenge whether this was the right caching and retry design——让 Codex 主动挑战你的设计决策而非只看代码细节。
2. 压力测试高风险区域：/codex:adversarial-review --background look for race conditions and question the chosen approach——围绕 auth、数据丢失、回滚、竞态等风险点定向加压。
3. 用 review gate 做提交前门禁：/codex:setup --enable-review-gate 让 Codex 在 Claude 每次响应后跑一次审查、有问题就阻止继续，形成强制质量关卡（注意用量，见踩坑 5）。
4. 指定便宜/快速模型通道：/codex:rescue --model spark fix the issue quickly（spark 映射为 gpt-5.3-codex-spark）或 --model gpt-5.4-mini --effort medium，按任务轻重选模型省成本。
5. 跨工具接续与并行委派：用 /codex:result 拿到的 Codex session ID，codex resume 直接回到 Codex 里审阅/续做；配合多个 --background rescue 并行排查多个独立问题，用 /codex:status 统一监控。

小技巧

1. 多文件审查务必 --background，同步等待会卡住主会话。
2. 跑任何 /codex:* 前先 /codex:setup 确认就绪，省得白等报错。
3. /codex:adversarial-review 记得加 focus text，审查才有针对性，否则等于普通 review。
4. /codex:rescue --resume 可继续上一次 rescue 线程，不用重复描述上下文。
5. 用 /codex:status 查进度、/codex:result 取结论，别反复追问模型”好了吗”。

常见问题 FAQ

Q1：这个插件要额外付费吗？需要单独的 Codex 账号吗？

A：插件本身开源免费（Apache-2.0），但调用 Codex 会产生用量，费用来自你的 ChatGPT 订阅（Free/Plus/Pro 均可用）或 OpenAI API Key，按 Codex 官方定价 计。不需要”单独的插件账号”——它复用你本机 Codex CLI 的登录态；如果你只在用 Claude Code、从没用过 Codex，那需要额外登录一次 Codex（!codex login）。来源：仓库 README、Codex pricing。

Q2：它和直接跑 Codex CLI 有什么区别？

A：无本质区别——插件就是通过你本地的 codex 二进制 + Codex app server 来委派，同一个安装、同一套登录态、同一份 config.toml、同一个仓库环境。区别在于体验：你在 Claude Code 里用斜杠命令和子 Agent 触发，不必开第二个终端，还能用 /codex:transfer 把 Claude 会话平滑接续到 Codex。来源：仓库 README「Codex Integration」。

Q3：和 Claude Code 原生 /review 相比，有什么不同？

A：原生 /review 是 Claude 审 Claude（同源模型），/codex:review/adversarial-review 是 Codex 审 Claude（异源模型），交叉验证能暴露单模型的盲点；且 adversarial-review 支持定向 challenge 设计决策。缺点是你要同时维护两个模型的账号/额度。两者可互补：先 Claude 自查，再 Codex 交叉审。

Q4：审查命令会修改我的代码吗？

A：不会。/codex:review 和 /codex:adversarial-review 都是只读的，只输出意见。会改代码的是 /codex:rescue（委派修复）以及 review gate 触发的后续动作。要纯审查就用 review 系列。来源：仓库 README。

Q5：支持指定模型吗？默认用什么模型？

A：支持。/codex:rescue --model <model> 可指定（如 gpt-5.4-mini、spark→gpt-5.3-codex-spark）；不指定则由 Codex 自选默认。也可在 config.toml 里写 model = "..." 和 model_reasoning_effort = "high" 设全局默认。详见 Codex config 文档。

进阶学习建议

想用透它，往这几个特有机制钻：

• 吃透 /codex:adversarial-review 的 focus 能力：它不是”更凶的 review”，而是可定向加压的审查——练习围绕 auth、数据丢失、回滚、竞态、可靠性等具体风险点写 focus text，把”交叉审查”用成”定向压力测试”。
• 玩转 review gate 的 Stop hook：理解 /codex:setup --enable-review-gate 如何在 Claude 每次响应后注入 Codex 审查并阻止 stop，把它做成团队提交前的强制门禁（先读 README 里关于用量耗尽的警告再决定是否常开）。
• 研究 /codex:transfer 的会话导入：它走 Codex 的 external-agent session importer，把 ~/.claude/projects 下的 transcript 转成 Codex 可见会话——读透这条转换链路，你就理解了”跨工具上下文迁移”的通用做法，codex resume <session-id> 是它的落点。
• 调优 config.toml：用户级 ~/.codex/config.toml 与项目级 .codex/config.toml 的分层覆盖、项目信任机制、model_reasoning_effort 的取舍，是控制成本与质量的关键（参考 config-reference）。
• 真实项目案例：仓库 issues #432/#439/#623 记录了后台任务与多会话 broker 生命周期的一系列真实 bug，读这些 issue 的复现与修复过程，比文档更能帮你理解”后台委派任务”在工程上的坑。

参考链接

• GitHub 仓库 openai/codex-plugin-cc
• Codex CLI 文档
• Codex app server 文档
• Codex 定价页
• Codex 配置参考
• claude-code-router（竞品参考）

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。