Codex Capability Bridge

简体中文 | English

让 Claude Code 或 Claude Desktop 自动发现并选择本机 Codex 的 Skills、已启用插件能力，并通过 Codex MCP 完成任务。

让 Claude 自己安装

在 Claude Desktop Cowork 中挂载本项目目录，然后直接发送：

请读取本项目 README.md 和 docs/AI_INSTALL_PROMPT.md，按照“AI 自主安装提示词”的流程自主完成 Claude Desktop 接入。允许 Codex 操作的目录是本仓库父目录。不要只给建议，直接执行、验证并汇报；不要运行会产生模型用量的真实 ImageGen 验收。

完整提示词、权限规则和故障处理见 AI 自主安装提示词。

安装完成后，可以直接在 Claude Code 中说：

使用 codex 的 imagegen 插件生成一张猫咪的图片

或者不指定能力：

使用 codex 的插件生成一张猫咪的图片

Claude Code 会搜索 Codex 能力目录、选择 imagegen、检查运行时状态，再把完整任务委派给 Codex。

一条命令安装

前置条件：Node.js 20+、Claude Code、Codex CLI 或 Codex Desktop。

Claude Desktop：

npm run setup:desktop -- --project-dir "<允许 Codex 操作的项目目录>"

Claude Code：

npm run setup

如果安装器提示 Claude Code 尚未认证，请在真实验收前执行 claude auth login。插件安装和离线校验不要求 Claude API 登录，但 Claude 自己处理自然语言任务时必须已认证。

安装完成后重启 Claude Code。默认安装到 Claude Code 的 user 作用域；团队项目可使用：

npm run setup -- --scope project

Windows 也可以执行：

.\setup.ps1

macOS/Linux 也可以执行：

sh ./setup.sh

它解决什么问题

Codex 的 Skills、插件和宿主工具不属于同一层能力：

• 独立 Skills 位于 $CODEX_HOME/skills 或 ~/.agents/skills。
• 已安装插件有启用状态，不能把缓存目录中的所有内容都当作可用插件。
• imagegen 等系统 Skill 可以被发现，但其默认 image_gen 工具由 Codex 宿主管理。
• codex mcp-server 对外提供 codex 与 codex-reply，可以启动和继续 Codex 任务。

本项目把这些差异封装在一个 Claude Code 插件中，不要求 Claude 自己理解 Codex 的目录结构。

架构

本文档中的架构图与流程图均由 lhr-fireworks-tech-graph 技能生成——一个面向 Claude Code 的企业级 SVG 技术图生成器。想为自己的项目生成同风格插图，推荐使用它。

用户的自然语言任务经 Claude Code 的 Skill 路由进入桥接层;桥接层一边从四个来源合并能力目录并甄别启用状态,一边通过 codex mcp-server 把任务真实委派给 Codex Agent;产物落盘后经存在性与文件签名双重校验,绝对路径回传 Claude。

插件向 Claude Code 暴露 5 个稳定工具：

• search_codex_capabilities：按用户任务搜索和排序能力。
• describe_codex_capability：检查来源、启用状态和执行模式。
• run_codex_capability：启动 Codex 任务。
• continue_codex_task：使用 threadId 继续任务。
• codex_bridge_doctor：诊断 CLI、MCP 与 ImageGen 委派链路。

委派全流程

一次「用 codex 的插件生成图片」从进入到返回,完整经过搜索排序、可执行性检查、安全闸、真实执行与产物校验五道关:

任何一道关失败都不会被掩盖:不可执行走 doctor 诊断并如实报告,产物未通过校验不会声称成功。

AI 自我修复(Actionable Errors)

桥接器的所有失败路径都内嵌可执行的恢复步骤——错误文本直接告诉调用方模型"先用哪个工具确认什么、然后怎么重试",并按 MCP 规范以 isError: true 结果返回(而非 JSON-RPC 协议错),保证模型能完整读到指引并自我纠正:

覆盖的失败模式与恢复动作(完整决策表见 SKILL.md):

失败	错误内嵌的恢复指引
能力 id 不存在	附 Did you mean: <相近候选>,或引导调用 search 列出真实 id
能力名歧义	列出全部同名完整 id 供选择
可发现但不可执行	区分「插件未启用」与「后端缺失」,分别给出动作
Codex CLI 未找到 / 工具缺失	引导 doctor 查探测报告,提示 CODEX_CLI_PATH 修复
工作目录越界	列出允许的根目录,提示改用项目内路径或 CODEX_BRIDGE_ALLOWED_ROOTS
委派任务超时	建议缩小任务或调高 CODEX_BRIDGE_TIMEOUT_MS

自修复最多两轮,之后如实向用户报告已尝试与仍缺失的内容——防止无限重试。

能力发现顺序

桥接器按以下来源构建目录：

1. $CODEX_HOME/skills，包含隐藏的 .system Skills。
2. ~/.agents/skills。
3. $CODEX_HOME/plugins/cache 中的插件 Skills。
4. codex plugin list --json 返回的启用状态。

缓存中存在不代表已启用。桥接器会保留来源和状态，Claude 应优先选择可执行结果。

ImageGen 的准确边界

imagegen 是 Codex 系统 Skill，不是普通的可移植插件。它默认要求 Codex 宿主提供内置 image_gen 工具。桥接器会：

1. 自动发现 imagegen Skill。
2. 通过 Codex MCP 启动一个真实 Codex 任务。
3. 明确要求 Codex 使用内置 image_gen。
4. 要求产物写入当前工作目录并返回绝对路径。
5. 如果宿主没有提供图像工具，返回真实边界，不会偷偷切换到其他图片供应商。

