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三件套✅ 已验证READMEcodex-companion.mjs子命令setup/review/adversarial-review/task/transfer/status/result/cancel✅ 已验证用户引用源码 联网公开仓库可印证Codex App Server 走 JSON-RPC 2.0stdio 默认走 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.62026-07-08⚠️ 用户声明联网可独立命中 v1.0.42026-04-19未直接命中 v1.0.6 release notes发布前请再核 tag插件版本v1.0.42026-04-19✅ 已验证公开 commit 历史可印证协议层 JSON-RPC 2.0 头在 wire 上省略✅ 已验证codex-rs/app-server/README.md原文事实核验本稿按openai/codex-plugin-ccv1.0.62026-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使用环境中的全局codexbinary并应用同一套 Codex 配置。2这两句话基本定下了它的架构边界。一、整体链路可以先看一张简化图UserClaude Codecodex:* slash commandClaude Code Plugincodex-companion.mjsJob State LogsApp Server BrokerCodex App ServerLocal Codex CLI RuntimeOpenAI Codex用户看到的是/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/等组件。3codex-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 choicesargument-hint:[--wait|--background][--base ref][--scope auto|working-tree|branch][focus...]disable-model-invocation:trueallowed-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 信息显示它支持这些子命令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 jobhandleTask会解析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通知直接模式下会 spawncodex 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-rescuesubagent 把任务交给 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 是什么/codex:setup --enable-review-gate可以开启 review gate。官方 README 说明开启后插件使用 Claude Code 的Stophook根据 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 版本。错误速查卡症状根因定位修复误以为/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.62026-07-08公开可独立验证的最早是 v1.0.42026-04-19GitHub 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-idsession 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/:cancelOpenAI Developer Community, “Introducing Codex Plugin for Claude Code”, https://community.openai.com/t/introducing-codex-plugin-for-claude-code/1378186 ↩︎OpenAI,openai/codex-plugin-ccREADME, https://github.com/openai/codex-plugin-cc/blob/main/README.md ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎Claude Code Docs, “Create plugins”, https://code.claude.com/docs/en/plugins ↩︎OpenAI,adversarial-review.md, https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/adversarial-review.md ↩︎ ↩︎OpenAI,codex-companion.mjs, https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/codex-companion.mjs ↩︎ ↩︎OpenAI Developers, “Codex App Server”, https://developers.openai.com/codex/app-server ↩︎OpenAI,app-server.mjs, https://raw.githubusercontent.com/openai/codex-plugin-cc/main/plugins/codex/scripts/lib/app-server.mjs ↩︎OpenAI Developers, “Codex Config basics”, https://developers.openai.com/codex/config-basic ↩︎