OpenClaw 故障排查：先只读诊断，再做可回退修复

不要把“重装”当作第一步。先只读收集状态，确认故障属于哪一层，再执行最小、可回退的修复。新安装失败先对照安装中心，升级前先核对版本中心；如果错误涉及 systemd ownership、SERVICE_DEFINITION_SEALED 或多 Agent owner，可以直接参考2026.8.2 systemd 多 Agent 升级实录。

推荐诊断顺序

1. 记录版本、profile、配置路径和现象发生时间。
2. 检查整体状态与 Gateway 可达性。
3. 运行 doctor，但先不要带 —fix。
4. 只对有问题的模型、渠道、浏览器或扩展运行对应 probe。
5. 保存并脱敏日志，再执行最小修复。
6. 用同一条非敏感任务验证，确认问题没有转移到另一层。

OpenClaw 升级失败怎么恢复

2026.8.2 增强了 failed-update recovery、Session migration 失败处理和插件 finalization，但恢复原则仍然是：先保存现场，再判断更新停在哪一步。不要连续覆盖安装。

1. 先确认当前到底装到了哪个版本

openclaw --version
openclaw update status --json

如果 core package 已经变成新版本，不要再次执行一轮完整 update 来“碰碰运气”。后面的恢复动作取决于失败发生在 core install 之前，还是 plugin / doctor / migration finalization 阶段。

2. 先跑只读诊断

openclaw doctor
openclaw gateway status --deep

doctor 会暴露配置、服务、Session migration 等阻塞线索。官方当前没有要求用户靠一个虚构的 migration status 命令判断迁移；以 doctor、update 输出和 Gateway 状态中的实际错误为准。

3. 如果 Gateway 停着，不要直接强行覆盖 service definition

8.2 的 updater 会在安装包或 rollback 已验证安全时尝试恢复被停止的 Gateway；如果安全性或 service ownership 无法确认，它会保持保守状态并给出诊断。

先看：

openclaw gateway status --deep

只有你明确要替换 managed launcher 时，才考虑官方文档里的：

openclaw gateway install --force

不要把它当通用“修 Gateway”命令。

4. 检查插件 capability review 是否卡住了更新

2026.8.2 会在插件更新声明新的 capability、但 operator 尚未批准时阻止请求的 Gateway restart。此时旧的可用插件可以被保留，更新则以可操作的失败状态结束。

先查看 update 输出指出的插件，再检查 runtime：

openclaw plugins inspect <plugin-id> --runtime --json

--yes 不等于批准 capability。不要为了让 CI / 无人值守更新继续就绕过 review。

5. core 已更新、后处理没完成时使用 update repair

openclaw update repair

它适合的场景是：新 core package 已经安装，但 doctor repair、tracked plugin sync、managed npm plugin metadata、missing payload repair 或 plugin registry refresh 没有收敛。

openclaw update repair 会运行 doctor --fix 并重新完成这些 finalization；它不会再安装新的 core package，也不会自行重启 Gateway。

8.2 发布后的官方 update 文档又补充了几个容易误判的 repair 场景：

• bundled plugin 迁到 external package 时，如果 replacement payload 安装失败，repair 会保留底层错误；先解决这个错误，再重跑 openclaw update repair，不要把失败当成“旧插件已成功替换”。
• configured plugin 的 package files 或 runtime entry 缺失时，Doctor / repair 会重新安装缺失 payload；一个空目录不算成功安装。
• 如果 managed external package 本身健康，但源码 checkout 里存在一个同 ID 的损坏 bundled-discovery 副本，repair 以 recorded package root 为准，不会因为那个源码副本损坏就覆盖健康的 managed package；诊断也应该指向实际 recorded root。

有 capability 变化时优先在交互终端完成 review。只有已经人工审查过变更的自动化流程，才考虑：

openclaw update repair --accept-capabilities

6. repair 后再验证 Gateway 与关键能力

openclaw doctor
openclaw gateway status --deep
openclaw plugins list --enabled --verbose

然后用一条低风险任务验证模型、渠道、Session 和关键插件。共享 Gateway 在 9.2 后还要显式复核跨 Agent 权限：对应配置省略时，tools.sessions.visibility 默认到 all，tools.agentToAgent.enabled 默认开启；不要继续依赖 8.2 阶段的旧默认判断。

7. cleanup 不是恢复命令，放到全部验证之后

先预览：

openclaw update cleanup --dry-run

这个 dry-run 只读取 metadata，可以用来判断哪些 migration originals 可清理。真正 apply cleanup 时，目标 Gateway 需要停止，而且被删除 originals 对应的 rollback 能力会永久失去。当前 SQLite history 会保留，但这不能替代你自己的备份。

