Nexus Relay

Nexus Relay

让 Claude、Codex 和 Antigravity 在一台 Windows PC 上共享交流空间。 Claude（Claude Code）可以将评审、第二意见和任务交给 Codex 和 Antigravity，再取回它们的答复，无需你在应用之间复制粘贴。每个 Agent 都在自己的桌面应用中使用自己的工具继续工作，而中继不会操控你的鼠标、键盘或剪贴板。

警告

实验性功能，仅支持 Windows。 唤醒 Codex 会通过其本地调试端口操作 Codex 桌面应用，唤醒 Antigravity 则会通过其 sidecar API。两者都取决于这些应用当前的外观和行为：应用更新可能导致唤醒失效，直到中继的界面映射得到更新（survey）。使用风险自负。

工作原理

flowchart LR
    C["Claude Code<br/>(host)"] -- "send / wait_reply" --> D["nexus-relay daemon<br/>127.0.0.1:16181"]
    D -- "one immutable JSON<br/>per message" --> B[("~/.nexus/relay")]
    D -- "debug port 9223:<br/>new chat in project<br/>'Nexus Relay'" --> X["Codex app"]
    D -- "sidecar + agentapi" --> A["Antigravity"]
    X -- "read / reply" --> D
    A -- "read / reply" --> D

1. Claude 调用 send(to, text, topic)。消息会写入本地交流空间，每条消息对应一个文件。
2. 守护进程会向接收方发送一条简短通知，其中只引用消息 ID，不包含消息内容：Codex 会在其“Nexus Relay”项目中收到一条新聊天，Antigravity 则通过中继的 sidecar 收到通知。
3. 接收方调用 read(id)，并通过 reply(id, text) 回复。Claude 使用 wait_reply(id) 等待。
4. 交流结束且 Agent 已有 10 s 未执行任务后，其对话会被归档（不会删除）。

一个 Agent 担任主机，默认是 Claude：只有主机可以发起交流，且主机不会被唤醒（它会等待答复）。其他 Agent 只能回复（或发布信息），因此不会相互触发形成循环。若没有 Claude Code，安装程序会将找到的第一个 Agent 设为主机（先 Codex，再 Antigravity）；可通过 host 设置更改主机。

要求

• Windows 10 或 11，无需管理员权限（会为你安装 uv 和 Python 3.14）。
• Claude Code、Codex 桌面应用和 Antigravity 中任选两个（任意组合；如果安装了 Claude Code，它就是主机）。

快速开始

1. 打开 PowerShell，粘贴：

   irm https://raw.githubusercontent.com/pironjulien/NexusRelay/main/get.ps1 | iex
   

   如果尚未安装 uv，此操作会安装它；随后将最新版本下载到 %LOCALAPPDATA%\NexusRelay\app，创建本地令牌（用户变量 NEXUS_MCP_TOKEN），启动后台守护进程（计划任务“Nexus Relay”），安装 Antigravity 插件和 sidecar，并将该服务配置到 Claude Code 和 Codex（令牌本身不会写入它们的文件）。再次运行即可更新。

2. 重启 Claude Code 和 Codex（彻底退出）。在 Codex 应用中执行一次：添加项目，名称为“Nexus Relay”，文件夹为 %USERPROFILE%\.nexus\relay\codex-projet。

3. 在 Claude Code 中询问：“使用 Nexus Relay，请 Codex 对此文件提供第二意见。” 使用 selftest(to="codex") 和 selftest(to="antigravity") 检查两个方向的通信。

从 PyPI 安装（一行命令，stdio）

同一服务也发布在 PyPI 和 MCP 官方注册表（io.github.pironjulien/nexus-relay）中。一行命令即可通过 stdio 为一个 Agent 启动服务，无需安装：

uvx --python 3.14 nexus-relay

将 NEXUS_RELAY_AGENT 设置为此连接代表的 Agent（claude、codex 或 antigravity）。例如，在读取 mcpServers JSON 的客户端中：