因此 npm run doctor 能确认“目录与委派链路已就绪”，最终图像工具可用性在真实任务调用时由 Codex 宿主确认。

验收

1. 离线协议验收

npm test
npm run smoke

覆盖能力发现、中文意图排序、MCP 协议、Codex 线程续聊、图像内容落盘和安装幂等性。

2. 环境诊断

npm run doctor

健康输出应包含：

Codex CLI: OK
Codex MCP: OK (codex, codex-reply)
ImageGen: DISCOVERED; delegation backend=true; host verification=unknown

unknown 是有意设计：doctor 不会把“Codex MCP 能启动”冒充“宿主一定注入了 image_gen”。真实任务返回后，桥接器会对工作区内图片做文件存在性和 PNG/JPEG/WebP/GIF 文件签名校验。

3. 一键真实 ImageGen 验收

npm run acceptance:imagegen

该命令会让 Codex 真实调用内置 ImageGen，并要求生成 output/codex-bridge-cat.png。只有目标文件存在、位于工作区内且图片签名有效时才成功。此步骤可能产生模型用量。

4. Claude Code 真实验收

重启 Claude Code，在任意可写测试项目中发送：

使用 codex 的 imagegen 插件生成一张猫咪的图片，并保存到当前项目的 output/cat.png

然后发送不指定能力的版本：

使用 codex 的插件生成一张猫咪的图片，并保存到当前项目的 output/cat-auto.png

预期行为：Claude 调用搜索工具，选择 imagegen，调用运行工具，最后报告 Codex 返回的文件路径。不得只回复一段图片描述。

开发时无需正式安装，可以运行：

claude --plugin-dir ./plugins/codex-capability-bridge

配置

通常不需要配置。可选环境变量：

变量	用途
CODEX_HOME	覆盖 Codex 主目录，默认 ~/.codex
CODEX_CLI_PATH	指定可执行的 Codex CLI
CODEX_BRIDGE_CODEX_COMMAND	最高优先级指定 Codex 命令
CODEX_BRIDGE_CODEX_ARGS_JSON	自定义 Codex 命令的 JSON 字符串数组前置参数
CODEX_BRIDGE_PROJECT_DIR	覆盖默认工作目录
CODEX_BRIDGE_ALLOWED_ROOTS	额外允许的工作目录根路径，多个路径使用系统 PATH 分隔符
CODEX_BRIDGE_TIMEOUT_MS	Codex 任务超时，默认 300000 毫秒
CODEX_BRIDGE_ALLOW_UNSAFE	仅显式设为 1 时允许 never 或 danger-full-access
CODEX_BRIDGE_DISABLE_NPX	设为 1 时禁用官方 npm Codex CLI 后备解析

Windows 下桥接器会验证候选 CLI 是否真的可以执行，并避开可能返回 Access denied 的 WindowsApps 路径。

安全策略

• 默认使用 on-request 审批和 workspace-write 沙箱。
• 默认只允许当前 Claude 项目目录及其子目录。
• 不自动安装 Codex 插件，不自动登录，不修改 Codex 配置。
• 不自动使用 danger-full-access 或跳过权限检查。
• 不把 API Key 写入配置、命令参数或日志。
• 只把嵌套返回的图像内容写入工作目录下的 .codex-bridge-output。
• ImageGen 内置工具不可用时，不静默降级到需要 OPENAI_API_KEY 的 CLI 模式。

卸载

Claude Desktop：

npm run uninstall:desktop

Claude Code：

npm run uninstall

指定安装作用域：

npm run uninstall -- --scope project

卸载脚本只卸载本插件及其 marketplace 声明，不删除用户凭据、Codex 配置或其他插件。

开发与发布

npm test
npm run check

项目运行时仅使用 Node.js 内置模块，没有生产依赖。Claude marketplace 会把插件目录复制到本地缓存，因此服务器、Skill 和配置全部位于 plugins/codex-capability-bridge 内，不依赖仓库外部文件。

发布新版本时同时更新：

• package.json
• .claude-plugin/marketplace.json
• plugins/codex-capability-bridge/.claude-plugin/plugin.json
• plugins/codex-capability-bridge/server/index.mjs 中的服务器版本
• CHANGELOG.md

故障排查

先运行：

npm run doctor

如果提示找不到 Codex CLI，设置 CODEX_CLI_PATH 指向可执行文件。桥接器也可以使用官方 npm 包 @openai/codex 作为最后后备；可通过 CODEX_BRIDGE_DISABLE_NPX=1 禁止该网络后备。Windows Codex Desktop 常见可执行候选包括用户目录下的 Codex app-server CLI；不要硬编码包含版本哈希的路径。

如果 Claude 看不到工具：

1. 运行 claude plugin list --json 确认插件已启用。
2. 重启 Claude Code，或在开发会话执行 /reload-plugins。
3. 运行 claude plugin validate --strict .。
4. 查看 Claude Code 的 /mcp 状态。

如果 ImageGen 被发现但真实任务失败，说明当前 Codex 委派会话没有获得内置图像工具。桥接器会保留错误原文；不要把目录发现成功误判为图像生成成功。

许可证

Apache-2.0。你可以使用、修改、商用及再发布本项目；分发原项目或衍生作品时，必须保留 LICENSE 与 NOTICE 中的原始版权和署名声明，并在修改过的文件中说明修改。参见 LICENSE。