🪟 Windows 系统部署 OpenClaw 完整指南

最后更新： 2026-03-11
版本： v2.0（含 9 个踩坑解决方案）

📋 目录

1. 前置环境
2. 部署总览
3. 第一阶段：安装 WSL
4. 第二阶段：配置 Linux 环境
5. 第三阶段：安装 OpenClaw
6. 第四阶段：核心参数配置
7. 第五阶段：点火启动
8. 验证安装
9. 下一步：飞书机器人对接
10. 常见问题 FAQ
11. 附录：完整命令清单

前置环境

系统要求：

• Windows 11 64 位（恢复出厂设置的干净系统）
• 管理员权限
• 稳定的网络连接

最终目标：

• 在本地 Linux 环境中稳定运行 OpenClaw
• 对接阿里百川 Coding 计划大模型
• 为后续对接飞书机器人铺平道路

部署总览

┌─────────────────────────────────────────────────────────┐
│  📍 OpenClaw Windows WSL 部署流程（5 阶段）              │
├─────────────────────────────────────────────────────────┤
│  阶段 1: 安装 WSL           →  Ubuntu 22.04.5 LTS      │
│  阶段 2: 配置 Linux 环境     →  Node.js v22 + Git      │
│  阶段 3: 安装 OpenClaw      →  官方一键脚本            │
│  阶段 4: 核心参数配置       →  API Key + Gateway Token │
│  阶段 5: 点火启动           →  openclaw start         │
└─────────────────────────────────────────────────────────┘

预计时间： 15-30 分钟
难度： ⭐⭐☆☆☆（按步骤操作即可）

第一阶段：安装 WSL

方式 1：命令行一键安装

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

wsl --install

方式 2：微软商店安装（推荐）⭐

1. 打开 Microsoft Store（微软商店）
2. 搜索 "Ubuntu 22.04.5 LTS"
3. 点击 "获取" 或 "安装"
4. 等待下载完成
5. 点击 "打开"，等待系统解压初始化

初始化系统

Installing, this may take a few minutes...
Please create a default UNIX user account. The username does not need to match your Windows username.
For more information visit: https://aka.ms/wslusers

Enter new UNIX username: yuchen
New password: ********
Retype new password: ********

注意：

• 用户名必须是纯英文
• 密码输入时屏幕无显示（正常现象）
• 按回车确认

⚠️ 踩坑 1：VPN 导致安装超时

现象：

ErrorCode: Wsl/WIN_INET_E_TIMEOUT

或进度条卡在 1.5% 不动。

原因： VPN（梯子）干扰了命令行连接微软服务器的路由。

解决方案：

1. 按 Ctrl + C 强制中断下载
2. 关闭 VPN
3. 改用微软商店安装（方式 2）

⚠️ 踩坑 2：WSL 2 内核更新失败

现象：

Wsl/WSL_E_WSL2_INSTALL_REQUIRED

解决方案：

1. 手动下载 WSL2 内核安装包： https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi
2. 运行安装包
3. 重新执行 wsl --install

第二阶段：配置 Linux 环境

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

sudo apt update
sudo apt install curl git -y

安装指定版本的 Node.js (v22)

# 下载 NodeSource 源
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# 执行安装
sudo apt install -y nodejs

# 验证安装
node --version  # 应显示 v22.x.x
npm --version   # 应显示 10.x.x

⚠️ 踩坑 3：Node.js 版本过低

现象： 通过 sudo apt install nodejs 安装的版本是 v12 或 v14，导致 OpenClaw 无法运行。

原因： Ubuntu 默认软件源的 Node.js 版本太老。

解决方案： 必须使用 NodeSource 源安装 v22：

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

第三阶段：安装 OpenClaw

运行官方一键安装脚本

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

安装脚本会自动：

• 检测 Linux 环境
• 检查 Node.js 和 Git 版本
• 安装 OpenClaw 最新版本
• 进入配置向导

⚠️ 踩坑 4：npm 安装超时

现象： 运行安装脚本后，界面一直卡在 Installing OpenClaw 毫无动静。

原因： npm 默认连接海外服务器，国内直连极易丢包或挂起。

解决方案：

1. 按 Ctrl + C 强行中断
2. 切换 npm 为国内淘宝镜像源：

   npm config set registry https://registry.npmmirror.com
   

3. 清理缓存：

   npm cache clean --force
   

4. 重新运行安装脚本：

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

⚠️ 踩坑 5：权限不足错误

现象：

Error: EACCES: permission denied

解决方案：

1. 在用户目录下安装（不需要 sudo）
2. 或使用 sudo 安装：

   sudo npm install -g openclaw
   

第四阶段：核心参数配置

启动配置向导

# 如果输入 openclaw 提示找不到命令
source ~/.bashrc

# 启动配置向导
openclaw configure

大模型配置（Model/Auth Provider）

