OpenClaw Windows 安装故障排查手册：从报错到修复的索引

适用对象：在 Windows 上安装或启动 OpenClaw 时遇到报错的用户
覆盖环境：Windows 原生 PowerShell 与 Windows + WSL2 + Ubuntu
文档基线：本文以 2026-03-09 可访问的 OpenClaw 官方中文文档、FAQ、Gateway / Dashboard CLI 文档与 Microsoft 文档为准

这不是一篇“从零安装 OpenClaw”的教程，而是一份专门给报错时查用的索引手册。你可以把它理解成一本 Windows 场景下的排障地图：

• • 先用“现象速查表”定位问题类别
• • 再跳到对应章节
• • 按环境分别执行 PowerShell 或 WSL2 路径的修复步骤
• • 最后再回到 openclaw gateway status、openclaw health 和 Dashboard 做验收

如果你还没安装 OpenClaw，建议先看前两篇：

• • WSL2 主线路径：openclaw-windows-install-guide.md
• • 原生 Windows 路径：openclaw-native-windows-install-guide.md

一、先判断你是哪条 Windows 路径

Windows 上的 OpenClaw 问题，第一步不是看报错，而是先分环境。

路径 A：原生 Windows

符合这些特征，基本就是原生 Windows：

• • 你在 PowerShell 里直接运行 openclaw
• • 用的是 iwr -useb https://openclaw.ai/install.ps1 | iex
• • 后台服务依赖 Windows 计划任务，也就是 schtasks

路径 B：Windows + WSL2

符合这些特征，基本就是 WSL2：

• • 你先运行 wsl 或直接进入 Ubuntu
• • 安装命令在 Linux shell 中执行
• • Gateway 后台服务依赖 systemd --user

这两条路径有一部分报错是共通的，例如 token、模型认证、Dashboard 未授权；但也有一部分完全不同，例如：

• • 原生 Windows 更容易踩 PATH、git、计划任务上下文
• • WSL2 更容易踩 systemd、WSL 生命周期和 Linux 服务状态

二、排障前先跑这组“60 秒体检命令”

不要直接盯着浏览器错误页面猜原因。先跑一轮体检命令，把问题缩小到 CLI、服务、认证还是渠道层。

原生 Windows 体检命令

openclaw --version
node -v
git --version
openclaw status
openclaw status --all
openclaw gateway status
openclaw gateway probe
openclaw health

如果你怀疑是后台任务问题，再补一条：

Get-ScheduledTask | Where-Object { $_.TaskName -like'*OpenClaw*' } |
Select-Object TaskName, TaskPath, State

WSL2 体检命令

openclaw --version
node -v
openclaw status
openclaw status --all
openclaw gateway status
openclaw gateway probe
openclaw health
systemctl --user status

如果你怀疑是服务启动失败，再补：

journalctl --user -u openclaw-gateway.service -n 200 --no-pager

三、故障现象速查表

四、问题 1：openclaw 命令找不到或“不是内部/外部命令”

常见表现

原生 Windows 常见报错：

openclaw : 无法将“openclaw”项识别为 cmdlet、函数、脚本文件或可运行程序的名称

WSL2 常见表现：

openclaw: command not found

典型原因

• • 安装器已经执行，但当前终端会话没重开
• • PATH 没刷新
• • CLI 实际没有安装成功
• • 你在错误的环境里执行了命令

最后一种很常见：你明明把 OpenClaw 装在 WSL2 里，却在 Windows PowerShell 里找 openclaw。

修复步骤

where.exe openclaw
npm prefix -g
$env:Path

然后：

1. 1. 关闭当前 PowerShell
2. 2. 重新打开 PowerShell
3. 3. 再次执行 openclaw --version

如果还是没有，重新执行官方安装器：

iwr-useb https://openclaw.ai/install.ps1 | iex

which openclaw
npm prefix -g
echo$PATH

然后重新打开 WSL 终端，再试：

openclaw --version

修复后验收

openclaw --version

或：

openclaw --version

只要版本号能稳定打印，说明这个问题已经解决。

五、问题 2：spawn git ENOENT

常见表现

OpenClaw 官方 FAQ 明确提到，Windows 和 Linux 路径都可能遇到：

