OpenClaw Windows 使用指南：WSL2 安装、限制说明与常见问题

OpenClaw 支持在 Windows 上运行，官方推荐通过 WSL2（Windows Subsystem for Linux 2）安装，以获得与 macOS/Linux 一致的工具兼容性和运行稳定性。原生 Windows 安装方案目前尚在开发中。需要提前了解的关键限制：iMessage 渠道仅限 macOS，浏览器自动化功能在 WSL2 环境下需要额外配置 Chrome CDP 跨网络命名空间通信。本文提供从 WSL2 搭建到常见问题排查的完整操作流程。

Windows 平台支持现状

方案	支持状态	推荐程度
WSL2（Ubuntu）	✅ 完整支持	⭐⭐⭐ 官方推荐
Docker Desktop for Windows	✅ 支持	⭐⭐ 适合服务器场景
原生 Windows（无 WSL2）	⚠️ 部分支持，开发中	⭐ 不推荐用于生产

官方文档注明："Native Windows companion apps are planned. Contributions are welcome."——原生 Windows 完整支持尚未落地，目前最稳定的路径是 WSL2。

方案一：WSL2 安装（推荐）

前置条件

Windows 10 版本 2004 及以上，或 Windows 11
以管理员身份运行 PowerShell

Step 1：安装 WSL2 + Ubuntu

在 PowerShell（管理员）中运行：

wsl --install

该命令自动安装 WSL2 内核和默认 Linux 发行版（Ubuntu）。安装完成后重启 Windows。

重启后 Ubuntu 会弹出首次设置向导，创建用户名和密码后进入 Linux 终端。

验证 WSL2 安装成功：

wsl --list --verbose
# 应显示 Ubuntu 版本和 WSL2 标记

Step 2：启用 systemd（必须）

OpenClaw 的 Daemon 安装依赖 systemd。在 Ubuntu 终端中编辑配置文件：

sudo nano /etc/wsl.conf

写入以下内容：

[boot]
systemd=true

保存后退出 Ubuntu，在 PowerShell 中重启 WSL2：

wsl --shutdown
wsl

验证 systemd 已启用：

systemctl --version
# 应输出 systemd 版本号

Step 3：安装 Node.js 22+

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc

# 安装并激活 Node.js 22
nvm install 22 && nvm use 22 && nvm alias default 22

# 验证
node --version   # v22.x.x

Step 4：安装 OpenClaw

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

或使用 npm：

npm install -g openclaw@latest
openclaw onboard --install-daemon

Step 5：验证安装

openclaw doctor
openclaw status

预期输出：No blocking issues found，Runtime: running。

方案二：Docker Desktop（服务器场景）

若不想使用 WSL2，Docker Desktop for Windows 是另一种选择，适合将 OpenClaw 作为后台服务持续运行：

# PowerShell 中运行（需已安装 Docker Desktop）
docker run -d `
  --name openclaw `
  -p 18789:18789 `
  -v "$env:USERPROFILE\.openclaw:/root/.openclaw" `
  openclaw/gateway:latest

Control UI 访问地址：http://127.0.0.1:18789

模型配置：Windows 下接入七牛云

在 WSL2 的 Ubuntu 环境中，创建环境变量文件：

mkdir -p ~/.openclaw
cat >> ~/.openclaw/.env << 'EOF'
QINIU_API_KEY=sk-your-api-key-here
EOF

在 ~/.openclaw/openclaw.json 中配置模型：

{
  gateway: { mode: "local" },
  agents: {
    defaults: {
      model: {
        primary: "qiniu/deepseek-v3.2-251201"
      }
    }
  },
  channels: {
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",
      dmPolicy: "pairing"
    }
  }
}

七牛云推理服务使用 OpenAI 兼容接口（端点 https://api.qnaigc.com/v1），在 WSL2 的 Linux 环境中调用外部 API 与 macOS/Linux 完全一致，无需额外网络配置。

Windows 特有限制

限制 1：iMessage 不可用

iMessage 渠道依赖 macOS 的 Messages 应用，Windows 无法支持。Windows 用户可用的替代渠道：

可用渠道	说明
Telegram	✅ 完整支持，推荐首选
Discord	✅ 完整支持
Slack	✅ 完整支持
WhatsApp	✅ 支持（需手机扫码配对）
Signal	✅ 支持

限制 2：浏览器自动化需要额外配置

WSL2 运行在独立的网络命名空间中，默认无法直接访问 Windows 主机上的 Chrome CDP 端口（localhost:9222）。以下是完整解决流程。

浏览器自动化：WSL2 + Chrome CDP 配置

问题根因

WSL2 的 localhost 与 Windows 的 localhost 是两个不同的网络命名空间。Chrome 在 Windows 上以调试模式启动后，WSL2 内的 OpenClaw 无法通过 127.0.0.1:9222 连接，需要使用 Windows 宿主机的实际 IP 地址。

完整配置步骤（6 层排查）

第 1 层：在 Windows 启动带调试端口的 Chrome

在 Windows PowerShell 中：

& "C:\Program Files\Google\Chrome\Application\chrome.exe" `
  --remote-debugging-port=9222 `
  --no-first-run

验证 Chrome CDP 正常：

curl http://127.0.0.1:9222/json/version
# 应返回 Chrome 版本信息 JSON

第 2 层：在 WSL2 中获取 Windows 宿主机 IP

# 方法一：从 /etc/resolv.conf 读取
cat /etc/resolv.conf | grep nameserver | awk '{print $2}'

# 方法二：直接获取网关 IP
ip route show default | awk '{print $3}'

