Troubleshooting
先判断你卡在哪一层，再决定该修哪里。
这页不打算做成海量报错百科，而是先覆盖最容易把 OpenClaw 用户卡住的几类问题：dashboard、gateway、doctor、Windows/WSL2 路径，以及 Bun 这类偏离官方稳路径的运行时选择。
快速提示
先分清你卡在运行时、gateway、auth、provider 还是外部服务层。
先用 `openclaw gateway status` 和 `openclaw doctor` 确认最上游状态，再去翻更深的日志。
如果你已经偏离官方推荐路径，先回到更稳的 Node + 官方 shell 环境。
你将获得
内容风格
少废话，先给结果
先告诉你该做什么、会遇到什么，再给出最短可用路径。
阅读体验
能看懂，也能照着做
重点信息会被拆成清单、步骤和提示，减少第一次上手的理解成本。
页面重点
先把关键问题讲清楚
How to use this page
排错时，先修最上游问题，不要一次改一整片配置。
很多看起来复杂的问题，最后都能归到少数几层：运行时、gateway、认证、provider、外部服务。先分层，后动手。
Common failure zones
下面这几类问题，最值得先看。
它们不是最全的报错库，而是最容易把第一次上手和后续回访都卡住的核心阻塞点。
Priority issue
Dashboard 打不开或没弹出来
先确认你是否真的完成了 onboarding 的最短链路，再区分是浏览器没打开、gateway 没起来，还是认证信息不对。
先看什么
先重新执行 `openclaw dashboard`，确认是不是同一台机器上的同一套配置。
优先排查
gateway 是否在线、dashboard URL 是否正确、是否需要 token。
别先做什么
不要一上来就重装一整套环境，先把 URL、gateway 状态和 auth 链路说清楚。
推荐下一步
先跑 `openclaw gateway status`，再决定是修服务、修 URL，还是修认证。
Priority issue
Doctor 报错，看不懂该先修什么
Doctor 的价值不是把一切都修好，而是帮你先分清楚“阻断项”和“可稍后处理项”。先修阻断项，再继续。
先看什么
先区分是不是运行时、gateway、provider、外部服务四类问题之一。
优先排查
是否存在阻断项、是否要补 token / provider、是否需要 `--verify-external-services`。
别先做什么
不要看到 warning 就立刻扩大权限或乱改配置。
推荐下一步
先跑 `openclaw doctor`，必要时再跑 `openclaw doctor --verify-external-services`。
Priority issue
gateway status 显示异常，或者回复迟迟不到
很多看起来像“模型坏了”或“消息没回来”的问题，根上其实是 gateway 运行态、端口占用或服务配置不一致。
先看什么
先看 `Runtime`、`RPC probe`、端口和最近错误，而不是先怀疑模型。
优先排查
是否已有别的 gateway 占端口、服务和 CLI 配置是否不一致、是否需要 restart。
别先做什么
不要同时改端口、bind、token 和 provider，先找最上游的根因。
推荐下一步
优先用 `openclaw gateway status`、`openclaw gateway restart` 做最短验证。
Priority issue
Windows 路径、终端或 WSL2 让安装过程变得混乱
Windows 真正常见的问题不是命令不会敲，而是终端环境没统一，导致路径、权限和 service 判断不断串线。
先看什么
先确认你走的是 WSL2、Git Bash，还是默认终端；三者不要混着排错。
优先排查
Node 版本、当前 shell、daemon 装在谁的环境里。
别先做什么
不要今天用 PowerShell、明天用 Git Bash、后天再去 WSL2 里看状态。
推荐下一步
优先回到 WSL2；如果暂时不用 WSL2，也至少固定在 Git Bash 里完成首轮起步。
Priority issue
你用了 Bun 或实验路径，结果 Telegram / WA / gateway 表现不稳
这类问题很多不是项目本体坏了，而是你一开始就站在官方不推荐的运行时路径上。
先看什么
先确认当前 gateway 到底跑在 Node 还是 Bun 上。
优先排查
是否涉及 Telegram / WhatsApp、是否处于生产环境、是否混用了多套运行时。
别先做什么
不要在不稳定运行时上继续叠频道、插件和自动化链路。
推荐下一步
回到官方更稳的 Node 路径，再重跑 doctor 与 gateway 检查。
Official sources
这页优先只采信 OpenClaw 官方 FAQ、Doctor 与 Gateway 排障文档。
排错页最怕写成经验拼盘。因此这一版先以官方文档能互相印证的内容为准，把真正高频、最容易造成误判的问题先讲清楚。
官方文档 · FAQ
用于核对 dashboard、gateway、doctor、Bun 与远程模式等高频问题的官方说明。
https://docs.openclaw.ai/faq
官方文档 · Doctor & Health Check
用于核对健康检查、外部服务验证与常见阻断项的处理顺序。
https://docs.openclaw.ai/zh-CN/config/doctor-and-health-check
官方文档 · Gateway Troubleshooting
用于核对 gateway 端口、运行状态、auth 与远程连通性的排障说明。
https://docs.openclaw.ai/gateway/troubleshooting
官方文档 · Windows / WSL2 平台说明
用于核对 Windows 优先 WSL2 的平台建议，以及服务运行位置判断。
https://docs.openclaw.ai/platforms/windows