推荐标题：Claude Code 怎么调用 Codex：拆解 codex-plugin-cc 的四层架构 备选标题1：codex-plugin-cc 原理剖析：从 Slash Command 到 Codex App Server 备选标题2：Claude Code 不是直接调用 OpenAI API：插件桥接链路详解 备选标题3：review、rescue、transfer 背后：Codex 插件的任务控制面

四层桥接

事实核验： 本稿按 openai/codex-plugin-cc v1.0.6（2026-07-08）与官方 README 核对。插件命令、参数和实现细节属于版本敏感信息，发布前仍需重新检查最新 release。

codex-plugin-cc 表面上只是给 Claude Code 增加几个 /codex:* 命令。真正的原理要分层看：Claude Code 插件层负责暴露入口；本地 companion 脚本负责解析参数、收集上下文、创建任务；Codex CLI/App Server 负责实际执行；状态文件和后台 worker 负责记录、查询、取消和回收结果。

一句话概括：

它不是 Claude 直接调 OpenAI API。
它是 Claude Code 插件系统把本地 Codex runtime 包装成一个可调用的 Agent 工具。

官方社区帖给出的关键信息是：插件通过本地 Codex CLI 和 Codex app server 委派任务，并复用 Codex 的本地认证、配置、环境和 MCP 设置。1 官方 README 也写明：Codex plugin wraps the Codex app server，使用环境中的全局 codex binary，并应用同一套 Codex 配置。2

这两句话基本定下了它的架构边界。

一、整体链路

可以先看一张简化图：

一、整体链路 用户看到的是 /codex:review。真正发生的是：Claude Code 读取插件命令文件，按命令说明调用本地 Node 脚本；脚本解析参数，确定要审查 working tree 还是某个 base branch；然后通过 Codex app server 把任务交给 Codex；最后把 Codex 的输出渲染回 Claude Code。

第一层：插件命令

二、第一层：Claude Code 插件层

Claude Code 插件可以包含 commands、skills、agents、hooks、MCP server、LSP server、background monitors、bin 可执行文件和 settings。官方插件文档明确说明，插件根目录可以包含 .claude-plugin/plugin.json、skills/、commands/、agents/、hooks/、.mcp.json、.lsp.json、monitors/、bin/ 等组件。3

codex-plugin-cc 利用的核心入口是 slash commands。它把 /codex:review、/codex:adversarial-review、/codex:rescue 等能力暴露给 Claude Code 用户。

以 adversarial-review.md 为例，官方命令文件里可以看到几个关键信息：

---
description: Run a Codex review that challenges the implementation approach and design choices
argument-hint: [--wait|--background] [--base <ref>] [--scope auto|working-tree|branch] [focus ...]
disable-model-invocation: true
allowed-tools: Read, Glob, Grep, Bash(node:*), Bash(git:*), AskUserQuestion
---

这个设计说明命令文件本身不是“让 Claude 自己审代码”的提示词，而是指挥 Claude Code 使用受限工具执行本地脚本。disable-model-invocation: true 的语义是限制命令内部不再让模型自由发挥，而是让它按命令说明去调用共享 runtime。4

所以第一层的本质是：用 Claude Code 的插件与命令系统注册一个可调用入口。

第二层：Companion

三、第二层：companion 脚本层

真正的桥接逻辑集中在 plugins/codex/scripts/codex-companion.mjs 这类脚本里。这个脚本的 usage 信息显示它支持这些子命令：

setup
review
adversarial-review
task
transfer
status
result
cancel

这正好对应用户在 Claude Code 里看到的 /codex:* 命令。脚本负责的事情包括：

解析命令参数
检查 Codex CLI 是否可用
检查 Git 仓库状态
解析 review 目标：working tree 或 base branch
构造 review / task 请求
创建 job 记录
启动前台或后台执行
轮询状态
渲染结果
取消任务

官方源码片段里能看到 handleReviewCommand 会解析 base、scope、model、cwd、background、wait 等参数，并创建 review job；handleTask 会解析 model、effort、write、resume、fresh、background 等参数；后台任务会创建 job，然后通过 worker 执行。5

