Codex Claude Bridge

连接 Codex、Claude Code 与 OpenCode 的已有会话，让长任务在上下文压缩后继续协作。

Codex Claude Bridge（管理页与命令名称：Cooperation）连接 Codex 桌面 App、VS Code 中的 Claude Code 和 OpenCode 原生后端。你在原生对话界面中为会话分配工作；agent 通过 MCP、CLI 或 OpenCode 插件交换任务、评审意见和结果。本地工作台集中展示多个项目的会话、消息、上下文用量与额度恢复状态。

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

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

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

核心特色

用户决定参与者与分工，agent 交换工作成果，Cooperation 传递消息、展示状态并执行获准的维护流程。

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

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

Related MCP server: promem-mcp

快速部署

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": "C:\\Tools\\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 连接，让它通过 wrapper 启动。若关闭面板后仍复用旧进程，重启对应的 VS Code 窗口。

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

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

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

4. 找到要协作的会话

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

地址形如：

codex://实现功能的会话:原生会话ID
claude://审查方案的会话:原生会话ID
opencode://复核测试的会话:原生会话ID

也可以使用短地址 codex:会话ID、claude:会话ID 或 opencode:会话ID。接收方由你指定；发送者由工具自动识别。 OpenCode 的发送入口与插件配置见 OpenCode 接入。

会话被发现只代表它存在。先打开准备使用的原生会话；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 表示投递结果未确认，需要先核对原会话。

Claude 原生端可能暂存或拒收跨会话消息，管理页会显示已观察到的暂存、过期和拒收状态。发送适配器按实际发送方的权限模式生成声明；无法核实时，消息明确保留在本地队列。跨权限类别的接收由 Claude 原生设置决定。已过期的消息需要核对接收设置后明确重新发送。

给 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 发送的消息。

自定义提示词

管理页右上角的 提示词设置 可编辑 Codex、Claude、OpenCode 消息前后缀、Claude 显示标签，以及交付、恢复、继续任务和额度恢复提示词。支持实时预览、插入变量、清空附加文字和恢复默认；修改后点击保存。设置覆盖此管理台的所有项目，普通消息在入队时固定配置，维护提示词从下一次发送起使用新内容。详见 提示词设置。

自动上下文维护

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

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

一次维护会发生什么

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

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

工具使用原会话当前的模型、思考强度和权限设置。三端均已取消思考强度和权限的前后一致性限制：这些设置与压缩前记录不同，本身不会阻塞维护或回执；OpenCode 在发送前读取最新 variant。原生权限审批仍由客户端执行。

会话身份、模型/代理、原生轮次、交付文档和回执仍需核对。维护包含模型参与的交付与恢复轮次，会使用原客户端的正常用量。

额度不足与恢复

启用自动管理后，Codex 和 Claude 的已核实额度中断会保留原任务与排队消息，并定期查询实际额度。Codex 的账户额度独立于当前会话活动状态显示；窗口名称按返回的真实时长标注。

• 额度可用、原轮次仍对应：核对会话状态后提交一次继续请求。

• 客户端未连接、存在待审批请求或未结束子任务：保留任务并显示具体等待原因，额度查询继续进行。Codex 已结束的历史子任务不会阻塞接续。

• 额度查询失败或必要窗口缺失：显示待查询或缺失信息，继续检测。

• 曾提交继续请求但结果未知：保留记录，先核对原生结果。

服务重新启动后，先在管理页确认需要接续的会话，再按上述条件推进。确认只覆盖所选会话。OpenCode 的 HTTP 429 会暂停维护和消息投递；当前尚无统一额度查询，需要在原会话处理限流后继续。详见 额度恢复 与 重启恢复。

回执遇到权限确认

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 上次压缩已确认失败且没有压缩边界时，可在额度和会话就绪后重新接续。

当前回复、额度或连接状态暂不允许操作时，按钮旁会说明原因。取消维护可选择保留待处理消息或发送待处理消息；保留的消息维持先后顺序。

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

客户端重连后的维护接续

客户端离线时，流程保留阶段、会话锁和 FIFO 队列。重新打开同一个原生会话后，管理器核对会话 ID、目录、模型/代理、文档哈希及原生历史，再接续能够确认的阶段；已接受的回执保留。

Codex、Claude 按恢复判据处理未完成提示；OpenCode 对已提交但没有回执的提示保留待处理状态，供核对后重试。新业务输入、文档变化或无法确认的压缩结果会暂停原流程。具体处理见 重启恢复。

常见问题

数据、升级与使用范围

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

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

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

更新代码后如何生效

只更新 Cooperation 管理端通常无需重启 Codex App。修改 MCP 配置时，仍需重新加载对应客户端的 MCP 连接。

当前支持同一台 Windows 机器上的会话协作。Cooperation 的维护锁覆盖本工具入口；原生界面出现新输入时，旧流程会暂停核对。活动 goal、未结束或无法核实的子任务和后台任务暂不开放自动维护；Codex 中有明确结束记录的历史子任务不受此限制。

本地原生控制依赖客户端接口。客户端升级后，应先核对连接、消息和维护行为；各版本的实际验收记录见 验证范围。

验证与进一步阅读

在仓库根目录执行：

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

截至 2026-10-08，最近一次完整自动检查为 385 项通过。回归覆盖重连与额度接续、取消与新输入竞态、未知结果保护、两阶段回执、一次压缩、FIFO，以及思考强度和权限变化后继承当前设置。

Codex、Claude 和 OpenCode 均有软/硬维护的原生验收记录；浏览器检查覆盖状态反馈、继续操作、消息队列及 390px 布局。版本、原生异常和恢复过程分别保存在 验证范围，本地原始日志不随源码发布。