🌐WSL2 + Windows 完整配置指南

本教程将指导你在 Windows 的 WSL2（Ubuntu）中配置 OpenClaw，并让 Chrome 浏览器扩展正常工作，支持 AI 控制浏览器。

教程涵盖从零开始到解决常见的端口冲突、UI 资源缺失等问题，所有操作均安全可控，不要求手动编辑复杂配置文件。

一、环境准备

1确认 Windows 版本

• 建议 Windows 10 21H2 以上或 Windows 11，以获得最佳 WSLg 支持。
• 如果版本较低，可使用第三方 X server（如 VcXsrv）替代，本教程会提供两种方案。

2安装 WSL2 及 Ubuntu

在 Windows PowerShell（管理员）中执行：

wsl --install

重启电脑，然后从开始菜单启动 Ubuntu，完成初次设置。

3更新系统并安装基础工具

在 WSL 终端中执行：

sudo apt update && sudo apt upgrade -ysudo apt install -y curl wget git jq

jq 用于安全修改 JSON 配置文件，非常重要。

二、安装 OpenClaw

1全局安装（推荐）

npm install -g openclaw

安装完成后验证：

openclaw --version

2初始化配置

openclaw onboard

按提示完成初始设置，期间会生成 token 和基础配置文件。

三、解决图形界面问题

如果你使用 Windows 11 且 WSLg 正常，可跳过此节。若遇到 Missing X server 错误，说明 WSLg 不可用，请按以下步骤安装 VcXsrv。

1在 Windows 上下载安装 VcXsrv

• 访问 VcXsrv 下载页 下载安装。
• 安装后，从开始菜单启动 XLaunch。
• 在设置向导中：
• 第一步：选择 "Multiple windows"，下一步。
• 第二步：选择 "Start no client"，下一步。
• 第三步：务必勾选 "Disable access control"，下一步。
• 第四步：点击 "完成" 启动 X server。

2获取 Windows 的 IP 地址

在 Windows 命令提示符中执行：

ipconfig

找到 "vEthernet (WSL)" 网卡的 IPv4 地址（如 172.18.16.1），记录下来。

3在 WSL 中设置 DISPLAY 变量

export DISPLAY=172.18.16.1:0 # 将 IP 替换为你实际获取的地址

为了使每次登录自动生效，将上述命令添加到 ~/.bashrc：

echo "export DISPLAY=172.18.16.1:0" >> ~/.bashrcsource ~/.bashrc

4测试图形界面

安装一个简单图形工具测试：

sudo apt install -y x11-appsxeyes

如果弹出窗口，说明 X server 配置成功。

四、安装 Chrome 浏览器

虽然扩展本身在 Windows Chrome 中运行，但某些情况下需要 WSL 内有一个 Chrome 来启动调试端口。推荐安装以便后续可能的需求。

1下载并安装 Chrome

cd /tmpwget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.debsudo dpkg -i google-chrome-stable_current_amd64.debsudo apt install -f -y # 修复依赖

2验证运行

google-chrome-stable

如果弹出 Chrome 窗口，说明图形环境正常。

五、安装 OpenClaw 浏览器扩展

在 Windows Chrome 中完成以下步骤：

1在 WSL 中生成扩展文件

openclaw browser extension install

2获取扩展文件夹路径

openclaw browser extension path

输出类似：\\wsl.localhost\Ubuntu\home\你的用户名\.openclaw\browser\chrome-extension

3在 Windows Chrome 中加载扩展

• 打开 Chrome，地址栏输入 chrome://extensions/ 并回车。
• 开启右上角 "开发者模式"。
• 点击 "加载已解压的扩展程序"。
• 在文件选择对话框中，粘贴步骤 2 获取的路径（支持网络路径），选择该文件夹。
• 扩展加载成功，图标出现在工具栏。

4配置扩展连接 Gateway

• 在 WSL 中获取 token：

  jq -r '.token' ~/.openclaw/openclaw.json

• 点击 Chrome 工具栏的 OpenClaw 扩展图标，在弹出的窗口中输入 token，保存。
• 扩展应显示 ON 状态，并自动连接到 Gateway（默认端口 18789）。

5附加到标签页

• 打开任意网页（如百度）。
• 再次点击扩展图标，点击 "附加到当前标签页"（或自动附加）。图标应显示"已附加"。

6测试控制

在 OpenClaw 的聊天界面（Web 控制台或飞书等）发送指令，例如：

打开百度，搜索 OpenClaw

观察浏览器是否自动操作。

六、常见问题：多实例冲突与修复

如果你安装了第二个 OpenClaw（例如另一个机器人），可能会遇到：

• 扩展连接失败，提示 ws://127.0.0.1:18792 无法连接。
• Web 控制面板报错 Control UI assets not found。
• Gateway 实际运行在 18789 端口，而扩展固执地连接 18792。

原因：第二个机器人修改了配置或端口，导致组件不一致。

解决方法：统一端口为扩展期望的 18792，并修复 UI 资源。

步骤 1：备份当前配置（安全第一）

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup

步骤 2：修改 Gateway 端口为 18792

使用 jq 安全添加/修改端口，无需手动编辑文件：

jq '.gateway.port = 18792' ~/.openclaw/openclaw.json > ~/.openclaw/openclaw.json.tmp && mv ~/.openclaw/openclaw.json.tmp ~/.openclaw/openclaw.json

如果原文件已有 gateway 其他设置，此命令会保留它们，仅添加或修改端口。

步骤 3：验证修改

jq '.gateway' ~/.openclaw/openclaw.json

输出应包含 "port": 18792。

步骤 4：重启 Gateway

openclaw gateway restart

检查状态：

openclaw gateway status

确认 port=18792 且 Runtime: running。

步骤 5：修复 UI 资源缺失

openclaw doctor --repair

等待修复完成，再次重启 Gateway：

openclaw gateway restart

步骤 6：验证 Web 控制面板

浏览器打开 http://127.0.0.1:18792/，应正常显示登录或控制界面。

步骤 7：让扩展重新连接

扩展应自动发现新的端口（18792）并连接。如果扩展仍显示未连接：

• 点击扩展图标，重新输入 token（jq -r '.token' ~/.openclaw/openclaw.json）。
• 保存后，图标变为 ON，浏览器控制功能恢复。

步骤 8：清理多余实例（可选）

如果之前运行的第二个机器人还在占用端口，可以停止它：

sudo lsof -i :18792 # 检查是否有进程sudo kill <PID> # 结束它

七、注意事项

• 端口统一：
  扩展默认期望 18792，保持 Gateway 监听该端口可避免后续问题。
• 备份配置：
  任何时候修改前先备份，本教程已包含。
• 图形环境：
  若使用 VcXsrv，每次重启 Windows 后需手动启动 XLaunch，或将其加入开机启动。
• 扩展更新：
  若扩展更新后出现异常，可先移除再重新加载（路径不变）。
• 多实例：
  尽量避免同时运行多个 OpenClaw 实例，如确需多个，可修改端口并分别配置扩展。

八、故障排查速查表

通过以上步骤，你应该能顺利在 WSL 环境下配置 OpenClaw 浏览器扩展，并应对常见冲突问题。

如有其他疑问，可查阅官方文档或使用 openclaw doctor 进一步诊断。

关于作者

艺设·集美，策展与博物馆研究领域的实践者与观察者。专注于展览设计、数字博物馆、观众体验与文化传播的交叉研究。关注策展与技术的融合，致力于在理论与实务之间寻找平衡。每周更新策展干货、AI工具实操和数字文化观察等内容。