OpenRig cross-host架构深度解析：在多台机器上运行一个Agent团队

OpenRig cross-host架构深度解析：在多台机器上运行一个Agent团队

【免费下载链接】openrigMulti-agent harness that runs Claude Code and Codex together as one system项目地址: https://gitcode.com/GitHub_Trending/op/openrig

OpenRig 是一个开源的多智能体运行框架（multi-agent harness），能把 Claude Code 与 Codex 组合成一支可持久化、可恢复、可观测的 Agent 团队。它的 cross-host（跨主机）架构更进一步：让你把这支 Agent 团队拆开放到多台机器上运行，却仍然像一个统一系统那样协调、寻址和通信。

一、为什么 Agent 团队需要多台机器

单台机器运行多个 Agent 会遇到三个瓶颈：

• 🖥️资源挤占：多个模型会话同时编译、测试，CPU 和上下文窗口互相争抢；
• 🌐环境割裂：有的 Agent 需要 macOS 环境，有的更适合 Linux 服务器；
• 🔒隔离不足：不同权限、不同密钥的 Agent 挤在同一台机器上，信任边界模糊。

OpenRig 的单机模型是：一份 YAML 拓扑（RigSpec）→rig up一条命令启动 → 每个 Agent 一个 tmux 会话，由本地 Daemon（HTTP 服务 + SQLite）统一管理。TUI 里可以直接看到团队全貌：

cross-host 架构在这个模型之上只做一件事的扩展：把"一台机器上的一个 Daemon"变成"N 台机器上的 N 个 Daemon，外加一张把它们连起来的注册表"。

二、三层骨架：本地 Daemon、主机注册表与传输通道

注意"每个容器/主机一个 Daemon、本地数据库、本地 HOME，唯一共享面是网络"这条原则——它保证了任何一台机器宕机都不会污染其他主机的状态。

三、一行命令注册远程主机：rig host 速览

主机注册表就是主机之间的"通讯录"。常用动词：

rig host add --id <主机id> --transport http --url http://B:7433 --bearer-env TOKEN_ENV rig host ls --json # 查看已注册主机 rig host select <id> # 持久化"当前主机"指针（类似 kubectl 的 current-context） rig host doctor # 分步体检：连通性、认证、daemon 可达性 rig host pair # 双向配对握手

两条值得记住的设计细节：

• 🚫保留字：kernel、host、local以及虚拟域令牌永远不能被注册为主机别名，避免寻址歧义（见 host-registry.ts 的RESERVED_HOST_IDS）；
• 🔐密钥卫生：注册表里只存认证指针（环境变量名或文件路径），任何代码路径都不会把 token 明文落盘。

四、两种传输方式：HTTP 直连与 SSH 单跳

HTTP 直连

Daemon 以 HTTP 暴露后，注册表记录url+ bearer 指针即可。这里有一道强制护栏：Daemon 一旦绑定非 loopback 地址，必须同时配置OPENRIG_AUTH_BEARER_TOKEN，否则拒绝启动——跨网络可达性与鉴权是耦合在一起的。

SSH 单跳

适合没有开放端口的场景。执行器通过一次 ssh 调用在远端跑sh -lc "rig ..."，并且刻意区分五种失败模式，让你知道该修哪一层：

把"修 SSH"和"修远端 Daemon"混成一个 failed，是多数多机系统的通病；OpenRig 在 cross-host-types.ts 中把它们显式拆开了。

五、跨主机寻址：三段式地址 seat@rig@host

OpenRig 里的座位地址是成员@rig（如dev-owner@first-project）。cross-host 加了一段主机限定：

rig send dev-main@rig-b@B "ping" --host B

解析规则很克制（见 cross-host-target.ts）：

• 形如X@Y@Z且Z恰好是已注册主机 id → 拆成target=X@Y、host=Z；
• Z不是已注册主机 → 原样透传并响亮报错，绝不下沉成静默歧义；
• 优先级：显式--host> 目标糖语法 >rig host select持久化选择；同一命令里两者冲突会直接报错。

六、身份三重奏：跨主机消息如何精确回家

跨主机协作最容易出 bug 的是"回信"。OpenRig 用身份三重奏成员@rig@selfHostId解决：

1. id 是读的，不是猜的：每台主机的selfHostId由 daemon 端铸造、存为永不改写的单例，你只能从/healthz捕获它（L5 runbook 明确要求 "adopt-by-read"）；
2. 发送即盖章：跨主机 send 会把来源主机写进发件人身份，From: orch@rig-a@A，回复原样回到 A；
3. 同名 rig 碰撞：A、B 两台机器各有一个叫shared的 rig 时，回复只落回来源主机的座位，绝不误投给本地"同名替身"；
4. 优雅降级：来源 Daemon 停止后，From:降级为两段式而不是崩溃（fail-open 控制实验就内置在测试夹具里）。

这套行为有完整的可复现验证脚本：L5 多主机 runbook 用两个容器模拟两台命名主机，把注册、盖章、碰撞、降级全部跑成自动化证据。

七、动手实践：在两台机器上运行一个 Agent 团队

第 0 步｜两台机器装好前置：Node.js 22/24 + tmux，然后npm install -g @openrig/cli。

第 1 步｜先在本机看团队长什么样：启动 UI 后，在左侧 Explorer 点选demorig 加载实时拓扑：

拓扑图里每个 Pod（orch、dev、rev）内的座位都标注了运行器（Claude/Codex），点开 lead 座位的 CMUX 按钮可直接进入编排者终端：

第 2 步｜让 B 机对外暴露 HTTP：

OPENRIG_HOST=0.0.0.0 OPENRIG_AUTH_BEARER_TOKEN=<你的token> rig daemon start curl -fsS http://127.0.0.1:7433/healthz # 记下 selfHostId

第 3 步｜在 A 机注册 B 机（id 用第 2 步捕获到的值）：

rig host add --id <B的selfHostId> --transport http --url http://B:7433 --bearer-env B_TOKEN rig host doctor

第 4 步｜跨主机发送第一条消息：

rig send dev-main@my-rig "ping" --host <B的别名>

到这一步，你就在两台机器上拥有了一个统一寻址、身份可溯源、回复精确回家的 Agent 团队。

八、关键源码与文档路径

小结

OpenRig 的 cross-host 架构没有引入复杂的消息中间件，而是用本地 Daemon + 主机注册表 + 双传输通道三层薄结构，把多机问题还原成"通讯录 + 寻址 + 身份盖章"三个可独立验证的问题。对新手而言，记住三段式地址seat@rig@host和rig host命令族，就拿到了多机 Agent 团队的全部入口。🚀

【免费下载链接】openrigMulti-agent harness that runs Claude Code and Codex together as one system项目地址: https://gitcode.com/GitHub_Trending/op/openrig