🦞 Windows 11 + WSL2 安装 OpenClaw 避坑指南

📌 适用环境

• 操作系统：Windows 11（64位）
• 子系统：WSL2 + Ubuntu 22.04
• OpenClaw 版本：2026.3.12（最新）
• Node.js 版本：22.x

---

一、前置准备：WSL2 环境配置

1.1 启用 WSL2 和虚拟化

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

# 启用 WSL 功能
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# 重启电脑
Restart-Computer

重启后，在 PowerShell 中设置 WSL2 为默认版本：

wsl --set-default-version 2

1.2 安装 Ubuntu 22.04

在 Microsoft Store 中搜索“Ubuntu 22.04”并安装，或使用命令行：

wsl --install -d Ubuntu-22.04

安装完成后，启动 Ubuntu 并设置用户名和密码。

1.3 关键步骤：启用 systemd 和 mirrored 网络模式 ⚠️

OpenClaw 网关依赖 systemd 用户服务，但 WSL2 默认未启用 systemd。必须配置 .wslconfig 文件。

在 Windows 用户目录（C:\Users\你的用户名）下创建文件 .wslconfig，内容如下：

[experimental]
networkingMode=mirrored
dnsTunneling=true
firewall=true
autoProxy=true

然后在 PowerShell 中执行 wsl --shutdown，重新打开 Ubuntu 终端。

验证 systemd 是否生效：

ps -p 1 -o comm=

预期输出：systemd（如果是 init，则配置未生效，请检查文件路径和重启步骤）

💡 经验谈：这一步是所有网络问题和网关启动失败的总根源。很多教程忽略了它，导致用户反复折腾端口转发、防火墙，其实根本原因就在这里。

1.4 更新软件源并安装基础工具

在 WSL 终端中执行：

sudo apt update && sudo apt upgrade -y
sudo apt install curl git -y

---

二、安装 Node.js 和 OpenClaw

2.1 安装 Node.js 22（官方推荐）

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node --version   # 应显示 v22.x.x

2.2 安装 OpenClaw

使用 npm 全局安装（推荐）：

npm install -g openclaw@latest

或者使用官方一键安装脚本：

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

验证安装：

openclaw --version   # 应显示 2026.3.12 或更高

---

三、配置 OpenClaw

3.1 选择模型提供商（关键一步）

OpenClaw 需要连接 AI 模型。根据你的经验，某些第三方代理可能触发编码错误，建议优先选择官方兼容性好的免费提供商。

3.2 运行配置向导

在 WSL 终端中执行：

openclaw onboard --install-daemon

向导会询问一系列问题：

• Gateway mode：选择 Local（本地运行）
• Auth provider：选择 OpenAI (API key)（因为 DeepSeek 兼容 OpenAI）
• Default model：暂时选一个占位符（后面我们会手动修改）
• Channels：根据需要选择（如 Telegram、WhatsApp），可跳过
• Daemon installation：选 y 安装后台服务

向导结束后，会自动生成配置文件 ~/.openclaw/openclaw.json，并启动网关。

3.3 手动修改配置文件（避开模型兼容性坑） ⚠️

由于向导可能未完全适配 DeepSeek，我们需要手动编辑配置文件。

nano ~/.openclaw/openclaw.json

将文件内容替换为以下模板（记得填入你的 DeepSeek API Key）：

{
  "meta": { "lastTouchedVersion": "2026.3.12" },
  "models": {
    "providers": {
      "deepseek": {
        "baseUrl": "https://api.deepseek.com/v1",
        "apiKey": "这里填入你的真实 DeepSeek API Key",
        "api": "openai-completions",
        "models": []      // 必须有这个字段，即使为空
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "deepseek/deepseek-chat"
      },
      "workspace": "/home/你的用户名/.openclaw/workspace"
    }
  },
  "gateway": {
    "port": 18789,
    "bind": "lan",
    "auth": {
      "mode": "token",
      "token": "1234"     // 可自定义简单 token
    },
    "controlUi": {
      "allowedOrigins": [
        "http://localhost:18789",
        "http://127.0.0.1:18789"
      ]
    }
  }
}

保存（Ctrl+O → 回车 → Ctrl+X）。

💡 经验谈：models: [] 是必需的，否则网关启动会报错 expected array。另外，bind: "lan" 配合 .wslconfig 的 mirrored 模式，可以让 Windows 浏览器直接通过 localhost 访问，无需额外端口转发。

3.4 重启网关

openclaw gateway restart
openclaw gateway status   # 确认显示 running 和 RPC probe: ok

---

四、访问控制台

在 Windows 浏览器中打开以下地址（使用 127.0.0.1 而不是 localhost，避免解析问题）：

http://127.0.0.1:18789/#token=1234

如果页面正常加载，恭喜你，OpenClaw 核心服务已就绪！

---

五、测试 CLI 命令

在 WSL 终端中发送一条消息：

openclaw agent --message "你好，OpenClaw！" --agent main

如果 DeepSeek 返回正常回答，说明一切完美。

---

六、常见问题及解决方案（来自实战）

现象	可能原因	解决方法
浏览器访问 http://127.0.0.1:18789 拒绝连接	WSL2 未启用 systemd 或 mirrored 模式	检查 .wslconfig 配置，执行 wsl --shutdown 重启
openclaw gateway status 显示 stopped，不断重启	端口被占用	sudo lsof -i :18789 找到进程并 kill，再重启
CLI 调用时报 Cannot convert argument to a ByteString...	模型提供商不兼容（如返回含特殊字符）	更换为 DeepSeek 等兼容性好的提供商，并确保配置正确
Web UI 提示 unauthorized: gateway token mismatch	浏览器缓存了旧 token	使用无痕模式访问，或清除站点数据
openclaw doctor 提示 systemd 问题	WSL2 未正确启用 systemd	按本文 1.3 节重新配置

---

🎯 参考

原文链接：https://blog.csdn.net/liwang0113/article/details/157579187