OpenRig 跨主机部署完全指南：host registry、pair 配对与远程执行一步到位-开发者社区

OpenRig 跨主机部署完全指南：host registry、pair 配对与远程执行一步到位

【免费下载链接】openrigBuild your own network of agents from Claude Code, Codex and Pi: persistent teams with roles, shared context and owned work.项目地址: https://gitcode.com/GitHub_Trending/op/openrig

OpenRig 是一个把 Claude Code 和 Codex 协同运行成统一系统的多智能体（Multi-agent）编排工具。当你有多台机器——笔记本、家里的 Mac mini、云端 VPS——想让每个智能体坐在最合适的主机上工作时，OpenRig 的跨主机（cross-host）能力就派上用场了。本文将带你走通 OpenRig 跨主机部署的完整流程：注册主机（host registry）、一键配对（rig host pair）、选中主机、健康检查（rig host doctor），以及最终的远程执行（--host）。

为什么需要 OpenRig 跨主机部署？

在单台机器上跑多智能体已经够忙了，而现实中算力是分散的：编译在服务器、原型在笔记本、审查在云端。OpenRig 的设计是把每台主机当作一个"自命名节点"：

每个主机上运行一个 OpenRig daemon（守护进程），监听7433端口，并拥有唯一的selfHostId；
本地通过host registry（主机注册表，位于~/.openrig/hosts.yaml）记住所有远端主机；
支持两种传输方式：ssh（远程 shell 执行）和http（直接访问远端 daemon API）。

这样，一条rig send --host <id>就能把消息精准送达另一台机器上的智能体终端。

核心概念：host registry 主机注册表

主机注册表是跨主机协作的"通讯录"，核心实现在 packages/cli/src/host-registry.ts。它支持两种条目：

传输方式	必填字段	可选字段	适用场景
`ssh`	`target`（主机名/IP/SSH 别名）	`user`	能登录的机器，命令通过`ssh`中转执行
`http`	`url`（远端 daemon 地址，如`http://vps-a:7433`）	`bearer_env`或`bearer_file`（凭据指针，二选一）	网络直连的 daemon，CLI 直连远程 API

两个值得新手记住的安全设计：

凭据只存"指针"，不存值：注册表里记录的是"token 在哪个环境变量/文件里"，真正的密钥放在~/.openrig/secrets/下权限为0600的文件中；
保留 id 保护：local、kernel、host等 id 被系统保留，注册时会被拒绝，避免与本地主机身份混淆。

快速配对：`rig host pair`一键接入

如果手动维护 YAML 让你犹豫，OpenRig 提供了"创始人友好"（founder-simple）的配对路径——packages/cli/src/commands/host.ts 中的pair子命令。只需要粘贴一个地址：

rig host pair http://vps-a:7433

配对过程分三步：

发起请求：CLI 向目标主机的/api/hosts/pair-request发起请求，打印一个Pairing code（配对码），目标主机的注意力队列（attention queue）会收到一条审批项；
目标端批准：在目标主机上执行rig queue update <qitem-id> --state done --closure-reason no-follow-on完成批准（CLI 会直接提示完整命令）；
自动落盘：批准后，OpenRig 把签发的 bearer token 以独占创建方式写入~/.openrig/secrets/host-<id>.token，并向注册表追加一条 http 条目。

配对失败时（拒绝、过期、超时），OpenRig 保证什么都不落盘——不写注册表、不写 token 文件，错误信息会明确告诉你失败原因。相关行为可在 packages/cli/test/host-pair.test.ts 中查看完整契约。

手动注册与列表查看

进阶用户可以用rig host add完全控制注册条目（ssh 主机走这条路）：

rig host add --id vps-a --transport ssh --target vps-a --user openrig

注册后立即用列表命令确认：

rig host ls

输出是一张信息密集的表格：ID、HOST-ID（对端真实身份）、TRANSPORT、TARGET、STATUS（可达性探测：reachable/unreachable/unknown）、AUTH（凭据指针）。当前选中的主机前带*标记。

这里有个容易困惑的列：HOST-ID。你的id是"你给机器起的昵称"，而HOST-ID是那台机器自我声明的身份。OpenRig 会在rig host doctor时从对端/healthz接口"学习"这个身份并记录在侧车文件里（TOFU：首次接触信任）——之后所有跨主机消息的回复提示都能正确路由回来，即使两台机器上有同名的 rig 也不会串线。若对端改过身份，列表会用id-changed!大声告警，而不是静默出错。

