企业官网建设流程全解析

如何快速诊断 OpenRig 故障：rig doctor 机器变更后排查完整指南

【免费下载链接】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是一个多智能体运行框架（multi-agent harness），让 Claude Code 和 Codex 在同一套系统中协同工作：用 YAML 定义智能体团队，一条命令启动整个 rig。当你的电脑换了系统、换了端口、升级了 Node 或恢复了备份后，OpenRig 可能突然"不听话"。这时只需运行rig doctor健康诊断命令，它会在几秒内逐项体检，告诉你哪里坏了、为什么重要、以及该怎么修。

什么时候该运行 rig doctor

rig doctor是官方为"装机体检"设计的命令，源码位于 doctor.ts。以下场景建议立即运行：

官方 README 也明确建议：Userig doctorwhen something stops working or after machine changes——这正是它的本职。

rig doctor 一键体检：命令用法

直接运行，零参数即可开始：

rig doctor

输出格式非常友好——每项检查都带状态图标、结论，失败项还会附赠Why（为什么重要）和Fix（怎么修）：

[OK] daemon_dist: Daemon dist found at ... [OK] node_version: Node v22.x [OK] tmux: tmux 3.5a [WARN] cmux_shell: cmux installed, but control unavailable right now. Why: OpenRig can run without cmux... Fix: Open the cmux app, verify control access... [FAIL] port: Port 127.0.0.1:7433 is in use by another process. Why: The daemon needs this port to serve the API and UI. Fix: Stop the process using port 7433, or start the daemon on a different port with: rig daemon start --port <port> Some checks failed.

两个进阶选项值得记住：

• rig doctor --json：输出 JSON，适合给 AI 助手或脚本消费。注意它只在真正的fail时返回非零退出码，warn不会让你"挂掉"。
• rig doctor --spec <path/to/rig.yaml>：把规格文件和正在运行的同名 rig做拓扑对比。这个检查在没传--spec时会诚实地标记为SKIP（"没找到检查对象"不等于"没问题"），避免假阴性。对应测试见 doctor-spec-conformance.test.ts。

8 项检查清单：每一项在查什么

rig doctor完整覆盖以下检查项（源码见 doctor.ts）：

关键设计：cmux 的问题永远只是 WARN。OpenRig 没有 cmux 也能正常跑，只是 Open CMUX 工作流不可用——不要因为黄色警告就重装。

机器变更后最常见的 4 个故障与修复

1️⃣ 端口被占用（portFAIL）

换机或重启后最容易遇到。daemon 需要 7433 端口提供 API 和 UI。若端口被别的进程占着，就停掉它，或换端口启动：rig daemon start --port <port>。如果占用的正是 OpenRig daemon 自己，这项会直接通过——命令会先探测/healthz确认身份，不会误报。

2️⃣ tmux 缺失或控制 socket 不健康

OpenRig 依赖 tmux 管理每个智能体的终端会话。机器恢复后常见的表现是"tmux 装了但 socket 坏了"，此时建议先保存可见 pane 里的状态，再重启默认 tmux 服务器（细节见 tmux-health.ts）。macOS 用户额外注意鼠标模式警告：运行tmux set -g mouse on临时开启，写入~/.tmux.conf即可永久生效。

3️⃣ Node 版本不支持

OpenRig 只认 Node 22 或 24。版本分类逻辑与rig preflight共享同一策略（见 node-support.ts），换机后若顺手升到了 26 或降回 20，这项会直接 FAIL 并给出修复建议。

4️⃣ 状态目录不可写（writable_homeFAIL）

新系统、新用户的家目录权限变了，daemon 无法写入~/.openrig数据库。检查目录存在且当前用户可写即可；这是"机器变更后"最隐蔽的故障之一。

修复后如何验证：从体检回到正常工作流

rig doctor管的是主机级安装健康。修完之后，按这条链路确认一切回归正常：

1. 再跑一次rig doctor，确认只剩 SKIP/WARN；
2. rig requirements <spec>：检查某个 rig 规格特有的依赖——doctor 管"这台机器"，requirements 管"这个 rig"，两者配合使用（用法说明见 cli-reference.md）；
3. rig ps --nodes --rig <rig-name>：确认每个 seat 的运行时、模型和就绪状态；
4. rig tui --shared或rig ui：回到可视化拓扑界面，直观看到 pod 和 seat 都在正常运行。

仍然卡住？去哪里找官方帮助

• 📖 docs/reference/help.md：官方排障手册，开头就是rig --version+rig doctor --json的组合拳，并按"安装问题 / 团队没启动 / 权限与权限提示 / 座席状态异常"分类给出下一步。已安装的用户可直接运行rig context get help查看同版本内容；
• 🚀 docs/reference/getting-started.md：其中的"Incomplete setup and restart"症状表，教你把观察到的现象先匹配到类别再动手，避免盲目重启；
• 🔍 demo/rig.yaml：仓库自带的示例 rig 规格，练手--spec检查时可以直接拿它当输入。

💡 记住诊断的黄金顺序：rig doctor先看机器 →rig requirements再看规格 →rig ps最后看运行态。三层分开，故障定位就变成了一道简单的排除法。

【免费下载链接】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