spawn git ENOENT

典型原因

• • 系统里根本没装 git
• • Git 已安装，但不在 PATH 中
• • 当前终端还在旧环境变量上下文里

修复步骤

先检查：

git --version
where.exe git

如果没有结果，直接安装 Git：

winget install --id Git.Git -e

安装后关闭并重开 PowerShell，再执行：

git --version
openclaw --version

git --version
which git

如果没装：

sudo apt update
sudo apt install -y git

修复后验收

重新运行之前失败的安装或构建命令。如果 git 已可见，spawn git ENOENT 这类问题通常就会消失。

六、问题 3：WSL2 里 systemd 没有启用

常见表现

典型报错：

System has not been booted with systemd as init system

或者 systemctl --user status 根本不可用。

典型原因

• • /etc/wsl.conf 没有启用 systemd=true
• • 修改了配置，但没有执行 wsl --shutdown
• • 你正在一个没有启用 systemd 的旧 WSL 实例里排查

修复步骤

在 WSL2 里执行：

printf'[boot]\nsystemd=true\n' | sudotee /etc/wsl.conf >/dev/null

回到 Windows PowerShell：

wsl --shutdown

然后重新进入 Ubuntu：

wsl -d Ubuntu

再验证：

systemctl --user status

修复后验收

如果 systemctl --user status 已能正常返回，说明 WSL2 的服务管理层已经恢复。

七、问题 4：Gateway 已安装，但服务没正常起来

常见表现

你执行：

openclaw gateway status

或：

openclaw gateway status

看到的是“已安装，但服务异常”“服务配置有问题”或者根本没有正确注册。

典型原因

• • Onboarding 没完整写入后台服务
• • 配置已变化，但旧服务没有重装
• • 原生 Windows 下计划任务创建失败
• • WSL2 下 systemd 用户服务未正确安装或启用

修复步骤

先用 OpenClaw 自己的命令重装服务，而不是先手工改底层服务：

openclaw gateway install --force
openclaw gateway status

或：

openclaw gateway install --force
openclaw gateway status

如果你想更完整地看当前问题，再跑：

openclaw status --all

或：

openclaw status --all

Get-ScheduledTask | Where-Object { $_.TaskName -like'*OpenClaw*' } |
Select-Object TaskName, TaskPath, State

journalctl --user -u openclaw-gateway.service -n 200 --no-pager

修复后验收

openclaw gateway status 不应再停留在“配置损坏”或“服务不存在”这类状态。

八、问题 5：服务看起来在跑，但 RPC 探测失败

常见表现

这类问题最容易误导人。你会看到：

• • 服务进程似乎存在
• • openclaw gateway status 里服务层看着没挂
• • 但 RPC 探测失败，或者 CLI 连不上 Gateway

典型原因

• • Gateway 监听起来了，但不是你当前 CLI 预期的实例
• • 认证 token 不匹配
• • 旧 Gateway 实例还占着端口
• • 服务配置和 CLI 当前配置不一致

修复步骤

先执行这组组合命令：

openclaw gateway status
openclaw gateway probe
openclaw logs --follow

或：

openclaw gateway status
openclaw gateway probe
openclaw logs --follow

如果你怀疑当前 CLI 连到的不是你想要的 Gateway，再做一次强制重装：

openclaw gateway install --force

或：

openclaw gateway install --force

修复后验收

openclaw gateway probe 应该成功，openclaw gateway status 里的服务层和 RPC 层都要一致。

九、问题 6：Dashboard 提示 unauthorized、1008 或 Disconnected from gateway

常见表现

官方故障排除文档和 FAQ 里，Dashboard 相关报错常见是：

• • unauthorized
• • 1008
• • Disconnected from gateway: no reason

典型原因

• • Dashboard 没带正确 token
• • 你手工打开了 http://127.0.0.1:18789/，但认证态没配好
• • 你当前浏览器打开的是一个旧 Gateway 地址
• • Gateway 实际未准备就绪，但页面先打开了

修复步骤

先按这个顺序来：

openclaw dashboard
openclaw gateway status
openclaw config get gateway.auth.token

或：