这层非常关键。它把“Claude Code 的一条自然语言 slash command”翻译成“Codex runtime 可执行的结构化任务”。

第三层：App Server

四、第三层：Codex App Server 与协议层

如果只是调用 codex "review this diff"，功能会很粗糙。codex-plugin-cc 更重要的做法是接入 Codex app server。

Codex App Server 文档说明它支持以 RPC 方式管理 thread、turn、config、app、skill 等能力。自定义 client 可以调用这些方法，而不是只能通过终端 UI 和 Codex 交互。6

插件源码里的 app-server.mjs 也体现了这点。它定义了 app server client，向 codex app-server 发送 JSON-RPC 风格消息，初始化时会发送 initialize，然后发送 initialized 通知；直接模式下会 spawn codex app-server，通过 stdin/stdout 读写 JSONL；另一路径会通过 broker 管理 app server 连接。7

因此，codex-plugin-cc 调 Codex 的方式更接近：

Claude Code command
  -> Node companion
  -> App Server client
  -> JSON-RPC / JSONL messages
  -> Codex app-server
  -> Codex session / thread / turn

这比一次性 CLI 调用强很多，因为它可以保留 thread、返回 session id、resume、管理后台任务，也可以把 Claude 会话迁移到 Codex 里继续。

第四层：本地环境

五、第四层：本地认证、配置、权限和 MCP

这个插件的一个设计重点是“复用本地 Codex”。

Codex 配置文档说明，用户级配置在 ~/.codex/config.toml，项目级覆盖可以放在 .codex/config.toml，并且项目级配置只在信任项目时加载。配置可以控制默认模型、provider、approval policy、sandbox settings、MCP servers 等。8

这意味着 codex-plugin-cc 不需要自己定义一套完整的模型配置和工具权限系统。它借用 Codex 原本的配置栈。

从工程角度看，这是它“轻”的原因，也是它“危险”的地方。

轻，是因为插件不用重复实现认证、MCP、sandbox、approval、模型选择。

危险，是因为你要清楚 Codex 已经被授予了什么权限。比如你的 Codex 配置里启用了某些 MCP server，插件调用 Codex 时也可能受这些配置影响。插件不是沙盒隔离出的另一个世界，它站在你本地 Codex 环境之上。

六、review 与 adversarial-review 的区别

官方 README 说明 /codex:review 是普通只读审查，用于审查当前 uncommitted changes 或相对 base branch 的变化；它不接收自定义 focus text。/codex:adversarial-review 则是 steerable review，可以对实现方式、设计选择、tradeoff、隐藏假设、失败模式进行 pressure-test，并且可以追加 focus text。2

这就是两个命令的核心差异：

/codex:review
目标：找代码问题
姿态：Reviewer
输入：diff / branch target
输出：优先级化 findings

/codex:adversarial-review
目标：挑战方案
姿态：Skeptical reviewer / 反方工程师
输入：diff / branch target + focus text
输出：设计风险、失败路径、替代方案、上线疑点

官方 adversarial-review.md 命令文件也明确要求它不是更严格的实现缺陷检查，而是 challenge review，要质疑实现、设计、tradeoff 和假设。4

所以它不是“review 的加强版”，而是“review 的角色切换”。

后台任务控制面

七、rescue、transfer、status、result、cancel 的状态系统

/codex:rescue 会通过 codex:codex-rescue subagent 把任务交给 Codex，适合调查 bug、尝试修复、继续之前的 Codex 任务，或用更快/更便宜的模型跑一遍。README 还说明 rescue 支持 --background、--wait、--resume、--fresh。2

/codex:transfer 则会从当前 Claude Code session 创建一个持久 Codex thread，并打印 codex resume <session-id>，用于把 Claude Code 里开始的调试或实现上下文迁移到 Codex 继续。2

/codex:status 显示当前 repository 的运行中和近期 Codex jobs；/codex:result 展示完成 job 的最终输出；/codex:cancel 取消活跃后台 job。2

