Windows 配置 OpenClaw 避坑指南：从安装到运行全程详解

写给想在 Windows 上跑 OpenClaw 的朋友，涵盖两种安装方式的完整流程，以及我整理的踩坑点汇总。图文并茂，建议收藏。

目录

• 一、OpenClaw 是什么？
• 二、Windows 上两种安装方式
• 三、方式一：WSL2 安装（推荐）
• 四、方式二：原生 Windows
• 五、常见踩坑点汇总
• 六、故障排查命令速查
• 七、开机自启动配置
• 八、进阶：WSL2 服务暴露到局域网
• 九、总结

一、OpenClaw 是什么？

OpenClaw 是一个自托管的 AI 网关，把你的 AI 助手（支持 Discord、Telegram、WhatsApp、Signal、Slack 等几乎所有主流聊天平台）连接到你自己的本地设备或服务器上。

核心特点：

• 支持 20+ 聊天渠道
• 多端同步（手机、电脑都能连）
• 本地运行，数据不经过第三方
• 支持语音唤醒（macOS/iOS/Android）
• 开源，MIT 协议

官网： https://openclaw.ai
文档： https://docs.openclaw.ai

二、Windows 上两种安装方式

在 Windows 上安装 OpenClaw 有两条路：

官方建议：WSL2 是更稳定的路径，完整功能兼容。原生 Windows 虽然也能跑，但部分 CLI 流程仍有 caveat（见后文）。

三、方式一：WSL2 安装（推荐）

WSL2（Windows Subsystem for Linux 2）是微软出品的 Linux 子系统，在 Windows 里跑一个完整的 Linux 内核，性能接近原生 Linux。

3.1 前置条件

• Windows 10 21H2+ 或 Windows 11
• 需要开启 WSL2 和虚拟化

3.2 第一步：安装 WSL2 + Ubuntu

以管理员身份打开 PowerShell，执行：

wsl --install

如果需要指定发行版：

wsl --list --online        # 查看可用发行版
wsl --install -d Ubuntu-24.04   # 安装 Ubuntu 24.04

安装完成后重启电脑。

⚠️ 踩坑点 1：虚拟化未开启
如果 wsl --install 报错，先去 BIOS/UEFI 开启 CPU 虚拟化支持（Intel VT-x / AMD-V）。

3.3 第二步：启用 systemd（关键！）

这是 WSL2 安装 OpenClaw 的最常见坑。OpenClaw 的 Gateway 以 systemd 服务运行，必须开启 systemd。

打开 Ubuntu 终端，执行：

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF

然后关闭 WSL 再重开：

wsl --shutdown

在 Ubuntu 里验证：

systemctl --user status

如果输出类似 systemd running 或类似信息，说明成功了。

⚠️ 踩坑点 2：systemd 未启用导致 gateway install 失败
如果不启用 systemd，openclaw gateway install 会失败或无法自动启动。

3.4 第三步：安装 OpenClaw

在 Ubuntu 终端里执行官方安装脚本：

curl -fsSL https://openclaw.ai/install.sh | bash

脚本会自动：

• 检测你的系统
• 安装 Node.js（如需要）
• 安装 OpenClaw
• 启动引导向导

3.5 第四步：运行引导向导

openclaw onboard --install-daemon

向导会逐步要求你：

1. 选择模型提供商（OpenAI、Anthropic、Google、MiniMax 等）
2. 输入 API Key
3. 配置 Gateway 基本设置
4. 安装 Gateway 为系统服务

⚠️ 踩坑点 3：pnpm 安装后需要 approve-builds
如果你用 pnpm 安装，部分包有 build script，需要手动 approve：

pnpm add -g openclaw@latest
pnpm approve-builds -g      # 这一步不能漏！
openclaw onboard --install-daemon

3.6 第五步：验证运行状态

openclaw gateway status

正常输出应该显示：

✅ Gateway running
✅ RPC probe: ok

打开控制面板：

openclaw dashboard

浏览器会自动打开 http://localhost:18789，看到界面说明一切正常。

四、方式二：原生 Windows

原生 Windows 支持用 PowerShell 安装，适合不想装 WSL2 的用户。

4.1 安装

以普通用户身份打开 PowerShell（不需要管理员）：

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

4.2 引导向导

openclaw onboard --install-daemon

4.3 原生 Windows 的已知限制

官方文档明确指出以下功能在原生 Windows 下尚不完美：

⚠️ 踩坑点 4：schtasks 权限被拒
openclaw gateway install 在原生 Windows 上优先尝试创建 Windows Scheduled Task。如果权限不足，会回退到用户级 Startup 文件夹方式，但这种方式不能以系统服务运行。

4.4 跳过 health 检查完成引导

openclaw onboard --non-interactive --skip-health
openclaw gateway run

五、常见踩坑点汇总

踩坑点 1：Node 版本不对

问题： OpenClaw 要求 Node 24（推荐）或 Node 22.14+。

检查方法：

node --version

解决方案： 使用 nvm 或 fnm 管理 Node 版本：

# 安装 nvm（Linux/macOS/WSL2）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install 24
nvm use 24

# Windows 上用 nvm-windows
# https://github.com/coreybutler/nvm-windows

踩坑点 2：sharp 构建失败（npm 安装时）

