🔥 codex-plugin-cc 原理全拆：四层桥接 + JSON-RPC 2.0 + JSONL + 后台任务状态机

武子康2026-07-15 10:40

TL;DR

  • 场景 ：你已经在用 Claude Code，又想用 Codex 做 review / rescue / 会话迁移；想知道 /codex:* 这一组命令到底怎么把任务交给本地 Codex runtime。
  • 结论：codex-plugin-cc 不是 Claude 直接调 OpenAI API，而是「Claude Code 插件系统 + 本地 companion 脚本 + Codex App Server (JSON-RPC 2.0/JSONL) + 复用本地 Codex 配置」四层桥接；轻，但站在你本地 Codex 环境之上。
  • 产出：四层架构图、命令矩阵、状态机模型、review gate 触发链、复刻 Demo 的分阶段清单；附 8 张全图 vision 描述。

版本矩阵

功能 状态 说明
/codex:review 只读审查 ✅ 已验证 官方 README + 用户引用源印证
/codex:adversarial-review 可加 focus text 的反方审查 ✅ 已验证 adversarial-review.md + README
/codex:rescue 含 --background / --wait / --resume / --fresh ✅ 已验证 README 明确说明
/codex:transfer 输出 codex resume <session-id> ✅ 已验证 README
/codex:status / :result / :cancel 三件套 ✅ 已验证 README
codex-companion.mjs 子命令（setup/review/adversarial-review/task/transfer/status/result/cancel） ✅ 已验证 用户引用源码 + 联网公开仓库可印证
Codex App Server 走 JSON-RPC 2.0，stdio 默认走 JSONL ✅ 已验证 codex-rs/app-server/README.md 原文
App Server 支持 thread / turn / config / app / skill 等 RPC 方法 ✅ 已验证 OpenAI Developers 文档
复用 ~/.codex/config.toml + 项目级 .codex/config.toml 覆盖（仅信任项目） ✅ 已验证 Codex Config basics 文档
插件根目录组件：plugin.json / commands/ / agents/ / hooks/ / skills/ / .mcp.json / .lsp.json / monitors/ / bin/ ✅ 已验证 Claude Code Plugins 文档
disable-model-invocation: true 限制命令内部不再让模型自由发挥 ✅ 已验证 Claude Code 文档约定
setup --enable-review-gate（基于 Stop hook） ✅ 已验证 README
插件版本 v1.0.6（2026-07-08） ⚠️ 用户声明 联网可独立命中 v1.0.4（2026-04-19），未直接命中 v1.0.6 release notes；发布前请再核 tag
插件版本 v1.0.4（2026-04-19） ✅ 已验证 公开 commit 历史可印证
协议层 JSON-RPC 2.0 头在 wire 上省略 ✅ 已验证 codex-rs/app-server/README.md 原文

事实核验： 本稿按 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 负责记录、查询、取消和回收结果。

一句话概括：

text 复制代码 
它不是 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^

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

一、整体链路

可以先看一张简化图：

flowchart TD U[User] --> CC[Claude Code] CC --> CMD[/codex:* slash command/] CMD --> PLUGIN[Claude Code Plugin] PLUGIN --> COMPANION[codex-companion.mjs] COMPANION --> STATE[Job State + Logs] COMPANION --> BROKER[App Server Broker] BROKER --> AS[Codex App Server] AS --> CLI[Local Codex CLI Runtime] CLI --> MODEL[OpenAI Codex] MODEL --> CLI CLI --> AS AS --> COMPANION COMPANION --> CC

用户看到的是 /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 为例，官方命令文件里可以看到几个关键信息：

yaml 复制代码 
---
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 脚本层

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

text 复制代码 
setup
review
adversarial-review
task
transfer
status
result
cancel

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

text 复制代码 
解析命令参数
检查 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 可执行的结构化任务"。

四、第三层：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 的方式更接近：

text 复制代码 
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^

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

text 复制代码 
/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^

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

