Windows 10 系统下WSL2 安装部署 OpenClaw

官方推荐:WSL2+Ubuntu24.04,OpenClaw Gateway 网关依赖 systemd,WSL1 不支持,不要用 WSL1 两种安装方式:一键脚本安装(推荐) / 源码编译安装(开发调试)
Windows 10 20H2 或更高版本
已启用 WSL2(如果没有,继续往下看第一步)

前置条件

  1. Windows 10 2004+ / Windows11,BIOS/UEFI 开启 CPU 虚拟化(Intel VT-x / AMD SVM)
  2. 管理员权限终端,网络可访问 github/openclaw.ai(国内建议配置代理 / 镜像加速)
  3. 内存建议 ≥8G,推荐 16G;C 盘预留至少 10G 空间(可后续迁移 WSL 到 D 盘)

第一步:启用 WSL2

  • 以 管理员身份 打开 PowerShell,执行:
wsl --install

PowerShell错误提示:

PS C:\Windows\system32> wsl --install -d Ubuntu-24.04
无法解析服务器的名称或地址
PS C:\Windows\system32>
  • 设置DNS地址如下图:
  • 刷新DNS缓存
ipconfig /flushdns

如果提示 wsl –install 不是已知命令,说明是旧版 Windows,需要先手动启用相关功能:

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
  • 设置代理下载速度要快,规避了很多网络问题造成的问题
  • 然后重启电脑,再执行:
wsl --install -d Ubuntu-24.04
  • 如果报错
PS C:\Windows\system32> wsl --install -d Ubuntu-24.04
无效的分发名称: “Ubuntu-24.04”。
若要获得有效的分发列表,请使用“wsl --list --online”。
PS C:\Windows\system32>
  • 先执行这条看当前可用发行版
wsl --list --online
  • 管理员 PowerShell 执行
wsl --install -d Ubuntu
  • 如果再次报「无法解析服务器的名称或地址」,改用带 web-download 参数:
wsl --install --web-download -d Ubuntu
# 列出本地已安装的WSL发行版(含版本WSL1/WSL2、默认)
wsl --list --verbose
wsl -l -v
  • 记得更新升级一下系统
sudo apt update && sudo apt upgrade -y

第二步:WSL 内开启 systemd(OpenClaw 网关必须)

  • 打开 WSL 终端(开始菜单搜索 Ubuntu),执行:
sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF
  • 然后关闭 WSL 使配置生效:
wsl --shutdown
  • 再次打开 WSL 终端确认 systemd 正常:
systemctl --user is-enabled multi-user.target
systemctl --user status
  • 如果 systemd 正常无法正常运行,例如如下提示:
zxb@创世纪网络备用电脑:~$ openclaw gateway start
OpenClaw 2026.9.8 (fc23bc8) — You had me at 'openclaw gateway start.'
Gateway service disabled.
  • 2. 安装 OpenClaw gateway 服务

回到 WSL 终端执行:

openclaw gateway install
  • 如果不行,可能 WSL 版本比较旧,建议在 PowerShell 执行更新:
wsl --update

你先执行 ps -p 1,把输出发给我确认 PID1 是不是 system

  • SSH远程WSL
sudo apt update && sudo apt install -y openssh-client
sudo apt install openssh-server
  • 启动SSH服务
sudo service ssh restart

WSL2 的 SSH 服务默认没开启,且网络是 NAT。步骤配置参考:

# 1. WSL 里安装并启动 SSH 服务
sudo apt install openssh-server
sudo service ssh start

# 2. 修改配置(允许密码/密钥登录)
sudo sed -i 's/#Port 22/Port 2222/' /etc/ssh/sshd_config
sudo service ssh restart

# 3. 在 Windows 上做端口转发,把 2222 端口映射到 WSL
netsh interface portproxy add v4tov4 listenport=2222 listenaddress=0.0.0.0 connectport=2222 connectaddress=<WSL的IP>

# 4. 开启 Windows 防火墙 2222 端口

安装 OpenClaw【一键脚本,推荐】

  • 在 Ubuntu(WSL)终端执行官方一键安装脚本:
curl -fsSL https://openclaw.ai/install.sh | bash

脚本会自动检测、安装适配版本 Node.js,不需要手动装 Node,避免版本冲突OpenClaw

国内网络:curl 超时可以给脚本增加代理,或者改用源码方式。

  • 这里我先跳过,后续在配置大模型接入

初始化向导 onboard

openclaw onboard --install-daemon

交互式配置:

  1. 选择模型服务商(OpenAI / Anthropic / 自定义 API,如火山、Ollama 本地模型)
  2. 填入 API Key、模型地址
  3. 选择消息通道(WebUI、Telegram 等,默认 WebUI 即可)
  4. 自动安装 systemd 后台服务(daemon),WSL 启动自动拉起 OpenClaw 网关

验证安装

# 查看版本
openclaw --version

# 健康自检,全部OK才算成功
openclaw doctor

# 查看网关服务状态
openclaw gateway status

看到 gateway running 代表网关正常。

如何无法启gateway,执行如下命令:

openclaw gateway install

访问 WebUI

默认地址:http://localhost:18789 WSL2 端口自动映射到 Windows 主机,直接在 Windows 浏览器打开即可。

✅ 方式 2:手动浏览器访问
  1. WSL 内先启动网关:
