OpenClaw 在 Windows 上的完整安装教程
在Windows平台运用WSL2配置OpenClaw：一份专业级操作手册
方案总览
为在Windows系统运行OpenClaw这一开源AI智能体框架，官方建议采用WSL2作为核心部署环境。此方案选用Ubuntu作为Linux发行版，旨在确保运行时环境与工具链的高度统一。核心组件CLI与Gateway在Linux子系统内运行，能精准兼容Node.js、Bun运行时、pnpm包管理器及各类Linux二进制依赖，从根源上规避跨平台兼容性问题。
尽管实现原生Windows支持具备技术可能性，但其配置流程的复杂性与潜在的稳定性隐患不容忽视。使用WSL2则能以近乎原生的性能在Windows内构建一个完整的Linux开发栈，通常仅需一条指令即可完成安装，显著提升了部署效率与成功率。
原生Windows应用的开发已纳入项目路线图。
第一步：配置WSL2与Ubuntu环境
1.1 执行快速安装
启动管理员权限的PowerShell窗口，输入以下指令完成WSL2及默认发行版的安装：
wsl --install
如需安装特定版本的Ubuntu（例如当前稳定的24.04），可先查询列表后指定安装：
# 查看可用发行版
wsl --list --online
# 安装指定版本
wsl --install -d Ubuntu-24.04
1.2 完成系统重启
根据安装提示重启Windows系统，以加载并激活WSL2内核组件。
1.3 完成Linux初始化
重启后，从开始菜单启动“Ubuntu”应用。根据终端提示完成两项初始化设置：
- 设置一个独立的Linux用户名
- 为该用户创建密码
完成上述步骤后，你将获得一个功能完整的Ubuntu终端环境。
第二步：启用systemd支持
此步骤至关重要。OpenClaw的Gateway服务依赖systemd进行守护进程管理，而WSL2默认未启用此功能。
2.1 编辑WSL配置文件
在Ubuntu终端中，执行以下命令，向/etc/wsl.conf写入配置：
sudo tee /etc/wsl.conf >/dev/null <<‘EOF’
[boot]
systemd=true
EOF
2.2 重启WSL子系统
返回Windows PowerShell（管理员），执行关机指令使配置生效：
wsl --shutdown
2.3 验证systemd状态
重新打开Ubuntu终端，运行状态检查命令：
systemctl --user status
若终端输出活跃的服务列表而非错误信息，则表明systemd已成功启动。
第三步：部署OpenClaw核心
基础环境就绪后，开始安装OpenClaw本体。
3.1 拉取项目代码库
在WSL的Ubuntu终端中，克隆官方仓库并进入项目目录：
git clone https://github.com/openclaw/openclaw.git
cd openclaw
3.2 安装项目依赖
使用pnpm安装全部必要的依赖包：
pnpm install
3.3 构建用户界面
构建UI组件。首次执行此命令将自动获取UI相关依赖。
pnpm ui:build
# 首次运行会自动安装 UI 依赖
3.4 执行项目构建
运行完整的项目构建流程：
pnpm build
3.5 运行初始化向导
执行初始化命令，跟随交互式指引完成关键的第一步配置：
openclaw onboard
第四步：安装与配置Gateway服务
Gateway作为OpenClaw的调度中心，负责管理任务流。官方提供了多种安装途径。
方式一：自动化安装（推荐路径）
此方式在初始化配置流程中一体化完成服务安装：
openclaw onboard --install-daemon
方式二：独立安装命令
若已完成初始化，可直接通过以下命令安装：
openclaw gateway install
方式三：通过配置工具安装
启动交互式配置向导，并在其中选择安装Gateway服务的选项：
openclaw configure
服务修复与诊断
若安装过程遇阻，使用内置诊断命令快速定位问题：
openclaw doctor
高阶配置：实现局域网访问
端口转发的必要性
需理解一个关键技术点：WSL2运行在独立的虚拟网络内。若需从局域网内其他设备访问WSL中运行的服务，必须配置端口转发，将Windows主机的特定端口映射至WSL的内部IP。
请注意，WSL的IP地址在每次重启后可能变动，因此转发规则可能需要随IP变化而更新。
配置端口转发规则
以管理员身份打开PowerShell，执行以下脚本，将Windows主机的2222端口转发至WSL的22端口：
# 配置参数
$Distro = “Ubuntu-24.04”
$ListenPort = 2222 # Windows 监听端口
$TargetPort = 22 # WSL 内目标端口
# 获取 WSL IP 地址
$WslIp = (wsl -d $Distro -- hostname -I).Trim().Split(“ ”)[0]
if (-not $WslIp) { throw “无法获取 WSL IP 地址” }
# 添加端口转发规则
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPort `
connectaddress=$WslIp connectport=$TargetPort
配置防火墙入站规则（一次性）
在Windows防火墙上开放对应端口，允许入站连接：
New-NetFirewallRule -DisplayName “WSL SSH $ListenPort” -Direction Inbound `
-Protocol TCP -LocalPort $ListenPort -Action Allow
WSL重启后刷新IP映射
WSL重启后，执行此脚本以更新转发规则至新IP：
# 删除旧规则
netsh interface portproxy delete v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 | Out-Null
# 重新获取 IP 并添加规则
$WslIp = (wsl -d $Distro -- hostname -I).Trim().Split(“ ”)[0]
netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 `
connectaddress=$WslIp connectport=$TargetPort | Out-Null
核心注意事项
- 访问控制策略：脚本中
listenaddress=0.0.0.0允许整个局域网访问；若仅限本机，请改为127.0.0.1。 - 远程连接示例：在其他设备上使用
ssh user@windows-host-ip -p 2222进行连接。 - 远程节点配置：其他节点配置Gateway时，必须使用其可访问的IP或主机名，而非
127.0.0.1。使用openclaw status --all确认正确的访问地址。 - 实现自动化：可将IP刷新脚本设置为Windows计划任务，在登录时自动执行，以彻底解决IP变动问题。
部署验证
完成所有步骤后，通过以下命令验证OpenClaw各组件运行状态。
检查整体服务状态
openclaw status --all
查看Gateway守护进程状态
systemctl --user status openclaw-gateway
实时追踪服务日志
如需实时监控Gateway运行日志，可使用journalctl命令：
journalctl --user -u openclaw-gateway -f
故障排查指南
WSL2安装失败？
首先验证Windows版本：需要Windows 10版本2004（内部版本19041）或更高版本，或Windows 11。旧版本系统可能缺少必要支持。
systemd启动失败？
请检查/etc/wsl.conf文件内容是否准确无误，并确认已执行wsl --shutdown进行了完整重启。
端口转发失效？
建议按此顺序排查：
- 确认Windows防火墙中对应端口的“允许”规则是否仍生效。
- 手动核对WSL当前IP地址：
wsl -- hostname -I。 - 在PowerShell中执行
netsh interface portproxy show all，查看当前生效的转发规则。
Gateway服务无法启动？
运行诊断命令，该工具通常会提供明确的错误指向：
openclaw doctor
项目官方地址：https://github.com/openclaw/openclaw
AI技术创新浪潮已至，实践是掌握其脉搏的最佳方式。参与我们的AMA活动，与一线AI构建者直接交流，获取前沿洞察与实践经验。在深度对话中探索可能，更有机会获得专属激励。???? AMA活动：AI创作者第二期