Codex Claude Bridge

让已有的 Codex 与 Claude Code 会话直接协作，让长任务在上下文压缩后接着做。

Codex Claude Bridge（管理页与命令名称：Cooperation）连接 Codex 桌面 App 和 VS Code 中的 Claude Code。你继续使用熟悉的原生对话界面，为不同会话分配工作；agent 通过 MCP 或 CLI 互相发送任务、评审意见和结果，本地工作台集中展示多个项目的会话、消息和上下文用量。

OpenCode 通信、上下文显示与自动维护已接入：新版插件支持软/硬阈值的交付、原生压缩、恢复和条件继续，默认按会话关闭。启用方法、原生验证及并发边界见 OpenCode 自动维护。主动创建、加载会话方向仍已取消；状态见 取消与收尾。安装与通信验收见 OpenCode 接入，桌面应用壳仍未验收。

它把 原生会话通信、跨项目管理、上下文交接与恢复 放进同一条工作流：从“请另一个 agent 看看这个方案”，到“上下文快满了，保存进度、压缩、恢复并接着协作”。

快速部署 · 发送第一条消息 · 配置-mcp · 自动上下文维护 · 常见问题

核心特色

项目的核心差异，是把“原生界面里的 agent 协作”和“长任务的上下文续接”一起做好。 用户决定参与者与分工，agent 负责交换工作成果，Cooperation 负责传递消息、展示状态和执行获准的维护流程。

例如：让 Codex 实现一个功能，让 Claude 审查方案与变更；发现问题后直接发回原 Codex 会话。两端各自保留自己的任务上下文，协作可以跨越一次上下文压缩继续进行。

flowchart LR
    C[Codex 桌面原生会话] <-->|MCP / CLI| B[Cooperation 本地服务]
    B <-->|消息与原生控制| A[Claude Code 原生会话]
    U[用户管理页] -->|选择目录、查看通信、配置阈值| B
    B --- D[持久消息、维护流程与队列]

Related MCP server: papi

快速部署

1. 准备环境并获取项目

当前部署与原生验收以 Windows x64 为基线。

git clone https://github.com/Heisenbear-Rebirth/codex-claude-bridge.git Cooperation
cd Cooperation
node --version
.\scripts\build-claude-wrapper.ps1

无需运行 npm install 或构建前端。最后一步生成 bin/claude-wrapper.exe 和 bin/claude-wrapper.paths，其中包含本机路径；移动项目或换机器后重新构建。

下文统一以 C:/Tools/Cooperation 为安装目录，请替换为你自己的完整路径。工具安装目录用于存放服务和数据；工作项目目录是 Codex、Claude 实际处理代码或文档的目录，两者可以不同。

2. 启动服务并连接 Codex

双击 启动项目.cmd，服务会在后台启动并打开管理页。重复启动会复用已有服务；端口以打开的页面为准。

首次使用时，为 Codex 配置一次 Cooperation MCP，重新连接该 MCP。页面右上角显示 “Codex 已连接” 后，即可向 Codex 发消息。只使用 CLI 时，也可以让 Codex 在自己的命令工具中运行一次：

node "C:/Tools/Cooperation/bin/coop-service.mjs" start

工具会在本地保存已授权的连接，并在启动和发送前检查连通性。以后正常双击启动即可，不再要求每次都从 Codex 会话启动。 配好 MCP 后，Codex 重新接入时会自动更新连接，运行中的管理服务会自动重连，无需重启服务。

Codex App 需要保持可用。断开时页面会显示“Codex 待连接”；打开 Codex 并连接 Cooperation MCP 后，状态会自动更新。工具只复用本机已经取得的授权连接，投递结果不确定的消息仍需核对，不会自动重发。

3. 接入 Claude Code

在 VS Code 的用户设置 JSON 中，合并下面这一项，指向刚构建的文件：

"claudeCode.claudeProcessWrapper": "E:\\Projects\\Cooperation\\bin\\claude-wrapper.exe"

这是一项 VS Code 用户级配置，由你明确选择是否启用；构建和启动服务不会自动写入它。保留其他设置；已有其他 wrapper 时，先核对如何整合。该程序会启动扩展原本选定的 Claude，并转发其输入、输出和权限交互。