选中主机：像 kubectl 一样切换上下文

rig host select <id>把一个持久化的"当前主机指针"写入配置（形如kubectl config use-context）：

rig host select vps-a # 之后的无参数跨主机命令默认指向 vps-a rig host select local # 切回本机

选中后，支持--host的命令在不传参数时会自动路由到该主机。切换当前主机名则用rig host rename "Mac mini 2"，让它在仪表盘和列表里显示更友好的名字。

健康检查：`rig host doctor`分步诊断

配对了不代表连通了。rig host doctor <id>会逐层诊断，每一步独立给出pass/fail/unknown三态结论和修复建议（实现在 packages/cli/src/commands/host.ts 的doctorLegs）：

transport-reachability：SSH 能否登录 / HTTP 的healthz是否可达；
remote-rig-binary：远端是否安装了rig（http 传输无法判断，会诚实标为 unknown）；
remote-daemon-health：远端 daemon 是否运行；
remote-identity：远端 daemon API 是否能返回有效身份数据。

对面向公网的 VPS，还可以加--posture product-factory-vps跑完整安全基线：非 root 用户、禁用密码登录、UFW 默认拒绝、Tailscale 最小信任、daemon 只绑定 loopback/tailnet、公网 22/7433 端口不可达等九项检查。官方多主机演练手册见 docker/testbed/runbooks/L5-multi-host-and-51-09.md。

远程执行：`--host`与`agent@rig@host`语法糖

一切就绪后，远程执行只需在常用命令上加--host：

rig send --host vps-a dev-impl@my-rig "开始处理这个任务" --verify

不同传输的执行方式不同（packages/cli/src/cross-host-executor.ts）：

ssh 主机：CLI 通过单跳ssh在远端执行sh -lc 'rig ...'，用登录 shell 保证远端 PATH 正确，并自动带上来源身份三件套，让远端正确记录"消息来自哪台主机"；
http 主机：CLI 携带 bearer token 直连远端 daemon API，无需登录远端 shell。

还有一个优雅的语法糖（packages/cli/src/cross-host-target.ts）：dev-impl@my-rig@vps-a中第三个@后的名字如果是已注册主机 id，就自动等价于--host vps-a。优先级规则为：显式--host> 目标语法糖 > 持久化选中；若--host与语法糖指向不同主机会直接报冲突错误，绝不静默猜测。

失败分类：错误信息本身就是排查手册

跨主机链路长，OpenRig 把每一类失败都拆成独立类别并附带修复提示，而不是笼统的 "failed"：

失败类别	含义	典型修复
`ssh-unreachable`	SSH 层就连不上	检查目标别名、网络连通性
`permission-gate`	密钥/认证被拒	检查 key、agent、authorized_keys
`remote-command-not-found`	远端 PATH 找不到`rig`	在远端重装 CLI（`npm install -g @openrig/cli`）
`remote-daemon-unreachable`	连上了但 daemon 没运行	在远端执行`rig daemon start`
`remote-command-failed`	远端命令本身报错	查看返回的 stderr 原文

常见问题（FAQ）

Q：注册表文件丢了或写坏了怎么办？rig host ls会明确报出 YAML 解析/校验错误及行号；add命令拒绝修改非法注册表，绝不用坏数据覆盖你的手工配置。

Q：token 文件不小心删了？重新执行rig host pair（或rig host add重新指向正确的bearer_file）即可。注意配对过程绝不会覆盖已存在的凭据文件。

Q：两台主机上有同名的 rig，消息会发错吗？不会。跨主机消息会盖上来源主机的身份三件套（member@rig@selfHostId），回复原路返回来源主机；这正是HOST-ID身份学习机制要保证的（L5 手册 LEG B 专门验证了这个场景）。

小结

OpenRig 跨主机部署的四步口诀：pair 配对 → ls 确认 → doctor 体检 → --host 执行。从粘贴一个 URL 到把任务远程下发给另一台机器上的智能体，全程不超过 10 条命令。主机注册表、身份学习、分步诊断和失败分类这四层设计，让多机协作既"新手能上手"，又"出问题能定位"——这正是 OpenRig 把 Claude Code 与 Codex 组成一个系统、再扩展到多台主机的核心价值。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

OpenRig 跨主机部署完全指南：host registry、pair 配对与远程执行一步到位