# 记录这个 IP，通常类似 172.x.x.1 或 192.168.x.1
WINDOWS_IP=$(ip route show default | awk '{print $3}')

验证 WSL2 能访问 Windows 的 CDP 端口：

curl http://$WINDOWS_IP:9222/json/version

若无响应，说明 Windows 防火墙阻止了该端口，需要在 Windows 防火墙中放行 9222 端口：

# PowerShell（管理员）
New-NetFirewallRule -DisplayName "Chrome CDP for WSL2" `
  -Direction Inbound -Protocol TCP -LocalPort 9222 -Action Allow

第 3 层：在 openclaw.json 中配置 cdpUrl

{
  tools: {
    browser: {
      cdpUrl: "http://172.x.x.1:9222",  // 替换为实际 Windows IP
    }
  }
}

第 4 层（如需 Extension Relay）

若使用 Chrome 扩展中继模式，需将绑定地址改为 0.0.0.0，允许跨命名空间连接：

{
  tools: {
    browser: {
      relayBindHost: "0.0.0.0"
    }
  }
}

第 5 层：验证 Control UI 可访问

在 Windows 浏览器中打开 http://127.0.0.1:18789（而非 WSL2 内部 IP），确认 Dashboard 正常加载。

第 6 层：端到端测试

向 Telegram Bot 发送：打开 google.com 截一张图——若浏览器自动化工作，将返回截图。

WSL2 与 Windows 文件系统互访

WSL2 和 Windows 文件系统可以互相访问，这对管理配置文件很有用：

# 在 WSL2 中访问 Windows C 盘
ls /mnt/c/Users/YourName/Documents

# 在 Windows 中访问 WSL2 文件（资源管理器地址栏输入）
\\wsl$\Ubuntu\home\username\.openclaw

建议：OpenClaw 配置文件（~/.openclaw/）保持在 WSL2 的 Linux 文件系统中，不要放在 /mnt/c/ 下——Linux 文件系统的 I/O 性能远高于通过 9P 协议访问 Windows 文件系统。

开机自启配置

WSL2 本身不随 Windows 开机自动启动，需要额外配置让 OpenClaw Gateway 在登录后自动运行。

方法：Windows 任务计划程序

打开"任务计划程序"，点击"创建基本任务"
触发器选择"用户登录时"
操作选择"启动程序"，填写：
- 程序：C:\Windows\System32\wsl.exe
- 参数：-d Ubuntu -- bash -c "openclaw gateway start"
在"条件"选项卡取消勾选"只在计算机使用交流电源时启动"

验证：重启 Windows 后等待约 30 秒，在 Ubuntu 中运行 openclaw gateway status 确认 Runtime: running。

常见问题

Q：WSL2 安装时报错 "请启用虚拟机平台 Windows 功能"，怎么解决？
在 PowerShell（管理员）中运行：

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

然后重启 Windows，再重新运行 wsl --install。

Q：WSL2 的 Ubuntu 中执行 openclaw gateway start 后，Windows 浏览器打开 http://127.0.0.1:18789 无法访问，怎么办？
WSL2 会自动做端口转发，通常 localhost:18789 在 Windows 浏览器中可直接访问。若无法访问，在 PowerShell 中手动添加转发：

netsh interface portproxy add v4tov4 listenport=18789 listenaddress=0.0.0.0 connectport=18789 connectaddress=$(wsl hostname -I | awk '{print $1}')

Q：WhatsApp 渠道在 Windows 上能用吗？
可以。WhatsApp 渠道通过扫码关联手机账号，与操作系统无关。在 WSL2 中运行 openclaw channels login 后，扫描 WhatsApp Web 二维码即可完成配对，之后即可通过 WhatsApp 向 OpenClaw 发送指令。

Q：WSL2 中的 OpenClaw 能访问 Windows 本地文件吗？
可以，通过 /mnt/c/ 路径访问。例如，向 OpenClaw 发送"总结 /mnt/c/Users/YourName/Documents/report.pdf"，可以读取 Windows 文件系统上的文件。

Q：Windows 上运行 OpenClaw 的性能和 macOS 有差距吗？
核心 AI 推理走的是远端 API（如七牛云端点），性能差异可忽略不计。本地文件操作和浏览器自动化在 WSL2 下会有轻微额外延迟（通常 < 100ms），日常使用几乎感知不到。

总结

Windows 用户使用 OpenClaw 的最优路径是 WSL2 + Ubuntu：安装脚本与 macOS/Linux 完全一致，systemd 支持 Daemon 自启，绝大多数功能可无差异使用。唯一需要额外配置的是浏览器自动化的 Chrome CDP 跨命名空间连接——按本文 6 层排查步骤逐一验证即可解决。

iMessage 是 Windows 平台唯一不可用的渠道，但 Telegram、Discord、Slack 等均可完整替代。对于不想维护 WSL2 环境的团队，Docker Desktop 是更简洁的部署选择。

本文基于 OpenClaw 官方文档（docs.openclaw.ai）及七牛云开发者平台，内容对应 2026 年 3 月版本，Windows 原生支持随官方迭代可能发生变化，建议定期关注 Release Notes。

延伸资源

OpenClaw 官方文档：https://docs.openclaw.ai
WSL2 + Chrome CDP 排查：https://docs.openclaw.ai/tools/browser-wsl2-windows-remote-cdp-troubleshooting
七牛云 AI 推理服务：https://www.qiniu.com/ai/models
七牛云 OpenClaw 配置指南：https://developer.qiniu.com/aitokenapi/13332/openclaw-installation-cuide

posted @ 2026-03-10 17:13 七牛云行业应用阅读(481) 评论(0) 收藏举报

刷新页面返回顶部

qiniushanghai