已接入 wrapper 的新进程会尝试显示 Cooperation 的 peer 消息，并标注“Cooperation 会话消息”。仅转换原生回显的界面副本，不向 Claude 重发、不打断当前工具。现有进程不会热更新；待工作结束后再正常重开面板。该功能已通过隔离协议测试及专用 Claude 会话的工作中投递测试，用户确认面板出现消息气泡；本次消息在原任务结束后被处理，不保证入队即刻显示。默认关闭重开时的自动历史补显，避免旧消息集中出现在对话末尾。新消息的实时显示保留，同一会话内同编号的实时/历史回放共用去重记录。重开后原生面板可能不再显示旧协作消息，可在 Cooperation 管理页查看通信历史。历史补显仅可通过独立的 peerHistoryVisibility: true 或 COOP_PEER_HISTORY_VISIBILITY=1 显式启用，仍会在末尾补回而非原位置；详见 wrapper 说明。若原生没有输出对应回显，不会凭传输提交结果补造已收到消息。设置启动环境变量 COOP_PEER_MESSAGE_VISIBILITY=0 可关闭此功能；也可在项目 .cooperation/claude-wrapper/config.json 中设置 peerMessageVisibility: false，在下次启动 wrapper 时生效。

随后在管理页：

1. 添加 Claude 实际工作的项目目录。

2. 打开目录旁的 “项目设置”，开启 “Claude 控制接入”。

3. 关闭并重新打开对应的 Claude Code 面板，让它通过 wrapper 启动。

4. 确认原面板的模型、思考强度与权限选项符合你的预期，并检查管理页是否显示连接状态。

“Claude 控制接入”精确匹配工作目录。“包含子目录”只扩大展示范围；需要接入的子目录应单独添加并允许。这个开关与会话的“自动压缩”相互独立。

详细接入、协议说明与回滚步骤见 Claude 原生控制接入。

4. 找到要协作的会话

在管理页左上选择 “目录项目”，点击 ＋ 添加工作目录，按需开启 “包含子目录”。展开项目后直接显示会话，灰色客户端名称位于会话名称后。点击会话，在右侧点击 “复制地址”。

地址形如：

codex://实现功能的会话:原生会话ID
claude://审查方案的会话:原生会话ID

也可以使用短地址 codex:会话ID 或 claude:会话ID。接收方由你指定；发送者由工具自动识别。

会话被发现只代表它存在。先打开准备使用的原生会话；Codex 自动维护需要任务已在 App 中加载，Claude 接收和控制需要相应连接在线。

发送第一条消息

通过 CLI：无需先配置 MCP

把下面的提示发给 Codex 发送方会话，替换目标地址与正文：

请通过 Cooperation CLI 向以下目标会话实际发送消息，并告诉我投递结果：

node "C:/Tools/Cooperation/bin/coop.mjs" send --client codex --to "这里粘贴目标会话地址" --text "请审查我的实现方案，并通过 Cooperation 把意见发回本会话。"

如果发送方是 Claude Code，把 --client codex 改为 --client claude。该参数表示谁在发送；--to 表示发给谁。

CLI 应由原会话的命令工具执行，以便取得该会话的身份。从独立 PowerShell 手工执行可能无法确认发送者。

长消息、代码片段或复杂引号内容适合先写入发送方获准目录内的 UTF-8 文本文件，再发送：

node "C:/Tools/Cooperation/bin/coop.mjs" send --client claude --to "codex:目标会话ID" --file "E:/Work/MyProject/review.txt"

正文前会自动带上发送方地址。接收方可以用这个地址回信；是否回复、何时回复由任务要求和 agent 决定。

怎样确认第一次协作成功

1. 在目标原生会话中看到消息及发送方信息。

2. 在管理页选择相关会话，切换右侧 “通信记录”，找到同一条消息。

3. 让接收方回一条消息，并在原发送方会话中确认收到。

submitted 表示客户端已接受投递，对方实际回复才表明它已处理消息。如返回 unknown，先在原会话核对，避免重复发送。

给 agent 的协作约定

下面这段适合放在任务开头，或由你决定加入工作项目的指令文件：

本任务允许通过 Cooperation 与以下会话协作：
对方地址：<粘贴地址>
对方分工：<例如：审查方案、复核测试结果>

需要对方协助时，优先使用已加载的 Cooperation send_message 工具；未加载 MCP 时使用本机 Cooperation CLI。
发送时说明目标、必要背景、需要对方完成的事项和相关文件位置。
取得反馈后结合当前任务处理；需要回复时使用消息中附带的发送方地址。
发送后检查投递结果；结果不确定时先核对原会话。

Cooperation 负责通信和上下文维护。任务分工、文件修改范围与结果验收由你和参与会话约定。

配置 MCP

CLI 和 MCP 都连接同一个管理服务。配置 MCP 是让 agent 能直接调用工具；它不会替你启动管理服务或完成 Claude 接入。