1. 选择 Custom Provider
2. 填写配置：
   • API Base URL: https://coding.dashscope.aliyuncs.com/v1
   • API Key: 填入阿里百川 Coding 计划长串密钥
   • Model ID: qwen3-coder-next 或 qwen3.5-plus
3. 看到 Verification successful 即代表连通成功

网关配置（Gateway）

1. Gateway port: 保持默认 18789
2. Gateway bind mode: 选择 LAN (All interfaces) ⭐（关键：允许外部设备访问）
3. Gateway auth: 选择 Token
4. ⚠️ 极度重要： 屏幕上生成的一长串 Token 必须复制并保存下来！
   • 这是后续飞书机器人等外部应用连接 OpenClaw 的唯一"钥匙"
5. Tailscale exposure: 选择 Off
6. 选择 Continue 保存并退出

⚠️ 踩坑 6：配置文件权限问题

现象： 配置向导无法保存配置文件。

解决方案：

# 确保配置目录存在
mkdir -p ~/.openclaw

# 确保有写入权限
chmod 755 ~/.openclaw

⚠️ 踩坑 7：Token 未保存问题

现象： 配置完成后找不到 Gateway Token，无法配置飞书机器人。

解决方案：

1. 查看配置文件：

   cat ~/.openclaw/openclaw.json
   

2. 找到 gateway.token 字段
3. 强烈建议： 将 Token 保存到安全的地方（密码管理器）

第五阶段：点火启动

启动服务

openclaw start

服务启动后会显示：

Gateway running at http://localhost:18789
Dashboard: http://localhost:18789

访问控制台

在 Windows 浏览器中访问：

http://localhost:18789

⚠️ 踩坑 8：跨域错误（CORS）

现象： 在 Windows 浏览器输入局域网 IP（如 http://172.23.238.17:18789）时，页面飘红提示：

origin not allowed

原因： OpenClaw 的安全机制拦截了"陌生"的外部 IP 访问。

解决方案： 利用 WSL 共享本地环回地址的特性：

1. 把浏览器地址栏里的网址替换为：

   http://localhost:18789
   

   或

   http://127.0.0.1:18789
   

2. 刷新页面，即可完美绕过拦截，进入控制台 UI

⚠️ 踩坑 9：端口被占用

现象：

Error: listen EADDRINUSE: address already in use :::18789

解决方案：

1. 查找占用端口的进程：

   lsof -i :18789
   

2. 杀死占用进程：

   kill -9 <PID>
   

3. 重启服务：

   openclaw start
   

验证安装

完整验证流程

# 1. 检查 Gateway 状态
openclaw gateway status

# 2. 健康检查
openclaw health

# 3. 测试 API 连接
curl http://localhost:18789/health

# 4. 查看日志
openclaw daemon logs

验证清单

下一步：飞书机器人对接

步骤 1：创建飞书应用

1. 访问 https://open.feishu.cn/app
2. 点击 "创建应用" → "自建应用"
3. 填写应用信息：
   • 应用名称：OpenClaw Assistant
   • 应用图标：可选

步骤 2：获取应用凭证

1. 进入 "应用凭证" 页面
2. 记录：
   • App ID (cli_xxxxxxxxxxxxxxxx)
   • App Secret

步骤 3：配置权限

添加以下权限：

• im:message - 发送和读取消息
• im:chat - 访问群组信息
• contact:contact - 读取联系人信息

步骤 4：配置 OpenClaw

编辑配置文件 ~/.openclaw/openclaw.json：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "你的 App ID",
      "appSecret": "你的 App Secret"
    }
  }
}

步骤 5：测试连接

1. 在飞书中添加机器人
2. 发送测试消息：你好！你是谁？
3. 等待回复

常见问题 FAQ

wsl -l -v

curl -fsSL https://nodejs.org/dist/v22.11.0/node-v22.11.0-linux-x64.tar.xz | tar -xJ

npm config set registry https://registry.npmmirror.com
npm cache clean --force
curl -fsSL https://openclaw.ai/install.sh | bash

http://localhost:18789

openclaw configure

附录：完整命令清单

PowerShell 命令（Windows）

# 安装 WSL
wsl --install

# 查看已安装的 WSL 发行版
wsl -l -v

# 以管理员身份打开 PowerShell
Win + X → A

# 安装 Windows Terminal
winget install Microsoft.WindowsTerminal

Bash 命令（WSL）

# 更新软件源
sudo apt update

# 安装基础工具
sudo apt install curl git -y

# 安装 Node.js v22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# 切换 npm 镜像
npm config set registry https://registry.npmmirror.com
npm cache clean --force

# 安装 OpenClaw
curl -fsSL https://openclaw.ai/install.sh | bash

# 刷新环境变量
source ~/.bashrc

# 启动配置向导
openclaw configure

# 启动服务
openclaw start

# 查看状态
openclaw gateway status
openclaw health

# 查看日志
openclaw daemon logs

# 重启服务
openclaw daemon restart

参考资源

大管家 🦞 | 文档版本：v2.0 | 最后更新：2026-03-11