源码里可以看到后台任务会 spawn detached worker，并写入 queued record，包含 jobId、status、title、summary、pid、logFile、request 等信息。5

这说明插件内部有一套最小任务队列模型：

{
  "id": "review-abc123",
  "status": "queued | running | succeeded | failed | cancelled",
  "jobClass": "review | task",
  "title": "Review working tree",
  "summary": "Review current changes",
  "pid": 12345,
  "logFile": "...",
  "request": {
    "cwd": "...",
    "scope": "working-tree",
    "model": "..."
  }
}

这个模式和传统后台任务系统非常像：创建 job、写状态、启动 worker、输出日志、轮询状态、读取结果、允许取消。

Review Gate

八、review gate 是什么

/codex:setup --enable-review-gate 可以开启 review gate。官方 README 说明，开启后插件使用 Claude Code 的 Stop hook，根据 Claude 的上一轮响应运行一个 targeted Codex review；如果 review 发现问题，stop 会被阻断，让 Claude 先处理问题。README 同时提醒这可能造成长时间 Claude/Codex 循环，并快速消耗 usage limits。2

这是一个很典型的 Agent 工程模式：把审查插入到主 Agent 停止之前。

普通模式是：

Claude 完成响应 -> 用户手动 review -> 用户决定是否继续

review gate 模式是：

Claude 完成响应 -> Stop hook 触发 Codex review -> 有问题则阻断 -> Claude 修复 -> 再审

它有价值，但不能默认开。因为这类循环如果缺少人工边界，成本和时间都会失控。

架构边界

九、为什么自己写 Demo 时不能一开始就复刻官方插件

官方插件看似只是命令文件加脚本，实际牵涉很多边界：Claude Code plugin 格式、Codex app server 协议、broker 生命周期、job 状态、resume thread、session import、hook、配置继承、跨平台进程管理。

自己写 Demo 时，不应该一开始复制所有东西。最小闭环应该只有三步：

收集上下文：git diff / git status / 用户 focus
封装任务：把上下文转成 reviewer prompt
回收结果：把模型输出结构化展示

然后再逐步加：

background job
status/result/cancel
Claude Code command wrapper
Codex CLI bridge
App Server bridge
session handoff
review gate

这也是下一篇文章要做的事：先写一个 Mini Reviewer，再解释它和官方插件的差距。

结论

codex-plugin-cc 的核心不是“让 Claude Code 调 OpenAI 模型”，而是把一个已有的本地 Coding Agent runtime 接到另一个 Coding Agent 的插件系统里。

它的架构可以压缩成四句话：

Claude Code 插件层提供命令入口。
companion 脚本把命令变成任务。
Codex CLI/App Server 执行真正的 Agent 工作。
job 状态层负责后台任务、结果回收和会话延续。

理解这四层，才能真正理解这个插件为什么火，也才能写出自己的 Demo 版本。

Footnotes

  1. OpenAI Developer Community, “Introducing Codex Plugin for Claude Code”, https://community.openai.com/t/introducing-codex-plugin-for-claude-code/1378186 ↩

  2. OpenAI, openai/codex-plugin-cc README, https://github.com/openai/codex-plugin-cc/blob/main/README.md ↩ ↩2 ↩3 ↩4 ↩5 ↩6

  3. Claude Code Docs, “Create plugins”, https://code.claude.com/docs/en/plugins ↩

  4. OpenAI, adversarial-review.md, https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/adversarial-review.md ↩ ↩2

  5. OpenAI, codex-companion.mjs, https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/codex-companion.mjs ↩ ↩2

  6. OpenAI Developers, “Codex App Server”, https://developers.openai.com/codex/app-server ↩

  7. OpenAI, app-server.mjs, https://raw.githubusercontent.com/openai/codex-plugin-cc/main/plugins/codex/scripts/lib/app-server.mjs ↩

  8. OpenAI Developers, “Codex Config basics”, https://developers.openai.com/codex/config-basic ↩