openclaw dashboard
openclaw gateway status
openclaw config get gateway.auth.token

如果没有 token，生成一个：

openclaw doctor --generate-gateway-token

或：

openclaw doctor --generate-gateway-token

然后重新通过 openclaw dashboard 打开页面，而不是只靠手工地址访问。

修复后验收

Dashboard 应能稳定进入，不再反复弹 unauthorized 或直接掉线。

十、问题 7：device identity required 或 connect failed

常见表现

你可能会在通过局域网地址、远程设备或非本机方式打开 Dashboard 时，看到：

device identity required

或者：

connect failed

典型原因

OpenClaw 官方故障排除文档明确提到，如果你通过不安全的 http:// 从外部设备访问 Dashboard，浏览器端的设备身份能力可能不可用，于是连接建立失败。

修复步骤

最简单、最稳的办法是：

1. 1. 先在本机打开 Dashboard
2. 2. 优先使用 CLI 生成的本地访问方式
3. 3. 如果必须远程访问，改走 OpenClaw 文档建议的安全访问方案，而不是直接裸露 HTTP

如果你的目标只是验证安装是否成功，不要把“远程访问 Dashboard”作为第一阶段验收条件。先让本机访问通，再处理远程访问。

修复后验收

先回归本机：

openclaw dashboard

或：

openclaw dashboard

确保本机路径可用后，再做远程访问。

十一、问题 8：No API key found 或 All models failed

常见表现

典型错误包括：

No API key found for provider anthropic

以及：

All models failed. Last error: ...

典型原因

• • Gateway 所在主机上没有完成模型提供商认证
• • 你只在当前交互终端里设置了环境变量，但后台服务读不到
• • 模型提供商设置在错误的机器或错误的 profile 上

这类问题在 Windows 上尤其容易混乱，因为你可能：

• • 在 Windows PowerShell 设置了 key，但实际 Gateway 跑在 WSL2
• • 在 WSL2 里做了认证，但你排查的是原生 Windows Gateway

修复步骤

先确认 Gateway 究竟跑在哪台环境里，然后在那台环境里重新做认证或配置。

排查顺序建议是：

openclaw gateway status
openclaw doctor

或：

openclaw gateway status
openclaw doctor

如果你刚改过模型提供商设置，建议再重启一次 Gateway：

openclaw gateway restart

或：

openclaw gateway restart

修复后验收

回到 Dashboard 或消息入口，发起一次最简单的模型请求，确认不是“服务活着但没有模型可用”的状态。

十二、问题 9：Gateway 能启动，但消息一直没有回应

常见表现

• • Dashboard 能打开
• • Gateway 似乎也启动了
• • 但输入消息后没有真正得到回复

典型原因

• • 模型认证没配好
• • 渠道认证未完成
• • 你看到的是前端可访问，不代表后端模型链路可用
• • 日志里已经有报错，但你只盯着浏览器页面

修复步骤

先看日志，而不是继续刷新页面：

openclaw logs --follow

或：

openclaw logs --follow

再配合：

openclaw health

或：

openclaw health

如果日志里已经显示是模型、渠道或认证错误，优先修那一层，而不是反复重装 CLI。

修复后验收

在 Dashboard 中发一条最简单的测试消息，例如“你好”，确认能正常得到响应。

十三、问题 10：关掉终端后，OpenClaw 是不是也停了

常见误解

很多人把“我关掉窗口了”误解成“Gateway 一定停了”，也有人反过来把“我跑过 --install-daemon”误解成“它肯定已经稳定后台化了”。

正确判断方式

OpenClaw 后台服务依赖任务计划程序。你要看的不是当前 PowerShell 窗口还在不在，而是：

openclaw gateway status
Get-ScheduledTask | Where-Object { $_.TaskName -like'*OpenClaw*' } |
Select-Object TaskName, State

你要看的不是 Linux shell 窗口，而是 systemd --user 服务状态：

openclaw gateway status
systemctl --user status

如果你只是想临时验证

不要一开始就死磕后台服务。先用前台方式确认 Gateway 本身没问题：

openclaw gateway run

或：

openclaw gateway run

前台模式正常，说明核心问题大概率在后台服务层，而不是 Gateway 本身。