{
  "mcpServers": {
    "nexus-relay": {
      "command": "uvx",
      "args": ["--python", "3.14", "nexus-relay@latest"],
      "env": { "NEXUS_RELAY_AGENT": "claude" }
    }
  }
}

它与守护进程共用同一个房间（~\.nexus\relay）。上面的一行安装命令仍会完成所有设置：后台守护进程、Antigravity 插件和 sidecar、Codex 项目、令牌和更新。在 OneDrive 下使用时，向 uvx 添加 --link-mode copy（uv 的缓存无法在那里创建硬链接）。

手动安装

1. 设置（可选文件，位于仓库之外）— ~\.nexus\nexus-relay\settings.json：

   {
     "token_file": "C:\\path\\to\\nexus-mcp-token.txt",
     "vaults": ["C:\\path\\to\\secrets"],
     "codex_router": "http://127.0.0.1:2455/health/ready",
     "codex_router_start": ["\"C:\\path\\to\\router.exe\" --background"]
   }
   

   需要设置 token_file（或传入 -TokenFile、设置 NEXUS_MCP_TOKEN_FILE，或者让 install.ps1 -Register 创建本地文件）。

2. 安装 — 创建虚拟环境、注册守护进程、安装 Antigravity 插件和 sidecar，并运行测试：

   pwsh -NoProfile -File install.ps1
   

   守护进程在后台由一个小型监督程序（python -m nexus_relay.daemon）运行，由 install.ps1 创建并启动的计划任务“Nexus Relay”在登录时启动。它读取 ~\.nexus\daemons\specs\nexus-relay.json，在守护进程停止时重新启动它，并将日志写入 ~\.nexus\nexus-relay\daemon.log。

3. 连接各 Agent — 将用户环境变量 NEXUS_MCP_TOKEN 设置为令牌，然后：

   Claude Code

   claude/ 文件夹是一个 Claude Code 插件（MCP 服务 + 技能）。其 .mcp.json：

   {
     "mcpServers": {
       "nexus-relay": {
         "type": "http",
         "url": "http://127.0.0.1:16181/mcp?agent=claude",
         "headers": { "Authorization": "Bearer ${NEXUS_MCP_TOKEN}" }
       }
     }
   }
   

   Codex

   使用 codex/ 中现成的插件（MCP 服务和 nexus-relay 技能；持有者令牌从用户变量 NEXUS_MCP_TOKEN 读取），例如将此仓库添加为插件市场，并将 codex/ 设为其根目录。或者添加一个个人插件，其 .mcp.json 指向守护进程：

   {
     "mcpServers": {
       "nexus-relay": {
         "url": "http://127.0.0.1:16181/mcp?agent=codex",
         "bearer_token_env_var": "NEXUS_MCP_TOKEN"
       }
     }
   }
   

   然后，在 Codex 应用中执行一次：添加项目，命名为“Nexus Relay”，文件夹为 ~\.nexus\relay\codex-projet（由 install.ps1 创建）。Codex 应用必须以调试端口启动（当 Codex 处于空闲状态且你未使用它时，relay 会使用 --remote-debugging-port=9223 重新启动它）。

   Antigravity

   无需操作：install.ps1 会在 ~\.gemini\config\plugins 下安装 nexus-relay 插件（MCP 服务、技能和 sidecar）以及“Nexus Relay”项目。

然后，在 Claude Code 中输入：*"使用 Nexus Relay 请 Codex 审查此差异"。使用 selftest(to="codex") 和 selftest(to="antigravity") 端到端检查两个方向。

工具

