如何快速诊断 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/openrigOpenRig是一个多智能体运行框架multi-agent harness让 Claude Code 和 Codex 在同一套系统中协同工作用 YAML 定义智能体团队一条命令启动整个 rig。当你的电脑换了系统、换了端口、升级了 Node 或恢复了备份后OpenRig 可能突然不听话。这时只需运行rig doctor健康诊断命令它会在几秒内逐项体检告诉你哪里坏了、为什么重要、以及该怎么修。什么时候该运行 rig doctorrig doctor是官方为装机体检设计的命令源码位于 doctor.ts。以下场景建议立即运行场景典型症状 更换/重装系统、机器迁移daemon 起不来、所有rig命令连不上后端 重新npm install -g openrig/cli后提示缺少 dist 产物或 UI 资源 端口被占用或配置变更默认端口 7433 被其他进程抢走 Node 版本升级/降级不支持 Node 22 以外的老版本升错版本会直接 fail tmux 重装或配置重置智能体终端无法创建、无法附着 手工改过 rig 规格文件运行中的 rig 与 spec 描述不再一致官方 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检查项检查内容失败时状态daemon_distdaemon 编译产物dist/index.js是否存在❌ FAILui_dist预构建的 Web 仪表盘资源是否存在❌ FAILnode_versionNode 是否为 22 或 24未测试版本会提示❌ FAIL / ⚠️ WARNtmuxtmux 是否安装、控制 socket 是否健康❌ FAILtmux_mouse仅 macOStmux 鼠标模式是否开启影响滚轮和选中文本⚠️ WARNcmux_shell可选的 cmux 外壳控制是否可用⚠️ WARNwritable_homeOpenRig 状态目录默认~/.openrig是否可写❌ FAILportdaemon 端口默认 127.0.0.1:7433是否空闲或被自己的 daemon 占用❌ FAILcmux_daemondaemon 侧的 cmux 控制是否可用shell 侧通过后才检查⚠️ WARNspec_live_conformance--spec提供的规格与运行中 rig 拓扑是否一致⚠️ WARN关键设计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管的是主机级安装健康。修完之后按这条链路确认一切回归正常再跑一次rig doctor确认只剩 SKIP/WARNrig requirements spec检查某个 rig 规格特有的依赖——doctor 管这台机器requirements 管这个 rig两者配合使用用法说明见 cli-reference.mdrig ps --nodes --rig rig-name确认每个 seat 的运行时、模型和就绪状态rig tui --shared或rig ui回到可视化拓扑界面直观看到 pod 和 seat 都在正常运行。仍然卡住去哪里找官方帮助 docs/reference/help.md官方排障手册开头就是rig --versionrig 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考