所以顺序必须是：先 dry-run → 确认备份 → 确认新版本和 migration 已稳定 → 最后才决定是否清理。

8. 回退放在最后，并先确认旧版本能否读取新状态

如果 repair 后仍无法恢复，再根据当前安装方式、Release Notes 和备份决定回退。不要手动删除新状态目录来“模拟回滚”，也不要在 migration 仍不明确时随意降级。

安装失败

命令不存在、Node 版本不支持或全局安装后找不到 CLI

症状： 终端提示 openclaw: command not found，或安装器/CLI 报告 Node.js 版本不在支持范围。

可能原因：

• Node.js 未安装，或版本低于官方当前支持范围。
• npm 全局目录没有进入当前 shell 的 PATH。
• 电脑上存在多个 Node/npm/OpenClaw 安装根，当前终端调用了另一套。

先做安全检查：

• 先只读取版本和路径，不要反复用管理员权限全局安装。
• 不要从第三方镜像复制安装脚本；回到 OpenClaw 官方安装页确认命令。
• 如果已有工作区和配置，重新安装前先备份并记录当前安装方式。

只读与诊断命令：

node -v
npm prefix -g
openclaw --version
openclaw doctor

修复步骤：

1. 按官方 Node.js 页面安装受支持版本：Node 26 是推荐运行时，但 Linux 官方 installer 在缺 Node 时当前默认 provision Node 24 LTS；只要满足最低版本和 SQLite 安全要求，不要把受支持的 Node 24 误判成“必须升级到 26 才能运行”。
2. 把 npm prefix -g 对应的可执行目录加入 PATH，然后重新打开终端。
3. 确认 shell 实际调用的 OpenClaw 来自预期安装根，再执行官方安装或 onboarding。

验证：

• openclaw --version 能返回版本。
• openclaw doctor 不再报告阻塞性安装或配置错误。
• openclaw gateway status 能识别预期 Gateway。

Gateway 启动 / 连接

Gateway 没启动、探测不可达或客户端连接到错误实例

症状： 状态显示 Runtime 未运行、gateway probe 不可达，或日志持续出现认证、端口、协议不匹配。

可能原因：

• 服务配置与当前 CLI 读取的配置文件或 profile 不一致。
• 升级/回滚后仍有旧客户端或旧 Gateway 进程连接。
• 端口、认证 scope、服务启动项或 Gateway 依赖发生错误。

先做安全检查：

• 先记录版本、profile、配置路径和当前服务状态。
• 不要直接删除状态目录或杀掉无法确认身份的进程。
• 重装服务前备份配置，并确认不会中断正在运行的真实任务。

只读与诊断命令：

openclaw status --all
openclaw gateway probe
openclaw gateway status --deep
openclaw logs --follow
openclaw doctor --deep

修复步骤：

1. 根据 gateway status --deep 的服务路径和已连接客户端定位错误实例。
2. 普通服务异常可先执行 openclaw gateway restart；这是会中断会话的操作，先保存任务状态。
3. 只有官方诊断明确指出服务注册损坏时，才在备份后考虑 openclaw gateway install --force。

验证：

• openclaw gateway probe 返回 Reachable。
• openclaw gateway status --deep --require-rpc 同时确认运行状态和 RPC 读取能力。
• 新日志不再重复同一认证、端口或 protocol mismatch 错误。

配置与环境变量

配置校验失败、变量缺失或服务读不到 shell 里的凭据

症状： Gateway 拒绝启动并提示 Invalid config，或同一凭据在交互终端可用、服务进程中不可用。

可能原因：

• 配置包含未知字段、错误类型或空的 ${VAR_NAME} 替换。
• 凭据只设置在当前 shell，没有进入 Gateway 服务环境。
• 修改了错误 profile、agent 或配置文件。

先做安全检查：

• 不要把 API Key 粘贴到截图、日志、Issue 或公开仓库。
• 修改前备份 openclaw config file 返回的真实配置文件。
• 优先运行校验和读取命令；doctor --fix 会修改配置，不能当成只读检查。

只读与诊断命令：

openclaw config file
openclaw config validate
openclaw config validate --json
openclaw doctor

修复步骤：

1. 按校验错误修正具体字段，不要用删除整份配置的方式绕过 schema。
2. 模型凭据优先放到 Gateway 主机的 ~/.openclaw/.env 或官方 SecretRef 支持路径。
3. 需要自动修复时先备份，再审阅 openclaw doctor --fix 提示；非交互 --yes 不适合作为首选。

验证：

• openclaw config validate 成功。
• openclaw status --all 显示预期 profile、模型与渠道。
• Gateway 重载后不再出现 config reload skipped 或缺失变量错误。

模型 / API

模型认证缺失、profile 过期、限流或默认模型解析错误