工具	功能
send	在主题中向 codex 或 antigravity 发送消息（可附加附件和可选截止时间）；to=["codex", "antigravity"] 会同时询问两者（交叉审查）
wait_reply	等待答复（每次调用最多 600 s）；提供 ID 列表时，会等待所有答复
cancel	撤回收件人尚未接手的请求（不再唤醒对方；消息一经读取、处理中或已答复，就无法撤回）
reply	回复消息，并注明结果：已完成、已拒绝或失败
progress	告知主机你正在处理（不会唤醒任何人）
inbox, read	查看未读消息；读取一条消息
track	查看消息状态：已发布、响铃、已读取、处理中、已答复、已超时
close	关闭主题（其中的对话会存档）
reserve, release, reservations	编辑文件前预留文件，释放预留，列出文件的持有者
file_reservation_paths, release_file_reservations	使用 mcp_agent_mail 的名称和参数执行相同的预留操作
search, summary	对整个房间的历史记录进行全文搜索（SQLite FTS5 索引，不区分变音符号和大小写）；总结主题
status	未读计数、最近唤醒记录、响铃线程、Codex 端口、Antigravity sidecar、配额
selftest	查看两个应用的界面地标；使用 to 时，会进行真实的唤醒往返测试
where, survey	查找 Codex 或 Antigravity 中按钮或菜单的位置；刷新应用的界面地图

每个工具都带有 MCP 注解（readOnlyHint、destructiveHint 等）。读取工具（inbox、read、track、 search、summary、reservations、status）会声明输出架构并返回类型化的 structuredContent（相同的 JSON 也会保留在文本块中）；出错时会返回 isError。

设置

先从 ~\.nexus\nexus-relay\settings.json（此 PC）读取，再从已安装文件夹根目录下的 settings.local.json（由同步安装中的各 PC 共享）逐项读取；值可以使用环境变量 （%LOCALAPPDATA%、%USERPROFILE% 等），如果是列表，则采用第一个存在的 token_file。守护进程环境中 已设置的变量优先。

变量（守护进程）	settings.json 键	默认值	用途
NEXUS_MCP_TOKEN / NEXUS_MCP_TOKEN_FILE	token_file	—（必需）	本地守护进程的 Bearer 令牌
NEXUS_RELAY_VAULTS	vaults	无	文件永远不会附加到消息中的文件夹
NEXUS_RELAY_CODEX_ROUTER	codex_router	无	Codex 前置本地模型路由器的健康检查 URL；路由器停机时不会唤醒 Codex
NEXUS_RELAY_CODEX_ROUTER_START	codex_router_start	无	启动该路由器的命令，按顺序尝试（以 ; 分隔）
NEXUS_RELAY_HOME	—	~\.nexus\relay	房间位置
NEXUS_RELAY_CODEX_PORT, NEXUS_RELAY_AGY_PORT	—	9223, 9227	Codex 和 Antigravity 的调试端口
NEXUS_JOURNAL_HOME	—	%LOCALAPPDATA%\NexusJournal	操作日志
NEXUS_RELAY_UPDATE_CHECK	—	开启	0：永远不检查最新版本
NEXUS_RELAY_HOST	host	claude	唯一可开启交流的 Agent（claude、codex 或 antigravity）；不会被唤醒
NEXUS_RELAY_LANG	lang	en	Agent 收到的文本（工具结果、错误、唤醒文本）及已部署指令的语言：en 或 fr

更新

守护进程会自行更新：向其本地 API 的 /api/update 发送 POST 请求（使用与 /mcp 相同的 Bearer 令牌）会返回 202，随后守护进程会运行自己的 get.ps1（powershell -File，不显示窗口）来安装最新版本；然后守护进程会 重启并运行该版本。GET /api/update 会返回状态，该状态也会写入 ~\.nexus\status\relay.json：

{"product": "relay", "version": "1.3.0", "latest": "1.3.0", "state": "idle", "checked_at": "2026-10-26T10:00:00Z", "message": null}

state 为 idle、updating、done 或 failed（会保留先前版本，message 会说明原因）。只有通过单行安装程序（%LOCALAPPDATA%\NexusRelay\app）安装的版本才会自行更新；Git 检出版本会返回 409。再次运行 get.ps1 也会执行更新。

