为什么这篇值得先看
真正有用的排错，不是把所有命令都背下来，而是知道顺序。OpenClaw 第一次跑不通，常见根因会分布在安装、配置、Gateway、认证、设备配对、渠道、Browser 和 Skills 几层。如果你同时改 token、重启 Gateway、删除会话、重新扫码和改 allowlist，最后即使好了，也不知道是哪一步生效。
这篇适合已经完成安装和 onboard，但出现 “Dashboard 打不开”“Control UI unauthorized”“pairing 失败”“Telegram / WhatsApp 没回应”“doctor 一堆警告” 的用户。目标是让你先定位问题层级，再决定下一步，而不是一出错就重装。
先抓住这 3 个关键点
openclaw doctor和openclaw status适合做第一道只读筛查：配置是否可读、Gateway 是否可达、凭据和服务有没有明显异常。- 如果 Gateway 没有稳定起来，后面所有 Dashboard、Control UI、channels 和 pairing 现象都只是表象。
- 配对、allowlist、groupPolicy、scope mismatch 这类逻辑错误，通常不会靠重装解决；重装还可能破坏原本可恢复的 session 和凭据。
先把问题分到一层
| 现象 | 可能层级 | 第一条检查命令 |
|---|---|---|
openclaw 命令找不到 | 安装 / PATH | 重新打开 shell，检查 PATH |
| onboard 后无法启动 | 配置 / Gateway mode | openclaw doctor |
| Dashboard 页面打不开 | Gateway / 端口 / 隧道 | openclaw status |
| Control UI unauthorized | Gateway auth / token / password | openclaw dashboard --no-open |
| 1008 需要配对 | devices / scope | openclaw devices list |
| Telegram / WhatsApp 不回应 | channel / allowlist / session | openclaw status --deep |
| Browser 登录流失败 | 浏览器会话 / 扩展 / 登录态 | 先看 Browser 专题，再看 logs |
实操步骤
- 先执行只读检查：
openclaw doctor、openclaw status。如果你准备把输出贴给别人，先确认没有 token、cookie、账号标识或私密路径。 - 如果 Gateway 不可达，先不要调渠道。确认
gateway.mode、端口、auth、服务是否运行，以及本地入口127.0.0.1:18789是否符合你的环境。 - 如果 Dashboard / Control UI 打不开或 unauthorized，用
openclaw dashboard --no-open获取当前命令路径给出的安全 URL 和认证提示，再排查 token、password、SecretRef 或设备 token。 - 如果看到 1008、需要配对或 scope mismatch，先走 devices / pairing 路径，不要先轮换 Gateway token。
- Gateway 和界面稳定后，再排查渠道：Telegram 看 bot token、dmPolicy、allowlist 和群聊策略；WhatsApp 看登录态、session、selfChatMode 和发送者是否被允许。
- 如果问题进入 Browser、Skills、Cron 或插件层，先把基础 Gateway 健康状态截图或日志留好，再进入对应专题页继续排查。
配置或命令示例
openclaw doctor
openclaw doctor --fix
openclaw status
openclaw status --all
openclaw health --verbose
openclaw dashboard什么时候用修复命令
doctor --fix 适合处理官方已知的可修复状态，例如配置规范化、缺失插件恢复、服务定义提示和部分旧配置迁移。但它不是“把所有首次失败变好”的按钮。运行前建议做三件事：
- 先跑一次不带
--fix的openclaw doctor，读清楚它发现了什么。 - 备份关键配置和你要复盘的日志。官方 doctor 修复路径会写备份，但你仍然应该知道自己改过什么。
- 一次只修一层。先修配置，再看 Gateway；Gateway 稳定后，再修 pairing 或渠道。
在 Nix、受控服务器、团队共享环境或 SecretRef 管理 token 的环境里，更要先读官方限制。某些修复路径在不可变配置或无头环境里会被跳过，交互式提示也可能不会出现。
Gateway 不可达的排查顺序
- 先确认是没启动、端口不对、认证失败，还是网络路径不通。不要把所有 Gateway 问题都归因于模型 Key。
- 本地开发优先检查
openclaw gateway或openclaw gateway run是否能前台启动。端口冲突时再考虑--force，不要默认强杀。 - 看
openclaw status或openclaw health --verbose。前者适合本地摘要，后者适合向正在运行的 Gateway 请求健康快照。 - 如果是远程 Gateway，检查 SSH 隧道、Tailscale、TLS / WSS、allowed origins 和显式凭据。设置了
--url时，CLI 通常不会自动回退到本地配置或环境凭据。
Dashboard / Control UI 常见失败
- 页面加载失败：Gateway 未运行、端口不是 18789、basePath 不一致，或远程隧道没有建立。
- unauthorized：显式 token、password、设备 token 或 SecretRef 解析失败。先确认当前命令路径能拿到正确凭据。
- 1008 需要配对：新浏览器或新设备连接时，Gateway 可能要求一次性批准。用
openclaw devices list找 requestId，再审批。 - scope mismatch：设备被识别，但这次请求更高权限。应该明确审批新 scope，或撤销设备后重走配对，而不是盲目重置所有认证。
渠道问题不要提前排查
只有 Gateway 和 Control UI 基本健康后，才值得调 Telegram、WhatsApp、Browser 或 Webhook。否则你看到的“消息没回”“二维码过期”“Browser 卡住”可能只是 Gateway 没连上。
渠道层排查可以这样拆：
- Telegram：bot token 是否有效，sender 是否在 allowlist，群聊是否需要 @mention，Privacy Mode / 管理员权限是否符合预期。
- WhatsApp：session 是否还在，扫码是否完成，selfChatMode 是否符合场景，发送者和群聊规则是否匹配。
- Browser：登录态是否在目标浏览器配置文件里，验证码是否需要人工介入，任务是否依赖已有 session。
- Webhook / hooks：入口 URL、鉴权、重试、幂等和日志要单独看，不要和消息渠道混在一起排。
可共享的最小故障报告
当你需要让别人帮忙看问题，尽量只提供这些高信号信息：
- 你在第几步失败：install、onboard、doctor、gateway、dashboard、pairing、channel。
openclaw doctor或openclaw status --all的脱敏摘要。- 你看到的错误类型：unauthorized、1008、scope mismatch、端口占用、token drift、channel logged out。
- 你已经尝试过的一步修复，且每次只改了一项。
不要贴 API Key、Gateway token、cookie、完整聊天记录、联系人标识、Webhook body 或未脱敏日志。官方 Gateway health / diagnostics 文档也强调诊断输出应避免泄露消息文本和秘密值。
常见坑
- 同时改 token、channel、browser、plugin，最后不知道是哪一项真的修好了问题。
- 看见 pairing 失败就重装，结果把原本还能用的 session 一起清掉。
- 忽略 Control UI 里的 auth / devices / sessions，只看终端最后一行错误。
- 把模型 API Key 错误和 Gateway 不可达混为一谈，导致排错方向完全错位。
- 在服务仍有活跃工作时强制重启 Gateway，造成任务、队列或回复投递中断。
完成检查
- 你已经能按固定顺序排查，而不是边猜边改。
- doctor 不再报阻断性错误，Dashboard / Control UI 能给出清晰状态。
- Gateway 可达、认证方式明确，设备配对或 scope 请求没有未知项。
- 渠道问题已经和 Gateway / Dashboard 问题分开处理。
- 同类问题下次出现时，你知道先去哪一层找根因。
下一步怎么选
- 问题集中在设备或渠道配对：继续读 OpenClaw pairing 教程。
- 问题集中在 Gateway 暴露面、token 和审批：继续读 OpenClaw 安全加固。
- 已经发生 token 泄露、未知设备批准或越权访问：继续读 OpenClaw 安全事故演练。
为什么建议把这篇收藏起来
- 这篇是所有后续教程的“兜底页”，每次接新能力都可能回来看。
- 真正可复用的不是某个命令，而是这套排错路径：只读检查、分层定位、一次改一项、验证后再进入下一层。