症状： 请求报 No credentials、expired、429/rate limit，或状态显示 no_model、excluded_by_auth_order。

可能原因：

• Gateway 主机没有对应 provider 的凭据，或凭据 profile 已过期。
• 默认模型、fallback 与 auth order 指向了不可用 profile。
• 上游提供商额度、限流或模型兼容性发生变化。

先做安全检查：

• 不要在命令历史、聊天或页面中打印完整 API Key。
• models status --probe 会访问上游服务，可能产生最小请求或费用；先用普通 status。
• 切换 fallback 前确认数据会发往哪个模型服务商。

只读与诊断命令：

openclaw models status
openclaw models status --check
openclaw models auth list --provider <provider>
openclaw config get agents.defaults.model --json

修复步骤：

1. 在 Gateway 主机按官方 provider 流程重新登录或配置 SecretRef/API Key。
2. 清理指向缺失 profile 的 auth order，或把默认模型改回已确认可用的条目。
3. 普通 status 无误后，才用限定 provider/profile 的 probe 验证真实连接。

验证：

• openclaw models status --check 返回可用状态。
• 限定范围的 models status --probe 不再返回认证或 no_model。
• 用非敏感短提示完成一次最小调用，并确认实际 provider 符合预期。

渠道（含飞书）

渠道显示已配置但消息收不到、发不出或飞书群里不响应

症状： 渠道状态只有配置摘要，probe 失败；飞书私聊或群聊无响应，或事件/权限检查失败。

可能原因：

• Gateway 不可达时，channels status 只能回退到配置摘要。
• 账号 token、应用权限、事件订阅或群策略不满足当前渠道要求。
• 飞书群默认需要 @机器人，或 groupPolicy 被禁用。

先做安全检查：

• 先检查单一测试账号/群，不要一次重绑全部生产渠道。
• 二维码、App Secret、token 和 webhook 地址不得进入公开日志。
• 重新登录渠道会修改授权；先确认账号、租户与管理员权限。

只读与诊断命令：

openclaw gateway status
openclaw channels status --probe
openclaw channels logs --channel feishu
openclaw logs --follow

修复步骤：

1. 先让 Gateway 可达，再按 probe/audit 输出修正具体渠道配置。
2. 飞书确认机器人已入群、消息中 @机器人、事件订阅含 im.message.receive_v1，并检查 groupPolicy。
3. 确需重建授权时运行 openclaw channels login --channel feishu；该向导会写入配置或安装插件，执行前先备份。

验证：

• channels status --probe 返回 live works/audit ok，而不只是配置摘要。
• 测试群中发送一条不含敏感信息的 @消息并收到响应。
• 渠道日志没有持续认证、scope 或事件订阅错误。

浏览器工具

Chrome Extension / relay 无法连接，或旧教程要求一直手工启动 relay

症状： Chrome Extension 显示 Waiting for local OpenClaw、native host 缺失、relay unavailable，或者旧教程要求先 Load unpacked / 手工启动 relay 才能使用。

2026.8.2 之后先理解两条路径：

• 普通 macOS / Linux 本地安装优先使用官方 Store extension + native host 自动 bootstrap。
• 支持 relay wake-up 的扩展构建，在 native host 已安装且 Automatic local setup 开启时，可以在 Gateway 未运行的情况下唤醒 paired standalone relay，供已认证 CDP client 使用。这不会启动 Gateway browser control，openclaw browser 动作仍需要 Gateway。
• Windows 当前仍以 manual pairing 为主。

先做安全检查：

• Chrome 登录态可能包含邮件、后台与支付权限；只给需要的 tab access。
• 完整 pairing string 按密码处理，不要贴到日志或 Issue。
• Load unpacked 现在是开发 fallback，不应作为普通用户首选安装方式。

只读与诊断命令：

openclaw browser extension status --json
openclaw browser doctor --browser-profile chrome
openclaw doctor

修复步骤：

1. macOS / Linux 正常安装时，先运行 openclaw browser extension install，等 native host 预注册完成，再添加官方 Chrome Web Store extension。
2. 如果扩展曾在 native host 安装前尝试自动连接，完整退出并重启 Chrome 一次，清除 Chromium 对“native host missing”的进程级缓存。
3. 本地常规 Browser control 仍需要 openclaw gateway run 或 managed Gateway service；不要把 standalone relay 能运行理解为 Gateway 已经可用。
4. Windows、恢复场景或明确的远程 Gateway 才使用 Settings 里的 advanced manual pairing。

验证：

• extension status --json 显示 owned native host 可用。
• browser doctor --browser-profile chrome 不再报告版本、pairing 或 relay 阻塞。
• 先只允许一个无敏感信息的 tab，完成一次读取测试，再扩大范围。