安全保障

• 所有服务仅监听 127.0.0.1；守护进程需要持有者令牌。
• Codex 不会在一轮对话期间或你正在使用时重新启动；你输入的草稿绝不会被覆盖；每次唤醒、成功或失败后，都会恢复你的视图、模式和项目。
• 只有在中继自己的 “Nexus Relay” 项目中创建的对话才会归档；只有在 Agent 的对话轮次结束 10 s 后才会归档，而且绝不会在你使用应用时归档。
• 如果无法确定消息是否已送达 Antigravity，会明确报告这一点，绝不会重放消息。
• 如果 Antigravity 未开启调试端口（例如它自行更新后），会在 5 min 后重新启动并开启调试端口；绝不会在你正在使用它或它的某个 Agent 正在工作时重启，且每小时最多一次。
• 同伴的消息会被标记为待审视的观点，而非来自你的指令；Agent 绝不会在中继对话中向你提问。
• 附件：只能使用绝对路径，且只能是单个名称的常规文件（不能是硬链接或网络共享文件），不得位于已配置的保险库中；每个附件最多 10 MB，每条消息最多 25 MB。

隐私

• 读取的内容：Agent 发送的消息、明确附加的文件、Codex 和 Antigravity 窗口（通过它们的本地调试端口打开聊天、检查消息是否送达以及归档中继对话）、Codex 的本地会话日志（用于判断中继聊天轮次何时结束，以及查询其配额）和 Antigravity 的设置页面（配额）。
• 数据去向：中继自身的传输仅在本地进行。它只与 127.0.0.1 通信（其守护进程、应用的调试端口、Antigravity 的 sidecar API，以及在已配置时与你的 Codex 路由器通信），此外每天最多向 https://github.com/pironjulien/NexusRelay/releases/latest 发送一次匿名请求，以获取最新版本（设置 NEXUS_RELAY_UPDATE_CHECK=0 可关闭此功能）。不过，已连接的 AI 通过中继读取的内容（消息、附件文件和图片）属于它的对话内容：Claude Code、Codex 和 Antigravity 会根据各自的隐私政策将这些内容发送给各自的模型提供商，就像处理你展示给它们的其他所有内容一样。请勿发布或附加任何你不愿直接交给这些应用的内容。
• 存储的内容：~\.nexus\relay\v1 中的消息和附件（纯 JSON，你的用户帐户可以读取）；~\.nexus\relay\v1\index 中这些消息的搜索索引（SQLite，删除后会根据消息重建）；~\.nexus\relay\v1\cartes 中两个应用的界面映射（元素角色和可见标签，其中可能包括屏幕上显示的对话标题）；以及 %LOCALAPPDATA%\NexusJournal\relay 中每项操作对应的一行记录（绝不包含消息正文）。
• 如何删除所有内容：删除计划任务 “Nexus Relay” 并停止其 pythonw 进程，然后删除 ~\.nexus\relay、~\.nexus\nexus-relay、~\.nexus\daemons\specs\nexus-relay.json、%LOCALAPPDATA%\NexusJournal\relay、~\.gemini\config\plugins 中的 nexus-relay 插件，以及 ~\.gemini\config\config.json 中的 sidecars 条目。

限制

• 仅支持 Windows；已在 Codex 桌面版 26.1021 和 Antigravity 2.26 上测试。
• 界面自动化本质上较脆弱：应用更新后，请运行 survey(app) 和 selftest。
• 主机不会被唤醒：它会通过 wait_reply 等待回复。Claude Code 完全无法被唤醒，因此如果使用其他主机，发给 Claude 的消息会留在其收件箱中等待。

开发

pwsh -NoProfile -File test.ps1   # ruff, pyright, pytest — offline, never touches the real apps

仓库副本（克隆、工作树）会使用自己的虚拟环境，因此测试该副本绝不会让已安装的中继切换到这个副本。

许可证

MIT