官方推荐:WSL2+Ubuntu24.04,OpenClaw Gateway 网关依赖 systemd,WSL1 不支持,不要用 WSL1 两种安装方式:一键脚本安装(推荐) / 源码编译安装(开发调试)
Windows 10 20H2 或更高版本
已启用 WSL2(如果没有,继续往下看第一步)
前置条件
- Windows 10 2004+ / Windows11,BIOS/UEFI 开启 CPU 虚拟化(Intel VT-x / AMD SVM)
- 管理员权限终端,网络可访问 github/openclaw.ai(国内建议配置代理 / 镜像加速)
- 内存建议 ≥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
交互式配置:
- 选择模型服务商(OpenAI / Anthropic / 自定义 API,如火山、Ollama 本地模型)
- 填入 API Key、模型地址
- 选择消息通道(WebUI、Telegram 等,默认 WebUI 即可)
- 自动安装 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:手动浏览器访问
- WSL 内先启动网关:
openclaw gateway
- 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 核心坑点
- 必须开启 systemd + loginctl enable-linger,否则关闭 Ubuntu 终端后 OpenClaw 服务直接退出,网关掉线OpenClaw
- WSL2 网络是 NAT 模式,Windows 访问 WSL 内端口
18789默认没问题;如果端口不通,检查 Windows 防火墙放行 wsl --shutdown:修改 wsl.conf、修改配置后,必须完全关闭 WSL,只关闭终端窗口不会重启子系统- 文件读写:OpenClaw 工作目录尽量放在 WSL 内部(
~/.openclaw),不要放在 /mnt/c/Windows 目录,跨文件系统性能极差,容易文件锁报错
2. Node & 环境
- 不要手动 apt 安装系统 Node,版本过低会冲突,官方脚本自带托管 Node 环境
- Node 版本要求 ≥22.22.3 / 24.x,推荐 24LTS;脚本自动处理,手动装容易版本不匹配
- 国内 npm/pnpm 下载慢:安装前配置国内镜像源
3. OpenClaw 服务与权限
- 使用用户级 systemd 服务(–user),不要用 root 运行 OpenClaw,权限错误会导致工作区读写失败
- API Key 保管:配置文件存放在
~/.openclaw/,不要泄露密钥 - Ollama 本地模型联动:Ollama 可以装在 Windows 主机,WSL 内 OpenClaw 通过 Windows 主机 IP 访问 Ollama(不要用localhost)
4. 网络 & 防火墙
- 安装脚本需要访问
openclaw.ai和 github;国内网络大概率超时,建议配置代理 - Windows 防火墙弹窗:允许 WSL2 的通信,否则浏览器打不开 WebUI
- 如果需要外网访问 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. 常见报错快速排查
openclaw: command not found:PATH 环境变量未加载,重新 source ~/.bashrc,或者重启 WSL- gateway 无法启动:
openclaw doctor看报错,优先检查 systemd、dbus 是否安装 - WebUI 打不开:
openclaw gateway status确认服务 running;确认端口 18789 没有被其他程序占用 - 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
