codex-claude-bridge
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Plexus
本机 AI 编程会话的协作网络:不限客户端,自由拓扑。
Plexus 把同一台电脑上的 AI 编程会话连成一张网:Codex 桌面 App、VS Code 中的 Claude Code、OpenCode,以及通过会话接口接入的任意外部程序。每个会话都有自己的地址,知道地址就能给它发消息。谁和谁协作、按什么结构协作,由你和 agent 决定;Plexus 不预设主从关系或固定流程。
协作发生在原生会话里:Codex 留在桌面 App,Claude 留在 VS Code,各自沿用原任务、上下文和模型配置。本地管理页集中显示多个项目的会话、消息、上下文用量与额度状态。上下文快满时,Plexus 按你设定的阈值完成交付、压缩和恢复,长任务可以跨越压缩继续协作。
OpenCode 通信、上下文显示与自动维护已接入:插件支持软/硬阈值的交付、原生压缩、恢复和条件继续,默认按会话关闭。启用方法、原生验证及并发边界见 OpenCode 自动维护,安装与通信验收见 OpenCode 接入,桌面应用壳仍未验收。主动创建、加载会话方向已取消,见 取消与收尾。
本项目在 0.3.0 之前名为 Cooperation(仓库名 codex-claude-bridge)。从旧版升级见 从 Cooperation 升级。
快速部署 · 发送第一条消息 · 配置-mcp · 会话接口 · 自动上下文维护 · 常见问题
核心特色
特色 | 带来的体验 |
不限客户端 | Codex、Claude Code、OpenCode 的会话使用同一种地址和消息格式互发。外部程序(脚本、MCP 服务、后台任务)通过会话接口给指定会话发通知,在任务完成后唤醒它。 |
自由拓扑 | 任何会话都能给任何已知地址的会话发消息。一对一评审、一个协调者分派多个执行者、流水线逐级传递、多方互相讨论,都用同一套机制组织;增减成员不需要改动其他会话。 |
协作发生在已有原生会话中 | Codex 留在桌面 App,Claude 留在 VS Code;沿用原任务 ID、已有上下文和客户端模型配置。 |
消息可追溯 | 每条消息自动附带真实发送者的名称、地址和消息编号;管理页保存完整通信记录,投递结果如实标注已提交、接收端暂存、未送达或待核对。 |
一个工作台管理多个项目 | 按目录浏览会话,或将跨目录会话组成自定义项目;右侧集中查看成员、设置和通信。 |
长任务有完整的上下文交接流程 | 达到阈值后保存交付文档,取得回执,再原生压缩、加载上文、取得恢复回执;原本正在工作的任务才自动继续。 |
维护期间,协作消息有序等待 | 每个会话独立持有维护锁与持久队列,恢复后按先后顺序投递;服务重启后仍保留流程与队列。 |
额度恢复后接续原任务 | Codex、Claude 的已核实限额中断会定期查询额度,恢复并核对原轮次后提交一次继续请求。 |
轻量、本地运行 | Node.js 原生模块、SQLite、静态管理页,零 npm 运行依赖;状态只在变化时写盘;复用原客户端登录,无需另配模型 API Key。 |
用户决定参与者与分工,agent 交换工作成果,Plexus 传递消息、展示状态并执行获准的维护流程。几种常见组织方式:
评审:一个会话实现功能,另一个会话审查方案与变更,意见直接发回原会话。
分派:一个协调会话把子任务发给多个执行会话,各自完成后回报。
流水线:实现 → 测试 → 文档,每个会话完成后把成果交给下一个。
唤醒:长时间运行的脚本或 MCP 服务完成后,通过会话接口通知等待中的会话继续。
flowchart LR
C1[Codex:实现] <--> A1[Claude:评审]
A1 <--> O1[OpenCode:测试]
O1 <--> C1
C1 <--> A2[Claude:文档]
X[外部程序 / MCP 服务] -->|会话接口| A1上图是逻辑上的连接。实际消息都经过本机的 Plexus 服务转发和记录,所以任意两个会话之间都能直接通信;每个会话有独立的持久队列,维护期间收到的消息按顺序等待。
Related MCP server: promem-mcp
快速部署
1. 准备环境并获取项目
当前部署与原生验收以 Windows x64 为基线。
需要准备 | 用途 |
Node.js 22.13 或更新版本 | 运行本地服务、MCP 与 CLI;本项目已验证 Node.js 25.2.1。 |
已登录的 Codex 桌面 App(使用 Codex 时) | 使用已有 Codex 会话及本机发送桥。 |
VS Code 与已登录的 Claude Code 扩展(使用 Claude 时) | 使用已有 Claude 会话。 |
OpenCode(使用 OpenCode 时) | 安装方法见 OpenCode 接入。 |
Windows .NET Framework C# 编译器 | 构建 Claude 接入程序;构建脚本会检查本机是否已有。 |
Git,或下载后的源码 ZIP | 获取项目。 |
只需准备你要用的客户端;不用 Claude 时可以跳过下面的构建步骤。
git clone https://github.com/Heisenbear-Rebirth/plexus.git Plexus
cd Plexus
node --version
.\scripts\build-claude-wrapper.ps1无需运行 npm install 或构建前端。最后一步生成 bin/claude-wrapper.exe 和 bin/claude-wrapper.paths,其中包含本机路径;移动项目或换机器后重新构建。
下文统一以 C:/Tools/Plexus 为安装目录,请替换为你自己的完整路径。工具安装目录用于存放服务和数据;工作项目目录是 Codex、Claude 实际处理代码或文档的目录,两者可以不同。
2. 启动服务并连接 Codex
双击 启动项目.cmd,服务会在后台启动并打开管理页。重复启动会复用已有服务。管理页固定在 http://127.0.0.1:47821(IANA 未分配端口);可用 --port 或环境变量 PLEXUS_PORT 改用其他端口,0 表示随机。若 47821 被其他程序占用,服务会改用随机端口并在管理页顶部提示,此时以打开的页面为准。
首次使用时,为 Codex 配置一次 Plexus MCP,重新连接该 MCP。页面右上角显示 “Codex 已连接” 后,即可向 Codex 发消息。只使用 CLI 时,也可以让 Codex 在自己的命令工具中运行一次:
node "C:/Tools/Plexus/bin/plexus-service.mjs" start工具会在本地保存已授权的连接,并在启动和发送前检查连通性。以后正常双击启动即可,不再要求每次都从 Codex 会话启动。 配好 MCP 后,Codex 重新接入时会自动更新连接,运行中的管理服务会自动重连,无需重启服务。
操作 | 入口与效果 |
打开或启动管理页 | 双击 |
关闭服务 | 双击 |
在终端查看运行日志 |
|
Codex App 需要保持可用。断开时页面会显示“Codex 待连接”;打开 Codex 并连接 Plexus MCP 后,状态会自动更新。工具只复用本机已经取得的授权连接,投递结果不确定的消息仍需核对,不会自动重发。
3. 接入 Claude Code
在 VS Code 的用户设置 JSON 中,合并下面这一项,指向刚构建的文件:
"claudeCode.claudeProcessWrapper": "C:\\Tools\\Plexus\\bin\\claude-wrapper.exe"这是一项 VS Code 用户级配置,由你明确选择是否启用;构建和启动服务不会自动写入它。保留其他设置;已有其他 wrapper 时,先核对如何整合。该程序会启动扩展原本选定的 Claude,并转发其输入、输出和权限交互。
已接入 wrapper 的新进程会尝试显示 Plexus 的 peer 消息,并标注“Plexus 会话消息”。仅转换原生回显的界面副本,不向 Claude 重发、不打断当前工具。现有进程不会热更新;待工作结束后再正常重开面板。该功能已通过隔离协议测试及专用 Claude 会话的工作中投递测试,用户确认面板出现消息气泡;本次消息在原任务结束后被处理,不保证入队即刻显示。默认关闭重开时的自动历史补显,避免旧消息集中出现在对话末尾。新消息的实时显示保留,同一会话内同编号的实时/历史回放共用去重记录。重开后原生面板可能不再显示旧协作消息,可在 Plexus 管理页查看通信历史。历史补显仅可通过独立的 peerHistoryVisibility: true 或 PLEXUS_PEER_HISTORY_VISIBILITY=1 显式启用,仍会在末尾补回而非原位置;详见 wrapper 说明。若原生没有输出对应回显,不会凭传输提交结果补造已收到消息。设置启动环境变量 PLEXUS_PEER_MESSAGE_VISIBILITY=0 可关闭此功能;也可在项目 .plexus/claude-wrapper/config.json 中设置 peerMessageVisibility: false,在下次启动 wrapper 时生效。
随后在管理页:
添加 Claude 实际工作的项目目录。
打开目录旁的 “项目设置”,开启 “Claude 控制接入”。
在当前任务结束后重启 Claude 连接,让它通过 wrapper 启动。若关闭面板后仍复用旧进程,重启对应的 VS Code 窗口。
确认原面板的模型、思考强度与权限选项符合你的预期,并检查管理页是否显示连接状态。
“Claude 控制接入”覆盖项目的目录范围:勾选“包含子目录”后,子目录会话自动继承接入,无需逐个添加;取消勾选时撤回继承。单独设置过的子项目按更具体的设置处理。这个开关与会话的“自动管理”相互独立。
详细接入、协议说明与回滚步骤见 Claude 原生控制接入。
4. 找到要协作的会话
在管理页左上选择 “目录项目”,点击 + 添加工作目录,按需开启 “包含子目录”。展开项目后直接显示会话,灰色客户端名称位于会话名称后。点击会话,在右侧点击 “复制地址”。
地址形如:
codex://实现功能的会话:原生会话ID
claude://审查方案的会话:原生会话ID
opencode://复核测试的会话:原生会话ID也可以使用短地址 codex:会话ID、claude:会话ID 或 opencode:会话ID。接收方由你指定;发送者由工具自动识别。 OpenCode 的发送入口与插件配置见 OpenCode 接入。
会话被发现只代表它存在。先打开准备使用的原生会话;Codex 自动维护需要任务已在 App 中加载,Claude 接收和控制需要相应连接在线。
发送第一条消息
通过 CLI:无需先配置 MCP
把下面的提示发给 Codex 发送方会话,替换目标地址与正文:
请通过 Plexus CLI 向以下目标会话实际发送消息,并告诉我投递结果:
node "C:/Tools/Plexus/bin/plexus.mjs" send --client codex --to "这里粘贴目标会话地址" --text "请审查我的实现方案,并通过 Plexus 把意见发回本会话。"如果发送方是 Claude Code,把 --client codex 改为 --client claude。该参数表示谁在发送;--to 表示发给谁。
CLI 应由原会话的命令工具执行,以便取得该会话的身份。从独立 PowerShell 手工执行可能无法确认发送者。
长消息、代码片段或复杂引号内容适合先写入发送方获准目录内的 UTF-8 文本文件,再发送:
node "C:/Tools/Plexus/bin/plexus.mjs" send --client claude --to "codex:目标会话ID" --file "E:/Work/MyProject/review.txt"正文前会自动带上发送方地址。接收方可以用这个地址回信;是否回复、何时回复由任务要求和 agent 决定。
怎样确认第一次协作成功
在目标原生会话中看到消息及发送方信息。
在管理页选择相关会话,切换右侧 “通信记录”,找到同一条消息。
让接收方回一条消息,并在原发送方会话中确认收到。
submitted 表示消息已提交到客户端通道;对方的回复或原生接收记录可用于核对处理进度。确认较慢时先返回 pending,服务在后台继续等待,状态会自动更新,无需重复发送。
Codex 投递确认最多等待两分钟。若仍为 unknown,服务会自动核对接收会话的原生记录;只有消息编号、完整正文和时间都匹配时,才确认送达并继续后续队列。没有匹配记录时保留未知状态,避免重复执行;此时仍可在消息详情核对处理。其他客户端的未知结果继续按各自的原生证据判断。
Claude 原生端可能暂存或拒收跨会话消息。发送适配器按实际发送方的权限模式生成声明;无法核实时,消息明确保留在本地队列。跨权限类别的接收由 Claude 原生设置决定:原生把 bypassPermissions(以及可切回绕过权限的 plan 模式)归为绕过类,auto、default、acceptEdits、dontAsk 均为需审批类,两类之间的消息会被暂存;VS Code 面板没有批准入口,到期(默认约 5 分钟)后过期。
管理页右上角 “通信设置” 提供 “允许不同权限模式互发消息” 开关,默认关闭。开启后,已允许 Claude 连接的会话由 wrapper 在其原生进程的会话级设置层写入 crossSessionInbound: "accept",不再比较权限类别;关闭时移除该项,恢复原生规则。切换即时生效,不写入 Claude 的设置文件,也不冒用发送方的权限声明。托管策略设置的 crossSessionInbound 优先,项目设置只能收紧,对话框会显示各会话读回的实际生效情况。开启后,需审批模式的会话若读到被注入的内容,可借“绕过权限”的会话执行操作,只在信任全部协作会话时开启。该开关需要 wrapper 更新后重开过的 Claude 面板。
提交后服务会等待接收端的原生裁定(最多约 1.5 秒):被暂存时发送方直接收到 receiver_held(接收端暂存)及原因,不再只返回 submitted;之后过期、拒收或丢弃时,通信记录自动改为 undelivered(未送达),MCP 与 CLI 按失败处理。已过期的消息不会自动重发,需统一双方权限模式或核对接收设置后明确重新发送。
给 agent 的协作约定
下面这段适合放在任务开头,或由你决定加入工作项目的指令文件:
本任务允许通过 Plexus 与以下会话协作:
对方地址:<粘贴地址>
对方分工:<例如:审查方案、复核测试结果>
需要对方协助时,优先使用已加载的 Plexus send_message 工具;未加载 MCP 时使用本机 Plexus CLI。
发送时说明目标、必要背景、需要对方完成的事项和相关文件位置。
取得反馈后结合当前任务处理;需要回复时使用消息中附带的发送方地址。
发送后检查投递结果;结果不确定时先核对原会话。Plexus 负责通信和上下文维护。任务分工、文件修改范围与结果验收由你和参与会话约定。
配置 MCP
CLI 和 MCP 都连接同一个管理服务。配置 MCP 是让 agent 能直接调用工具;它不会替你启动管理服务或完成 Claude 接入。
把配置放在需要调用工具的工作项目中,并把其中的安装路径替换为自己的路径。已有配置文件时合并相应条目。
Codex
在工作项目的 .codex/config.toml 中加入以下配置;Codex 需要信任该项目才能加载项目级配置。配置位置和格式参见 OpenAI MCP 文档。
[mcp_servers.plexus]
command = "node"
args = ["C:/Tools/Plexus/bin/plexus.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": {
"plexus": {
"command": "node",
"args": ["C:/Tools/Plexus/bin/plexus.mjs", "mcp", "--client", "claude"]
}
}
}重新加载对应客户端的 MCP 配置,完成客户端要求的信任或权限确认,并检查 plexus 是否已连接。配置样例也保存在 Codex 与 Claude 文件中。
让会话调用 MCP
请实际调用 Plexus MCP 的 send_message 工具:
to:<粘贴目标会话地址>
message:请审查刚才的方案,完成后通过 Plexus 回复本会话。
调用后告诉我投递结果。本项目提供三个业务工具:
工具 | 参数 | 用途 |
|
| 向指定会话发送消息。 |
|
| 在收到维护请求后,确认交付或恢复阶段。 |
| 无 | 取得本会话的会话接口,交给外部程序在完成后唤醒本会话。 |
会话发现和通信历史由用户在管理页查看,agent 根据用户提供的地址工作。维护回执所需参数由系统下发,日常发消息只需使用 send_message。
会话接口:让外部程序唤醒会话
每个会话可以开启一个专用接口。外部程序(例如执行长任务的 MCP 服务、后台脚本)凭接口密钥向该会话发送消息;会话空闲时会被唤醒,工作中则按顺序排队。消息走普通协作通道,标注为“外部程序”,不是用户指令,也不能回复。
取得接口,任选其一:
管理页选中会话,点击 “会话接口” → “开启接口”,复制密钥或调用方式。这里也可以重置密钥(旧密钥立即失效)或停用接口。
让会话自己调用 MCP 工具
session_interface,或运行node "C:/Tools/Plexus/bin/plexus.mjs" hook --client claude(Codex 用--client codex)。适合让 agent 把自己的接口交给它启动的任务。
调用接口,推荐命令行;即使端口因占用而改变,命令行也会自动找到当前服务:
node "C:/Tools/Plexus/bin/plexus.mjs" notify --hook <接口密钥> --source "训练任务" --text "训练已完成,结果在 out/report.md"密钥也可放在环境变量 PLEXUS_HOOK_KEY 中;长内容用 --file。也可以直接发 HTTP,默认地址固定为 http://127.0.0.1:47821(端口被占用而改用其他端口时,以安装目录 .plexus/connection.json 的 url 为准),主机名必须是 127.0.0.1:
POST http://127.0.0.1:47821/api/hooks/notify
Authorization: Bearer <接口密钥>
Content-Type: application/json
{"text":"训练已完成,结果在 out/report.md","source":"训练任务"}返回值与 send 相同(messageId、status、detail);undelivered 时 CLI 以非零退出。
一个会话只有一个接口;密钥只决定目标会话,请求里不能另指接收方。
每个接口每分钟最多 30 次调用;密钥错误、已重置或已停用的调用会被拒绝,不会进入任何会话。
外部程序没有权限类别,Claude 消息不附带权限声明。接收方是“绕过权限”模式时,需要在“通信设置”中开启“允许不同权限模式互发消息”,否则消息会被原生暂存后过期。
持有密钥即可向该会话发消息,只交给可信的程序。agent 不能重新启用用户停用的接口。OpenCode 会话请在管理页开启。
管理页怎么用
项目导航:左侧抽屉显示可折叠项目与单行会话。Claude、Codex、OpenCode 以灰色名称跟在会话后,状态圆点提示连接与活动。搜索项目或会话,点击“已连接”筛选;左上导航按钮可收起侧栏。
项目概览:点击项目名称,右侧展示成员与连接统计;点击成员进入其设置。目录旁的“···”可编辑项目名称、子目录范围和 Claude 控制接入。
会话设置:右侧显示上下文占用、模型、活动状态和统计时间。自动管理使用开关,阈值可输入或拖动;失焦、按 Enter 或松开滑块后自动保存。关闭自动管理后继续观察用量,未知容量保持未知。
通信记录:选择项目时显示涉及该项目成员的发送与接收,选择会话时聚焦该会话。消息支持关键词、状态筛选;点击消息阅读完整正文和投递结果。折叠导航不改变当前选中的通信范围。
连接与维护:会话设置中保留连接帮助、刷新状态、维护接续与队列处理。OpenCode 的自动管理开关按原生插件维护能力开放。
自定义项目:按协作目标组织会话
先在“目录项目”中添加会话来源目录。
切换左上 “自定义项目”,点击 +,填写组名并点击所需会话加入。可跨目录选择,也可按名称、目录或客户端搜索。
保存后,组名成为左侧项目标题,下方只展示所选成员。使用“编辑分组”改名或调整成员。
同一会话可以出现在多个组中,并共享原来的会话设置。分组成员与名称保存在本地管理数据库,服务重启后保留;暂时离线或未发现的成员仍显示在组中。删除分组只移除组织关系,保留会话、策略和通信历史。多个窗口同时编辑时会核对版本,提示重新打开已被修改的分组。
页面采用浅灰侧栏、白色内容区与绿色操作强调,主要空间留给所选项目或会话。目录、消息列表和正文各自滚动;手机宽度下项目导航为覆盖式抽屉。长消息实时刷新保持阅读位置。管理页中的通信记录只包含经 Plexus 发送的消息。
自定义提示词
管理页右上角的 提示词设置 可编辑 Codex、Claude、OpenCode 消息前后缀、Claude 显示标签,以及交付、恢复、继续任务和额度恢复提示词。支持实时预览、插入变量、清空附加文字和恢复默认;修改后点击保存。设置覆盖此管理台的所有项目,普通消息在入队时固定配置,维护提示词从下一次发送起使用新内容。详见 提示词设置。
自动上下文维护
每个会话有独立的 “自动管理” 开关,默认关闭。先确认会话接入和通信正常,再按需启用。
客户端 | 空闲阈值 | 优先阈值 |
Codex | 40% | 55% |
Claude Code | 50% | 80% |
OpenCode | 50% | 80% |
空闲阈值表示:达到该占用后,等待当前工作结束再维护。优先阈值表示:工作过程中达到该占用,先中断对应轮次,再进行维护。数值可按会话修改;必须满足 0 < 空闲阈值 < 优先阈值 < 100。已启用时降低阈值可能立即触发维护。
一次维护会发生什么
达到阈值 → 锁住 Plexus 入站消息 → 必要时中断原工作
→ 写交付文档 → handoff 回执 + 本轮结束
→ 原生压缩完成
→ 读取交付文档、加载上文 → restored 回执 + 本轮结束
→ 原本工作中才继续任务 → 按顺序投递排队消息交付文档保存接续任务所必需的信息,比如当前进展、关键约束或容易遗漏的事项,具体内容和组织方式由 agent 判断;文档写入目标会话工作目录的 .plexus/handoffs/。两个回执都校验身份、阶段凭证与文档内容;普通回复 OK 不会推进流程。
工具使用原会话当前的模型、思考强度和权限设置。三端均已取消思考强度和权限的前后一致性限制:这些设置与压缩前记录不同,本身不会阻塞维护或回执;OpenCode 在发送前读取最新 variant。原生权限审批仍由客户端执行。
会话身份、模型/代理、原生轮次、交付文档和回执仍需核对。维护包含模型参与的交付与恢复轮次,会使用原客户端的正常用量。
额度不足与恢复
启用自动管理后,Codex 和 Claude 的已核实额度中断会保留原任务与排队消息,并定期查询实际额度。Codex 的账户额度独立于当前会话活动状态显示;窗口名称按返回的真实时长标注。
额度可用、原轮次仍对应:核对会话状态后提交一次继续请求。
客户端未连接、存在待审批请求或未结束子任务:保留任务并显示具体等待原因,额度查询继续进行。Codex 已结束的历史子任务不会阻塞接续。
额度查询失败或必要窗口缺失:显示待查询或缺失信息,继续检测。
曾提交继续请求但结果未知:保留记录,先核对原生结果。
服务重新启动后,先在管理页确认需要接续的会话,再按上述条件推进。确认只覆盖所选会话。OpenCode 的 HTTP 429 会暂停维护和消息投递;当前尚无统一额度查询,需要在原会话处理限流后继续。详见 额度恢复 与 重启恢复。
回执遇到权限确认
Codex/Claude维护提示优先要求调用 context_checkpoint;未加载 MCP 时,会提供专用 CLI 命令。Claude 如果要求执行授权,可以按原权限流程批准。OpenCode使用插件工具 plexus_context_checkpoint 绑定原生身份,不使用CLI代填会话来源。
若希望在特定工作项目中允许该专用入口,可由你在该项目的 .claude/settings.local.json 中合并窄规则,例如:
{
"permissions": {
"allow": [
"Bash(node C:/Tools/Plexus/bin/plexus-checkpoint.mjs *)"
]
}
}保留已有权限条目,并使用实际安装路径。该许可只覆盖专用回执 CLI;工具不会自动安装这条规则。路径包含空格时,以维护提示实际生成的命令及客户端权限匹配结果为准。
流程显示“需要处理”时
卡片按当前阶段提供可执行操作:
检查并继续:核对已有压缩、回执和原生轮次后接续。
按当前进度继续维护:尚未提交压缩的暂停流程可重新保存最新进度,旧文档与回执保留。
重新保存进度并继续整理:Claude 上次压缩已确认失败且没有压缩边界时,可在额度和会话就绪后重新接续。
当前回复、额度或连接状态暂不允许操作时,按钮旁会说明原因。取消维护可选择保留待处理消息或发送待处理消息;保留的消息维持先后顺序。
Claude 压缩接口的等待超时后,管理流程会在维护期限内继续核对同一个压缩请求;确认原生压缩完成且会话空闲后发送恢复提示。服务重启会保留锁与流程;先在前端弹窗确认待接续会话,再核对原生完成证据后续接。结果未知的消息或压缩不会自动重复执行。
客户端重连后的维护接续
客户端离线时,流程保留阶段、会话锁和 FIFO 队列。重新打开同一个原生会话后,管理器核对会话 ID、目录、模型/代理、文档哈希及原生历史,再接续能够确认的阶段;已接受的回执保留。
Codex、Claude 按恢复判据处理未完成提示;OpenCode 对已提交但没有回执的提示保留待处理状态,供核对后重试。新业务输入、文档变化或无法确认的压缩结果会暂停原流程。具体处理见 重启恢复。
常见问题
现象 | 检查与处理 |
管理页能打开,但消息发不到 Codex | 查看右上角 Codex 连接状态,确认 Codex App 已打开、Plexus MCP 已连接,且配置中包含示例的三个 env_vars。已有服务会自动重连,无需反复关闭和启动。 |
Codex 显示“未加载” | 在 Codex App 中打开这个已有任务,再检查状态。独立自动维护通道目前不自动唤醒未加载任务。 |
Claude 能被发现,但接收或控制不可用 | 检查 wrapper 已构建、VS Code 配置路径正确、实际工作目录已允许“Claude 控制”,并重新打开面板。 |
Claude 已连接,但提示接入需要更新 | 当前原生进程仍使用旧代码。任务结束后重启对应 Claude 连接;仅刷新管理页或切换面板不足以更新它。 |
额度可用却仍等待 | 查看会话就绪原因与本次启动的接续确认。待审批请求、未结束或无法核实的子任务仍会等待;已结束的历史子任务不应阻塞。 |
Claude 消息显示“接收端暂存”或“未送达” | 核对双方权限模式是否同属绕过类或同属需审批类(例如一方 |
管理页没有消息 | 选择左侧项目或会话,打开“通信记录”,检查已连接、关键词与状态筛选;这里只展示经过本工具的通信。 |
会话说找不到 | 确认 MCP 配置在该会话工作项目内且已加载;可以先用 CLI 发消息。 |
CLI 报告无法识别当前会话 | 让 Codex 或 Claude 的原生命令工具执行;不要手工填写或伪造发送者环境变量。 |
配置了 MCP,却提示管理台未启动 | MCP 进程和管理服务是两个入口;先启动管理服务。 |
修改后没有自动压缩 | 确认卡片保存成功、开关已启用、统计可用且达到阈值;空闲阈值会等工作结束。 |
消息状态为 | Codex 会自动核对完整的原生接收记录,确认后继续队列;没有可核实记录或其他客户端仍显示未知时,在原会话核对后从消息详情确认结果。不要新建重复消息。 |
移动项目后 Claude 接入失效 | 在新位置重新构建 wrapper,并更新 VS Code 与 MCP 中的绝对路径。 |
构建提示找不到 | 检查环境要求;脚本不会自动安装软件。 |
PowerShell 阻止构建脚本执行 | 查看具体策略提示,按本机或组织规则允许所需脚本;无需为部署关闭全局安全策略。 |
数据、升级与使用范围
中央消息、策略、SQLite 数据库、流程与队列保存在工具安装目录的 .plexus/;交付文档保存在目标工作项目的 .plexus/handoffs/。服务日志是 .plexus/service.stdout.log 与 .plexus/service.stderr.log。
会话状态每隔几秒采样一次,但只有内容变化时才写入数据库并通知管理页;仅采样时间不同的结果只保存在内存中。Claude 面板或 OpenCode 后端被强制关闭时,来不及删除自己的注册文件;管理服务发现对应进程已退出后,会删除这些文件。所有 Codex 会话共用一条到 Codex 的连接;Codex 历史库没有变化时,会话发现直接沿用上次的结果。会话已不存在(例如记录被删除)而自动管理仍开启时,每分钟才重新查找一次;不再需要时,可在管理页关闭它的自动管理。
备份前先正常关闭管理服务。备份工具的数据目录;需要保留上下文交接文件时,同时备份相应工作项目的 handoffs 目录。连接记录、保存的 Codex 桥连接和 wrapper 注册文件含本机连接信息,不应随源码公开。项目的 .gitignore 已排除中央运行数据、机器相关构建产物和本机验收记录。
从旧版升级时,服务会备份并导入旧 messages.jsonl,保留原文件。升级后以 SQLite 为写入来源;若旧日志随后被改动,启动会要求核对,避免形成两个不一致的数据来源。
从 Cooperation 升级
0.3.0 起项目更名为 Plexus,命令、MCP 名称、数据目录和环境变量随之更改:
旧名称 | 新名称 |
|
|
MCP 服务名 |
|
OpenCode 插件工具 |
|
数据目录 |
|
环境变量 |
|
Claude 消息标签 |
|
升级步骤:
双击“关闭项目”停止服务。更新代码后的关闭脚本也能识别并停止旧版服务。
更新代码,重新运行
.\scripts\build-claude-wrapper.ps1。双击“启动项目”。首次启动时,安装目录的
.cooperation/自动迁移为.plexus/;.plexus/中已有同名项时保留旧项,并在管理页提示。提示词设置中仍是旧默认标签的部分改为新标签,你自己写的内容不变。在 Codex、Claude Code、OpenCode 的配置中,把 MCP 服务名改为
plexus,命令改为bin/plexus.mjs,再重新加载 MCP 连接。Claude 的权限规则若写了mcp__cooperation__…或coop-checkpoint.mjs,一并更新。在任务结束后重新打开 Claude 面板、重启 OpenCode 后端,加载新版 wrapper 与插件。
工作项目中已有的交付文档留在原来的 .cooperation/handoffs/,新的交付文档写入 .plexus/handoffs/。如果工作项目的 .gitignore 忽略了 .cooperation/,请同样忽略 .plexus/。
更新代码后如何生效
更新位置 | 加载方式 |
管理服务 | 正常关闭并重新启动 Plexus;按弹窗选择需要接续的会话。 |
管理页 | 完整刷新浏览器页面。已加载新版页面后,“更新状态”和服务重连还会更新维护提示规则,并保留未保存的提示词草稿。 |
Claude wrapper | 任务结束后重启对应的 Claude 连接;若仍复用旧进程,重启对应 VS Code 窗口。 |
OpenCode 插件 | 任务结束后重启原 OpenCode 后端,加载新的通信与维护逻辑。 |
只更新 Plexus 管理端通常无需重启 Codex App。修改 MCP 配置时,仍需重新加载对应客户端的 MCP 连接。
当前支持同一台 Windows 机器上的会话协作。Plexus 的维护锁覆盖本工具入口;原生界面出现新输入时,旧流程会暂停核对。活动 goal、未结束或无法核实的子任务和后台任务暂不开放自动维护;Codex 中有明确结束记录的历史子任务不受此限制。
本地原生控制依赖客户端接口。客户端升级后,应先核对连接、消息和维护行为;各版本的实际验收记录见 验证范围。
验证与进一步阅读
在仓库根目录执行:
.\scripts\build-claude-wrapper.ps1
node --test test/*.test.mjs截至 2026-11-10,完整自动检查共 458 项,457 项通过。未通过的一项是启动脚本测试:在中文代码页下,cmd 无法解析中文脚本文件名,与功能无关。回归覆盖子目录接入继承与撤回、重连与额度接续、取消与新输入竞态、未知投递的原生回执核对、原生暂存与过期的回传、会话接口、空闲时的资源占用、更名后的数据迁移、大会话快照、两阶段回执、一次压缩、FIFO,以及思考强度和权限变化后继承当前设置。
Codex、Claude 和 OpenCode 均有软/硬维护的原生验收记录;浏览器检查覆盖状态反馈、继续操作、消息队列及 390px 布局。版本、原生异常和恢复过程分别保存在 验证范围,本地原始日志不随源码发布。
文档 | 内容 |
自动测试、原生验收与当前边界。 | |
wrapper 构建、设置、协议与回滚。 | |
原生插件、回执、压缩与接续。 | |
接续确认、离线、额度与不同启动顺序。 | |
三端沿用当前思考强度与权限设置,以及消息声明修复。 | |
区分已结束的历史记录与仍待核实的工作。 | |
会话状态、阈值与维护流程的设计依据。 | |
分阶段实现与验收路径。 |
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Share one project context across ChatGPT, Claude, Telegram and any MCP client.
Shared memory for your AI tools: tasks, notes and context every tool can read and write over MCP.
Project management shared by people and AI agents, with persistent project state through MCP.
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceMulti-project execution, memory, and collaboration platform for humans and AI agents, providing MCP tools for agents to read and write project state.3MIT
- AlicenseBqualityCmaintenanceEnables AI coding agents to maintain persistent project context, including rules, decisions, environment intelligence, and Git history, using a local-first MCP server with automatic project detection and token-efficient retrieval.13MIT
- AlicenseCqualityCmaintenanceEnables coding agents to coordinate around shared project context, durable tasks, messages, artifacts, multimodal analysis requests, design-system checks, change proposals, and review requests through a compact MCP interface. It persists state locally in JSON and exposes tools, resources, and prompts for agent-to-agent workflows.9MIT
- AlicenseNot gradedqualityBmaintenanceProvides AI coding agents with shared project memory, compact evidence-first context, status checks, durable handoffs, and encrypted cross-device checkpoints through MCP.1AGPL 3.0