openclaw gateway
  1. Windows 宿主机浏览器直接访问:
http://127.0.0.1:18789
  • 复制命令到WSL系统内:openclaw gateway auth-token –show

⚠️ WSL2 注意点(你当前环境重点) WSL2 NAT 模式,默认只能 WSL 内部访问 127.0.0.1:18789;Windows 宿主机访问 WSL 服务,需要端口转发,否则打不开页面。

WSL2 端口转发A(Windows PowerShell 管理员执行)

# 将Windows 18789端口转发到WSL2的IP:18789
netsh interface portproxy add v4tov4 listenport=18789 listenaddress=0.0.0.0 connectport=18789 connectaddress=$(wsl --hostname -I | awk '{print $1}')
# 放行Windows防火墙18789端口
New-NetFirewallRule -DisplayName "OpenClaw 18789" -Direction Inbound -LocalPort 18789 -Protocol TCP -Action Allow

WSL2 端口转发B(Windows 访问 WSL 里的服务,NAT 模式必备)

PowerShell 管理员执行,示例:把 Windows 的 8080 转发到 WSL 的 80 端口

netsh interface portproxy add v4tov4 listenport=18789 listenaddress=0.0.0.0 connectport=18789 connectaddress=WSL的IP

查看 WSL IP:ip addr(eth0 的 inet 地址)

🔐 身份验证(页面提示 Token 时)

查看当前网关认证 Token:

openclaw config get gateway.auth.token

把输出的 token 粘贴到 WebUI 登录框即可。 重新生成 token:

openclaw doctor --generate-gateway-token

常用管理命令(WSL 内)

# 启动网关
openclaw gateway start
# 停止网关
openclaw gateway stop
# 查看日志
openclaw logs
# 重启服务
systemctl --user restart openclaw
# 查看服务
systemctl --user status openclaw

⚠️ 重点注意事项(踩坑清单)

1. WSL 核心坑点

  1. 必须开启 systemd + loginctl enable-linger,否则关闭 Ubuntu 终端后 OpenClaw 服务直接退出,网关掉线OpenClaw
  2. WSL2 网络是 NAT 模式,Windows 访问 WSL 内端口18789默认没问题;如果端口不通,检查 Windows 防火墙放行
  3. wsl --shutdown:修改 wsl.conf、修改配置后,必须完全关闭 WSL,只关闭终端窗口不会重启子系统
  4. 文件读写:OpenClaw 工作目录尽量放在 WSL 内部(~/.openclaw),不要放在 /mnt/c/Windows 目录,跨文件系统性能极差,容易文件锁报错

2. Node & 环境

  1. 不要手动 apt 安装系统 Node,版本过低会冲突,官方脚本自带托管 Node 环境
  2. Node 版本要求 ≥22.22.3 / 24.x,推荐 24LTS;脚本自动处理,手动装容易版本不匹配
  3. 国内 npm/pnpm 下载慢:安装前配置国内镜像源

3. OpenClaw 服务与权限

  1. 使用用户级 systemd 服务(–user),不要用 root 运行 OpenClaw,权限错误会导致工作区读写失败
  2. API Key 保管:配置文件存放在 ~/.openclaw/,不要泄露密钥
  3. Ollama 本地模型联动:Ollama 可以装在 Windows 主机,WSL 内 OpenClaw 通过 Windows 主机 IP 访问 Ollama(不要用localhost)

4. 网络 & 防火墙

  1. 安装脚本需要访问openclaw.ai和 github;国内网络大概率超时,建议配置代理
  2. Windows 防火墙弹窗:允许 WSL2 的通信,否则浏览器打不开 WebUI
  3. 如果需要外网访问 WebUI:不建议直接暴露;可以用 frp 反向代理,增加鉴权

5. 存储与迁移(C 盘空间不足)

WSL 默认镜像存在 C 盘,占用大,可以导出迁移到 D 盘:

wsl --export Ubuntu-24.04 D:\wsl_backup\ubuntu.tar
wsl --unregister Ubuntu-24.04
wsl --import Ubuntu-24.04 D:\wsl\Ubuntu2404 D:\wsl_backup\ubuntu.tar --version 2

迁移完成后需要重新设置默认用户。

6. 常见报错快速排查

  1. openclaw: command not found:PATH 环境变量未加载,重新 source ~/.bashrc,或者重启 WSL
  2. gateway 无法启动:openclaw doctor 看报错,优先检查 systemd、dbus 是否安装
  3. WebUI 打不开:openclaw gateway status确认服务 running;确认端口 18789 没有被其他程序占用
  4. WSL 空闲自动退出:WSL2 2.6.1 + 有空闲回收 bug,安装 dbus-x11 并启用 linger 缓解

7. 安全提醒

  • OpenClaw Agent 拥有文件读写、命令执行能力,不要给高权限,不要用 root
  • 公网暴露 WebUI 务必设置强密码,不要裸奔
  • API Key 不要硬编码在配置文件以外的地方,不要提交到 git

卸载(如需)

WSL 内卸载 OpenClaw:

openclaw gateway uninstall
npm uninstall -g openclaw
rm -rf ~/.openclaw

PowerShell 彻底删除整个 Ubuntu 子系统:

wsl --unregister Ubuntu-24.04

Openclaw网关启动问题:https://www.hao0564.com/6302.html

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注