把配置放在需要调用工具的工作项目中，并把其中的安装路径替换为自己的路径。已有配置文件时合并相应条目。

Codex

在工作项目的 .codex/config.toml 中加入以下配置；Codex 需要信任该项目才能加载项目级配置。配置位置和格式参见 OpenAI MCP 文档。

[mcp_servers.cooperation]
command = "node"
args = ["C:/Tools/Cooperation/bin/coop.mjs", "mcp", "--client", "codex"]
tool_timeout_sec = 75
env_vars = ["CODEX_APP_TOOLS_PIPE_PATH", "CODEX_THREAD_ID", "CODEX_MCP_NODE_PATH"]

Claude Code

在工作项目根目录的 .mcp.json 中合并以下配置。Claude Code 对项目级 MCP 的加载确认与连接检查见 Claude Code MCP 文档。

{
  "mcpServers": {
    "cooperation": {
      "command": "node",
      "args": ["C:/Tools/Cooperation/bin/coop.mjs", "mcp", "--client", "claude"]
    }
  }
}

重新加载对应客户端的 MCP 配置，完成客户端要求的信任或权限确认，并检查 cooperation 是否已连接。配置样例也保存在 Codex 与 Claude 文件中。

让会话调用 MCP

请实际调用 Cooperation MCP 的 send_message 工具：
to：<粘贴目标会话地址>
message：请审查刚才的方案，完成后通过 Cooperation 回复本会话。

调用后告诉我投递结果。

本项目只提供两个业务工具：

会话发现和通信历史由用户在管理页查看，agent 根据用户提供的地址工作。维护回执所需参数由系统下发，日常发消息只需使用 send_message。

管理页怎么用

• 项目导航：左侧抽屉显示可折叠项目与单行会话。Claude、Codex、OpenCode 以灰色名称跟在会话后，状态圆点提示连接与活动。搜索项目或会话，点击“已连接”筛选；左上导航按钮可收起侧栏。

• 项目概览：点击项目名称，右侧展示成员与连接统计；点击成员进入其设置。目录旁的“···”可编辑项目名称、子目录范围和 Claude 控制接入。

• 会话设置：右侧显示上下文占用、模型、活动状态和统计时间。自动压缩使用开关，阈值可输入或拖动；失焦、按 Enter 或松开滑块后自动保存。关闭自动压缩后继续观察用量，未知容量保持未知。

• 通信记录：选择项目时显示涉及该项目成员的发送与接收，选择会话时聚焦该会话。消息支持关键词、状态筛选；点击消息阅读完整正文和投递结果。折叠导航不改变当前选中的通信范围。

• 连接与维护：会话设置中保留连接帮助、刷新状态、维护接续与队列处理。OpenCode 的自动压缩开关按原生插件维护能力开放。

自定义项目：按协作目标组织会话

1. 先在“目录项目”中添加会话来源目录。

2. 切换左上 “自定义项目”，点击 ＋，填写组名并点击所需会话加入。可跨目录选择，也可按名称、目录或客户端搜索。

3. 保存后，组名成为左侧项目标题，下方只展示所选成员。使用“编辑分组”改名或调整成员。

同一会话可以出现在多个组中，并共享原来的会话设置。分组成员与名称保存在本地管理数据库，服务重启后保留；暂时离线或未发现的成员仍显示在组中。删除分组只移除组织关系，保留会话、策略和通信历史。多个窗口同时编辑时会核对版本，提示重新打开已被修改的分组。

页面采用浅灰侧栏、白色内容区与绿色操作强调，主要空间留给所选项目或会话。目录、消息列表和正文各自滚动；手机宽度下项目导航为覆盖式抽屉。长消息实时刷新保持阅读位置。管理页中的通信记录只包含经 Cooperation 发送的消息。

自动上下文维护

每个会话有独立的 “启用自动压缩” 开关，默认关闭。先确认会话接入和通信正常，再按需启用。

空闲阈值表示：达到该占用后，等待当前工作结束再维护。强停阈值表示：工作过程中达到该占用，先中断对应轮次，再进行维护。数值可按会话修改；必须满足 0 < 空闲阈值 < 强停阈值 < 100。已启用时降低阈值可能立即触发维护。

一次维护会发生什么

达到阈值 → 锁住 Cooperation 入站消息 → 必要时中断原工作
    → 写交付文档 → handoff 回执 + 本轮结束
    → 原生压缩完成
    → 读取交付文档、加载上文 → restored 回执 + 本轮结束
    → 原本工作中才继续任务 → 按顺序投递排队消息