十四、问题 11：端口占用、重复实例或无法绑定

常见表现

常见症状包括：

• • 你怀疑已经有别的 Gateway 在跑
• • 当前 Gateway 无法绑定预期地址
• • gateway probe 连到旧实例

典型原因

• • 上一次安装留下了旧 Gateway
• • 你切换过 profile 或服务配置
• • 新旧实例争用同一端口

修复步骤

OpenClaw 官方 Gateway 文档给出的思路是：别手工乱清，先让 CLI 接管并重装。

openclaw gateway install --force
openclaw gateway restart
openclaw gateway probe

或：

openclaw gateway install --force
openclaw gateway restart
openclaw gateway probe

如果你只是为了“当前机器先恢复可用”，这通常比你手工删一堆底层配置更稳。

修复后验收

openclaw gateway probe 应该连到你刚重装后的实例，而不是旧实例。

十五、问题 12：refusing to bind ... without auth

常见表现

典型错误类似：

refusing to bind ... without auth

典型原因

OpenClaw 官方 Gateway 故障排除文档明确提到，如果你尝试绑定到更开放的网络地址，但没有配置认证，Gateway 会拒绝这样做。

修复步骤

先退回安全、可控的本地验证路径：

1. 1. 先只在本机验证 Gateway
2. 2. 先用 Dashboard 或本地 CLI 跑通
3. 3. 再按文档补认证和远程访问方案

如果你当前只是为了确认安装是否成功，不要在第一阶段同时处理“开放绑定 + 鉴权 + 远程访问”三件事。

修复后验收

先确保本机路径成功：

openclaw gateway status
openclaw dashboard

或：

openclaw gateway status
openclaw dashboard

十六、如果你已经不知道该先看哪一层

这时不要继续猜。直接按下面这个顺序回到最小闭环：

1. 1. openclaw --version
2. 2. node -v
3. 3. git --version
4. 4. openclaw gateway status
5. 5. openclaw gateway probe
6. 6. openclaw health
7. 7. openclaw logs --follow
8. 8. openclaw dashboard

如果这 8 步里，前 3 步都过不了，那是基础环境问题。
如果前 3 步能过，但 gateway status 不行，那是服务层问题。
如果 gateway status 可以，但 probe 或 Dashboard 不行，那是连接或认证问题。
如果 Dashboard 能开但消息不回应，那是模型或渠道问题。

这个顺序非常适合排查 Windows 上最常见的“看起来哪都像有问题，其实只有一层真正坏了”的情况。

十七、结语

Windows 上排查 OpenClaw，最忌讳的不是报错多，而是把不同层的问题混在一起看。命令找不到、计划任务失败、systemd 未启用、Dashboard token 不对、模型 API key 缺失，这些都叫“装不上”或者“跑不起来”，但根本不是同一种问题。

你真正需要的是一套固定顺序：

• • 先分环境：原生 Windows 还是 WSL2
• • 再分层：CLI、服务、连接、认证、模型
• • 最后才进入具体修复动作

只要你按这个顺序排，Windows 上的 OpenClaw 问题大多数都能比较快地收敛。

参考资料

• • OpenClaw 入门指南（中文）：https://docs.openclaw.ai/zh-CN/start/getting-started
• • OpenClaw Windows 文档（中文）：https://docs.openclaw.ai/zh-CN/platform/windows
• • OpenClaw 安装文档（中文）：https://docs.openclaw.ai/zh-CN/install/index
• • OpenClaw 安装器内部机制（中文）：https://docs.openclaw.ai/zh-CN/install/installer
• • OpenClaw Gateway CLI 文档（中文）：https://docs.openclaw.ai/zh-CN/cli/gateway
• • OpenClaw Dashboard CLI 文档（中文）：https://docs.openclaw.ai/zh-CN/cli/dashboard
• • OpenClaw 故障排除文档（中文）：https://docs.openclaw.ai/zh-CN/help/troubleshooting
• • OpenClaw FAQ（中文）：https://docs.openclaw.ai/zh-CN/help/faq
• • Microsoft Learn WSL 安装指南：https://learn.microsoft.com/windows/wsl/install