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

不要把“重装”当作第一步。先只读收集状态，确认故障属于哪一层，再执行最小、可回退的修复。

推荐诊断顺序

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

安装失败

命令不存在、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，Node 22/24/25 另有最低小版本要求。
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 或事件订阅错误。

浏览器工具

browser 命令不存在、Agent 看不到浏览器工具或现有登录态无法连接

症状： Agent 报告 browser tool unavailable，CLI 不识别 browser，或 user/chrome profile 无法附着。

可能原因：

• 当前 tools profile 没有允许 browser。
• plugins.allow 排除了 browser，且没有有效 root browser 配置。
• 选择了需要桌面确认的 user profile，或 Chrome 扩展/relay 未准备好。

先做安全检查：

• 浏览器登录态可能包含邮件、后台和支付权限；优先用隔离的 openclaw profile。
• 不要为排错直接开放 full tools profile；只补所需 browser 能力。
• 使用真实 Chrome 前确认谁在控制、哪些标签页可见以及如何立即停止。

只读与诊断命令：

openclaw status --all
openclaw browser status
openclaw plugins inspect browser --runtime --json
openclaw doctor

修复步骤：

1. 按官方文档为目标 agent 的 tools policy 最小化加入 browser。
2. 若配置了 plugins.allow，确认包含 browser；修改配置前备份并通过 schema 校验。
3. 隔离浏览器用 openclaw profile；需要真实登录态时再选 user/chrome，并完成相应桌面确认或扩展连接。

验证：

• openclaw browser status 显示目标 profile 可用。
• runtime inspect 能看到 browser 注册的工具。
• 只打开一个无敏感信息的测试页，确认读操作后再扩大权限。

Skills / 插件

Skill 不可用、插件装了但 runtime 没注册或出现重复所有权

症状： Skill 没进入 eligible 列表，插件在 list 中但工具/hooks 不工作，或诊断报告重复 channel/tool owner。

可能原因：

• Skill 的运行时依赖、路径、agent allowlist 或配置条件不满足。
• 插件安装后 Gateway 尚未重启，或 runtime payload 校验失败。
• 多个插件声明同一 channel/tool，或旧安装残留。

先做安全检查：

• 把第三方 Skill/插件当作不受信代码；安装前核对来源、内容、版本与权限。
• 不要用 --force 掩盖来源、权限或完整性错误。
• 禁用、更新或卸载前记录当前版本和配置，并准备回滚。

只读与诊断命令：

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

修复步骤：

1. 按 skills check 输出补齐依赖或 agent allowlist，不要复制未知修复脚本。
2. 插件安装/更新后重启 Gateway，再用 --runtime 证明真实注册。
3. 重复所有权时保留一个明确 owner，禁用或移除陈旧项；操作前先备份配置。

验证：

• 目标 Skill 出现在 eligible 列表。
• 插件 runtime inspect 能看到预期 tools/hooks/services。
• openclaw status --all 和 doctor 不再报告 configured-unavailable 或重复 owner。

更新 / 回滚

更新前不知道目标频道，或更新后 Gateway/插件出现不兼容

症状： 更新后服务不启动、插件被禁用、协议不匹配，或准备降级但不知道状态是否已迁移。

可能原因：

• 没有先核对安装类型、频道、目标版本和 Node 要求。
• 核心更新后插件同步或完整性校验失败。
• 回滚到旧版本时，新客户端、配置或状态迁移仍在生效。

先做安全检查：

• 更新前备份状态、配置、凭据引用和重要 workspace，并记录当前版本/安装方式。
• update status 与 update --dry-run 是只读入口；不要先用 --yes 跳过确认。
• 旧版本可能无法读取新状态；降级前必须阅读对应版本和迁移说明。

只读与诊断命令：

openclaw --version
openclaw update status --json
openclaw update --dry-run
openclaw gateway status --deep
openclaw plugins list --json

修复步骤：

1. 确认 dry-run 的频道、目标、重启和插件同步动作，再执行更新。
2. 更新后先跑 doctor 和 Gateway/插件检查，不要立即恢复高权限任务。
3. 确需回滚时，在完整备份后按官方 update 的版本/tag 机制执行并处理旧客户端；不要手动删除新状态。

验证：

• openclaw --version 与预期目标一致。
• Gateway deep status、doctor 和 plugin list 均无阻塞错误。
• 用只读任务验证模型、渠道和关键插件，再逐步恢复写入动作。

日志与 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 均给出一致结果。
• 脱敏诊断记录足以说明版本、时间、错误和验证结果。