如果“relay / tab 看起来健康，但 snapshot、evaluate 或 navigate 仍超时”，再结合网页读取方案对比区分 Browser control、正文抓取与第三方读取链路，不要把所有网页失败都归因到同一个工具。

Skills / 插件

Skill 不可用、插件升级后 Gateway restart 被阻止或 SDK import 失效

症状： Skill 没进入 eligible 列表；插件在 list 中但 runtime 没注册；更新提示 capability review；或自研插件升级 8.2 后出现 import / load failure。

可能原因：

• Skill 的运行时依赖、路径、agent allowlist 或配置条件不满足。
• 插件新版本声明了更多 capability，更新等待 operator review。
• 插件仍使用已经移除的 SDK root / compat / extension surface。
• 插件使用仍 deprecated / removal-pending、但尚未实际删除的兼容 subpath；不要把旧的 9 月 1 日 target 或当前 10 月 1 日 review date 误写成“已经删掉”。

先做安全检查：

• 把第三方 Skill / 插件当作不受信代码；安装和升级都重新核对来源、diff 与权限。
• --yes 不批准 plugin capability；不要用非交互参数掩盖新的权限面。
• 禁用、更新或卸载前记录版本、安装来源和配置，准备回退。

只读与诊断命令：

openclaw skills list --eligible
openclaw skills check
openclaw plugins list --enabled --verbose
openclaw plugins inspect <plugin-id> --runtime --json
openclaw doctor

修复步骤：

1. Skill 按 skills check 补齐依赖或 allowlist。
2. 插件 capability 变化先人工 review；如果 core 已更新但 finalization 未完成，运行交互式 openclaw update repair。
3. 自研插件按 Plugin SDK migration guide 修改 removed / deprecated imports；那 5 个早先以 2026-09-01 为 target 的 compatibility subpaths，在 8.2 release registry 仍是 deprecated，官方已于 9 月 2 日把 post-release removal-pending 的 removeAfter 延到 2026-10-01。这个日期是 review / compatibility tracking，不等于已删除或会自动删除。没有完整 typed-public replacement 的 helper / type 不要改去依赖 private-local 实现。
4. 修复后再检查 runtime registration 与 Gateway 状态。

验证：

• 目标 Skill 出现在 eligible 列表。
• 插件 runtime inspect 能看到预期 tools / hooks / services。
• doctor 和 update finalization 不再报告 capability、payload、registry 或 import 阻塞。

安装或更新第三方扩展前，继续按Skill / Plugin 安装与验证指南核对来源、capability 和 SDK 兼容；涉及真实账号、shell、浏览器或外发权限时，再过一遍安全入口。

正常更新 / 回滚

更新前先确认频道、目标和回退条件

正常升级先使用只读预览：

openclaw --version
openclaw update status --json
openclaw update --dry-run

确认目标版本、channel、插件同步与 restart 计划后再执行 openclaw update。完成后运行 openclaw doctor 与 openclaw gateway status --deep。

如果 update 已经失败，不要回到这一节反复执行完整升级；直接按上面的OpenClaw 升级失败怎么恢复区分 core install、migration、plugin capability 与 finalization。

确需回滚时先确认旧版本对当前 state / config migration 的兼容性，并保留完整备份。cleanup 已经删除的 migration originals 不能靠降级命令恢复。

日志与 doctor

问题无法归类，或需要生成可复核但不泄密的诊断线索

症状： 错误间歇出现、只有“不可用”而没有明确原因，或需要区分配置、Gateway、渠道、插件与模型问题。

可能原因：

• 只看最终报错，没有按状态→Gateway→doctor→渠道→日志顺序缩小范围。
• 观察了错误 profile、过期日志或与当前服务不同的安装根。
• 诊断材料包含 token、cookie、消息正文或个人数据，无法安全共享。

先做安全检查：

• 共享前删除 token、密码、cookie、完整路径、用户标识和消息正文。
• 日志跟随会持续输出；复现结束后停止，避免无界收集。
• doctor --fix 和 security audit --fix 会修改状态；先运行不带 fix 的只读版本。

只读与诊断命令：

openclaw status --all
openclaw gateway status
openclaw doctor
openclaw channels status --probe
openclaw logs --follow
openclaw security audit

修复步骤：

1. 从第一条失败命令开始，只跳转到对应官方深度页面，不要同时修改多个子系统。
2. 保留时间、版本、profile、复现步骤和已脱敏错误码；不要复制整个状态目录。
3. 只有 doctor/security audit 明确列出修复范围且已备份时，才考虑对应 --fix。

验证：

• 原现象可以用最小步骤稳定复现或已消失。
• 状态、Gateway、doctor 和对应子系统 probe 均给出一致结果。
• 脱敏诊断记录足以说明版本、时间、错误和验证结果。