交付文档保存接续任务所必需的信息，比如当前进展、关键约束或容易遗漏的事项，具体内容和组织方式由 agent 判断；文档写入目标会话工作目录的 .cooperation/handoffs/。两个回执都校验身份、阶段凭证与文档内容；普通回复 OK 不会推进流程。

工具沿用原会话的模型、思考强度和权限选项。维护包含模型参与的交付与恢复轮次，会使用原客户端的正常用量。

回执遇到权限确认

Codex/Claude维护提示优先要求调用 context_checkpoint；未加载 MCP 时，会提供专用 CLI 命令。Claude 如果要求执行授权，可以按原权限流程批准。OpenCode使用插件工具 cooperation_context_checkpoint 绑定原生身份，不使用CLI代填会话来源。

若希望在特定工作项目中允许该专用入口，可由你在该项目的 .claude/settings.local.json 中合并窄规则，例如：

{
  "permissions": {
    "allow": [
      "Bash(node C:/Tools/Cooperation/bin/coop-checkpoint.mjs *)"
    ]
  }
}

保留已有权限条目，并使用实际安装路径。该许可只覆盖专用回执 CLI；工具不会自动安装这条规则。路径包含空格时，以维护提示实际生成的命令及客户端权限匹配结果为准。

流程显示“需要处理”时

先查看原生会话和卡片提示，再选择“核对后继续”“重发当前请求”或取消维护。取消时可选择释放消息或保留消息；保留的消息仍会阻挡后续消息插队。

Claude 压缩接口的等待超时后，管理流程会在维护期限内继续核对同一个压缩请求；确认原生压缩完成且会话空闲后发送恢复提示。服务重启会保留锁与流程，确认已有原生完成证据后才能续接。结果未知的消息或压缩不会自动重复执行。

常见问题

数据、升级与使用范围

中央消息、策略、SQLite 数据库、流程与队列保存在工具安装目录的 .cooperation/；交付文档保存在目标工作项目的 .cooperation/handoffs/。服务日志是 .cooperation/service.stdout.log 与 .cooperation/service.stderr.log。

备份前先正常关闭管理服务。备份工具的数据目录；需要保留上下文交接文件时，同时备份相应工作项目的 handoffs 目录。连接记录、保存的 Codex 桥连接和 wrapper 注册文件含本机连接信息，不应随源码公开。项目的 .gitignore 已排除中央运行数据、机器相关构建产物和本机验收记录。

从旧版升级时，服务会备份并导入旧 messages.jsonl，保留原文件。升级后以 SQLite 为写入来源；若旧日志随后被改动，启动会要求核对，避免形成两个不一致的数据来源。

当前支持同一台 Windows 机器上的会话协作。Cooperation 的锁覆盖本工具入口；原生界面输入与其他工具直连可以绕过它，观测到介入时流程会暂停。活动 goal、子agent 和后台任务的完整暂停与恢复尚未验收，此类目标暂不开放自动维护。

本地原生控制依赖客户端接口，客户端升级后可能需要适配。已验收基线为 Codex Desktop 26.901.6511.0 / Core 0.153.4、Claude Code VS Code 2.1.237；这些是验证版本记录，不是对最新版本的声明。

验证与进一步阅读

在仓库根目录执行：

.\scripts\build-claude-wrapper.ps1
node --test test/*.test.mjs

最近一次完整自动检查 167 项通过。Codex、Claude此前已完成各自软/硬维护原生验收。OpenCode 1.18.30也已通过隔离真实后端配合本地模拟模型的软/硬维护流程，验证原生工具回执、一次压缩及条件继续；管理页开关/阈值与手机布局验证通过。详情见 验证范围。

换账号或客户端重启后的维护接续

维护中客户端离线会显示“等待客户端重连”，保留会话锁及 FIFO 队列，暂停阶段超时。重新打开同一个会话后，管理器核对会话 ID、目录、可取得的模型和权限选项、交付文档哈希及原生历史。能够确认时自动接续，已接受的回执不要求重新提交。Codex/Claude可按现有恢复判据重发未完成提示；OpenCode对已提交但没有回执的提示保留待处理状态，不自动重发。

压缩只在原生完成证据充分时进入恢复，不会因为换账号就再次压缩。出现新业务输入、文档变化、已知设置变化或压缩结果不明时仍进入“需要处理”。缺少可核对历史时继续等待；不会读取登录凭据或替你切换账号。界面无需手动重发的前提是原会话仍可被唯一识别。