问题： npm 全局安装时，sharp（图像处理库）因全局 libvips 版本冲突报错。

解决方案：

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

或者直接用 pnpm：

pnpm add -g openclaw@latest
pnpm approve-builds -g   # 手动批准 build scripts

踩坑点 3：WSL2 网络隔离（其他设备无法访问 Gateway）

问题： WSL2 有独立的虚拟网络，Windows 宿主机和 WSL 里的服务不互通。

解决方案： 用 netsh interface portproxy 做端口转发（见本文第八节）。

踩坑点 4：端口 18789 被占用

问题： openclaw gateway 启动时报端口冲突。

排查：

# Windows PowerShell 查看端口占用
netstat -ano | findstr :18789

# 或在 WSL2 里
ss -tlnp | grep 18789

解决： 找到占用的进程并停止，或配置 OpenClaw 使用其他端口：

openclaw gateway --port 18790

踩坑点 5：WSL2 安装后 systemctl 报 "command not found"

问题： WSL2 默认不启用 systemd，直接用 service 或 systemctl 会失败。

解决方案： 编辑 /etc/wsl.conf 启用 systemd（见本文 3.3 节）。

踩坑点 6：Anthropic API 报 429 错误（上下文过长）

问题： 使用 Anthropic 长上下文模型时报 HTTP 429: rate_limit_error: Extra usage is required for long context requests。

原因： 你的 API Key 没有开通 1M token 长上下文权限。

解决方案：

1. 在配置文件里关闭该模型的 context1m 选项
2. 或换一个已开通长上下文的 API Key
3. 或配置 fallback 模型

踩坑点 7：本地模型后端兼容性问题

问题： 本地模型后端（如 Ollama）在直接 curl 测试正常，但 OpenClaw agent 运行时报错。

常见报错： messages[...].content: invalid type: sequence, expected a string

解决方案： 在配置文件里添加兼容性选项：

{
  "models": {
    "providers": {
      "your-provider": {
        "models": [
          {
            "id": "your-model",
            "compat": {
              "requiresStringContent": true,
              "supportsTools": false
            }
          }
        ]
      }
    }
  }
}

踩坑点 8：DM 政策开放导致安全问题

问题： 配置不当时，任何人都可以向你的 bot 发消息并获得 AI 回复。

排查： 运行 openclaw doctor，它会审计 DM 策略并警告开放策略。

建议： 保持默认的 dmPolicy: "pairing" 设置，新用户需要你手动审批才能使用。

六、故障排查命令速查

遇到问题时，按这个顺序跑命令：

# 1. 查看 Gateway 状态
openclaw status

# 2. 查看 Gateway 详细状态
openclaw gateway status

# 3. 实时查看日志
openclaw logs --follow

# 4. 健康检查 + 自动修复
openclaw doctor --repair

# 5. 检查频道状态
openclaw channels status --probe

openclaw doctor 是一个非常强大的工具，可以：

• 自动修复配置文件
• 迁移旧版配置
• 检查服务状态
• 审计安全策略
• 清理过期锁文件

七、开机自启动配置

7.1 WSL2 里的 systemd 服务

openclaw gateway install

验证服务状态：

systemctl --user is-enabled openclaw-gateway.service
systemctl --user status openclaw-gateway.service --no-pager

7.2 WSL2 开机自启动（无用户登录场景）

对于需要开机就运行、即使没登录 Windows 也运行的场景：

第一步： 启用 linger：

loginctl enable-linger "$(whoami)"

第二步： 安装 Gateway 服务：

openclaw gateway install

第三步： 让 WSL2 在 Windows 启动时自动启动：

在 PowerShell（管理员） 里：

schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM

注意把 Ubuntu 换成你实际安装的发行版名称，可用 wsl --list --verbose 查看。

八、进阶：WSL2 服务暴露到局域网

WSL2 有独立的虚拟 IP，直接从宿主机或其他设备无法访问 WSL 里的服务。

8.1 端口转发（PowerShell 管理员）

以转发 WSL2 的 SSH 端口（2222 → 22）为例：

$Distro = "Ubuntu-24.04"
$ListenPort = 2222
$TargetPort = 22

$WslIp = (wsl -d $Distro -- hostname -I).Trim().Split(" ")[0]
if (-not $WslIp) { throw "WSL IP not found." }

netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPort `
  connectaddress=$WslIp connectport=$TargetPort

8.2 配置防火墙（一次性）

New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound `
  -Protocol TCP -LocalPort $ListenPort -Action Allow

8.3 WSL 重启后 IP 变了怎么办

创建 Windows 计划任务，在每次登录时自动刷新 portproxy：

# 删除旧规则
netsh interface portproxy delete v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 | Out-Null

# 重新添加
netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 `
  connectaddress=$WslIp connectport=$TargetPort | Out-Null

⚠️ 踩坑点 9：WSL2 重启后 IP 变化导致服务失联
建议把端口转发写成脚本，配合 Windows 计划任务在启动时自动执行。

九、总结

参考链接：

• 官方文档：https://docs.openclaw.ai
• GitHub：https://github.com/openclaw/openclaw
• Discord 社区：https://discord.gg/clawd
• 更新指南：https://docs.openclaw.ai/install/updating

本文基于 OpenClaw 文档和社区经验整理，如有疏漏欢迎指正。