json 复制代码 
{
  "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 是什么

/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 停止之前。

普通模式是：

text 复制代码 
Claude 完成响应 -> 用户手动 review -> 用户决定是否继续

review gate 模式是：

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

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

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

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

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

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

然后再逐步加：

text 复制代码 
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 的插件系统里。

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

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

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

错误速查卡

症状 根因 定位 修复
误以为 /codex:review 是「让 Claude 自己审代码」 命令文件带 disable-model-invocation: true + 受限 allowed-tools，实际是指挥 Claude Code 调本地脚本 看 adversarial-review.md 等命令文件的 YAML frontmatter 把它当作「触发 companion 脚本」来理解，不要期望模型内部自由发挥
误以为 review 与 adversarial-review 是「严格程度不同」 两者是姿态切换：reviewer vs 反方工程师，adversarial 还接受 focus text 看 README 「/codex:adversarial-review」段 按需求选：找问题用 review；挑战方案/设计 trade-off 用 adversarial-review 并加 focus
/codex:setup --enable-review-gate 之后 usage 飙升、Claude/Codex 死循环 开启后 Stop hook 会在每轮响应后跑一次 targeted Codex review；缺少轮次/时长/usage 边界 看 README 风险提示 不要默认开；开了也要设硬上限：最大轮次、单次 review timeout、累计 usage 阈值
自己复刻时一次性抄完所有能力，PoC 直接崩 实际牵涉 plugin 格式、App Server 协议、broker 生命周期、job 状态、resume、hook、配置继承、跨平台进程 按文章第九节「最小三步闭环」+ 分阶段清单推进 先做 上下文→任务→结果 三步闭环，再按顺序加 job、command wrapper、CLI bridge、App Server bridge、session handoff、review gate
误以为插件是隔离的沙盒环境 插件直接复用 ~/.codex/config.toml + 项目级 .codex/config.toml（仅信任项目） 看 Codex Config basics 文档 上线前审查 Codex 配置：禁用多余 MCP server、明确 approval policy、必要时收窄 sandbox 边界
联网核查不到 v1.0.6 release notes 用户稿声明 v1.0.6（2026-07-08），公开可独立验证的最早是 v1.0.4（2026-04-19） GitHub releases / tags 发布前再核一次最新 tag，避免引用旧版命令/参数；如版本不匹配，更新事实核验段
App Server 协议字段搞混 Codex App Server 在 wire 上省略 "jsonrpc":"2.0" 头（与标准 JSON-RPC 2.0 区别） 看 codex-rs/app-server/README.md 写 client 时不要硬性断言 jsonrpc 字段；按 method / params / result / error 路由
codex resume <session-id> 续不上 transfer 只创建持久 Codex thread 并打印 session id；不依赖运行中 Claude Code 状态 重新跑 codex resume <session-id> session id 由 transfer 输出，单独保存到会话笔记；不要依赖 Claude Code 当前 session
误以为 companion 脚本是「Claude → OpenAI」直连 实际路径：Claude Code → plugin command → companion.mjs → App Server client → JSON-RPC/JSONL → Codex app-server 看 app-server.mjs 源码 + App Server README 排查时按这条链路逐段打断点；先确认 codex app-server 可独立启动并响应
误把 plugin 内部 jobClass 当作公共 API 字段来自内部最小任务队列模型（id / status / jobClass / title / summary / pid / logFile / request） 看 companion 源码 把它当内部状态看待；外部集成应优先用 /codex:status / :result / :cancel

Footnotes

  1. OpenAI Developer Community, "Introducing Codex Plugin for Claude Code", community.openai.com/t/introduci... ↩

  2. OpenAI, openai/codex-plugin-cc README, github.com/openai/code... ↩ ↩2 ↩3 ↩4 ↩5 ↩6

  3. Claude Code Docs, "Create plugins", code.claude.com/docs/en/plu... ↩

  4. OpenAI, adversarial-review.md, github.com/openai/code... ↩ ↩2

  5. OpenAI, codex-companion.mjs, github.com/openai/code... ↩ ↩2

  6. OpenAI Developers, "Codex App Server", developers.openai.com/codex/app-s... ↩

  7. OpenAI, app-server.mjs, raw.githubusercontent.com/openai/code... ↩

  8. OpenAI Developers, "Codex Config basics", developers.openai.com/codex/confi... ↩

相关推荐
手写码匠1 小时前
从零实现大模型推理引擎：Continuous Batching 与动态调度系统深度解析
人工智能·深度学习·算法·aigc
科技发布1 小时前
获奖平台传播易 全域广告投放一站式解决方案
人工智能
breeze jiang1 小时前
告别等待焦虑：Vue 3 + DeepSeek 实现 AI 打字机流式对话，用户体验提升立竿见影
vue.js·人工智能·ux
Databuff1 小时前
个人用的桌面级开源智能体有哪些？OpenOcta 八爪鱼上手与对比
人工智能·ai·语言模型·开源·开源软件
网易云信1 小时前
从“合规”到“信任”：网易智企专属云打造强监管下的通信新范式
人工智能·后端
Zzj_tju1 小时前
LLM for Code Research：程序合成、自动调试与软件工程评测
人工智能·语言模型·软件工程
拾起_3691 小时前
12-Provider 配置与模型路由：多 provider 接入机制
人工智能·开源
SelectDB技术团队1 小时前
Agent 可观测性：Apache Doris / SelectDB 的技术能力、选型对比与实践
数据库·人工智能·agent·可观测·ai-native·apache doris·selectdb
拾起_3691 小时前
10-Plugin 系统与 Skill 发现：扩展边界与上下文注入
人工智能·开源
热门推荐
012026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片02GitHub 镜像站点03AI科技热点日报 | 2026年07月01日04幻兽帕鲁 - 服务器管理员权限与 GM 命令完全指南05GPT-5.5 对比 GPT-5.6 Sol、Terra、Luna：官方性能数据与选型分析062026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？07AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路082026 年 AI 大模型 & AI 编程工具实战全总结09几个好用的ip纯净度检测网站102026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？