先说一句：如果你跟我一样，主力机是 Windows，但日常要跑各种命令行工具、脚本、AI agent 类应用，那我非常建议把这类工具放进 WSL 里，而不是强行在原生 Windows 环境里折腾。这篇记录的是我在 Windows 上安装 OpenClaw 的完整过程，用的是 WSL 方式，整个流程我重新跑过至少三遍，步骤是可靠的。文章会覆盖从初始化 WSL 环境到装好 OpenClaw、再到日常怎么和 Windows 协同使用的全部内容，适合第一次碰 WSL 的小白，也适合已经在用 WSL 但没装过这类 CLI 工具的人。
1. 为什么是 WSL：原生 Windows 的折腾点和 WSL 的取舍
先说结论：OpenClaw 这类工具，设计上就是按 Linux 生态来跑的。它依赖一堆底层行为，比如文件权限、软链接、进程信号、shell 环境变量传递，这些在 Windows 原生环境里都会变成莫名其妙的小问题。你能在 Windows 上装成功，但运行途中会遇到各种边界情况，查起来非常耗时间。
1.1 WSL 1 与 WSL 2 的差别，以及为什么推荐 WSL 2
WSL 2 和 WSL 1 是两条完全不同的实现路线。WSL 1 本质上是把 Linux 的系统调用翻译成 Windows 系统调用，兼容性说不上差，但遇到涉及文件系统 inode、socket 行为、内核模块的场景就容易出问题。WSL 2 则是真正跑了一个轻量虚拟机，里面有完整的 Linux 内核，OpenClaw 运行时的行为就和在真实 Linux 服务器上几乎一致。
多数 Linux 工具开发商在写安装文档时，会给用户提供 Linux 的安装命令，根本不会考虑 Windows。用 WSL 2 的好处就是：官方文档说怎么装，你就怎么装，不用再做任何“Windows 适配”翻译。OpenClaw 的安装脚本、依赖检查、路径权限设置，全部按 Linux 语义来跑，没人为难你。
WSL 2 的代价是它需要虚拟化支持。现在大多数 CPU 都支持，但你最好提前确认一下。
1.2 装之前你最好先确认这几件事
按顺序检查这几项，任何一个不满足，后面都会卡住：
- 系统版本：Windows 10 21H2 及以上，或者 Windows 11。这个要求并不苛刻，Win10 的老版本可以通过系统更新解决，Win11 通常开箱即用。
- BIOS 里的虚拟化开关：Intel 的 VT-x 或 AMD 的 SVM，需要处在开启状态。这个一般默认开着，但如果你的机器是二手、或者安全软件改过 BIOS 设置，有可能被关掉。
- Windows 功能里是否启用了“虚拟机平台”：安装 WSL 2 时会自动启用，但部分精简版系统需要手动打开，否则命令行会提示找不到虚拟化平台。
- 磁盘空间：装一个 Ubuntu 发行版，加上依赖和 OpenClaw 本体，预留 15GB 以上比较稳妥。如果还要跑模型文件或数据集，再多留一点。
提示：如果系统提示“WSL 2 需要更新内核”，就按提示下载更新包完成安装，或者直接执行
wsl --update。这比手动去下载内核包要简单得多。
2. 初始化 WSL 环境：从零到能跑 Ubuntu
环境初始化是整个流程的基础。我会按“命令执行、注意事项、验证结果”的顺序讲，照做基本不会翻车。
2.1 Windows 侧的开启命令
在 Windows 管理员权限的 PowerShell 里，执行：
wsl --install这一步在较新系统上会同时开启 WSL 功能、启用虚拟机平台、安装默认的 Ubuntu 发行版。如果没有自动装 Ubuntu，可以追加参数指定：
wsl --install -d Ubuntu执行完后，系统一般会提示重启。重启后发行版会自动继续安装，或者你在开始菜单里找到已装好的 Ubuntu 图标，点开走初始化流程。
如果你需要查看当前 WSL 版本和默认版本，可以用：
wsl --status wsl --version第一条约等于查“我现在的运行状态”，第二条看 WSL 组件版本。常见情况是：默认 WSL 版本已经是 2，但你还需要单独确认。
如果想完全手动启用，不靠自动命令，也可以这样操作：
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart提示：这两条命令需要管理员权限。手动方式适合自动化部署脚本，普通人直接用
wsl --install就行了。
2.2 发行版安装与账号初始化
重启之后，Ubuntu 会要求设置一个 Linux 用户名和密码。这个用户名只影响 Linux 侧的标识，和控制面板的 Windows 账号没有关系，随便取一个顺手的就行。
初始化完成之后，进入 Ubuntu 终端的第一件事是更新软件源和已有软件包：
sudo apt update && sudo apt upgrade -y这一步把系统软件索引和核心组件更新到较新状态，后续安装依赖时才不会遇到版本过旧的问题。更新过程中如果网络慢，可以留意自己系统的软件源配置，把源切换到响应更快的服务商镜像，很多地区的网络会明显改善。
验证 WSL 版本是否为 2，可以在 Windows PowerShell 里执行：
wsl -l -v输出结果里，VERSION 列显示 2 就说明当前发行版跑在 WSL 2 上。如果显示 1，执行：
wsl --set-version Ubuntu 2转换成 WSL 2。这一步会花几分钟，主要是在做磁盘格式转换。
2.3 把发行版装进非系统盘
WSL 默认把发行版放在系统盘（C 盘），用久了会发现虚拟磁盘文件越来越大。OpenClaw 的会话记录、配置文件、缓存，加上 Node.js 和 Python 的依赖包，C 盘空间会快速被吃掉。
有几种方式可以解决。最简单的是在拿到发行版之后立刻做一次导出再导入，把系统盘里的虚拟磁盘迁移到 D 盘或 E 盘。操作步骤：
wsl --export Ubuntu D:\backup\ubuntu-backup.tar wsl --unregister Ubuntu wsl --import Ubuntu D:\WSL\Ubuntu D:\backup\ubuntu-backup.tar导入后默认会以 root 用户进入，需要手动设置一下默认用户。可以在 PowerShell 里执行：
ubuntu config --default-user 你的用户名提示：
wsl --unregister会删除当前发行版的所有数据，包括你还没保存的文件。先确认迁移文件已经导出来再执行。我是专门写了一条命令把备份放在非系统盘，避免系统盘满后蓝屏的问题。
3. Linux 侧依赖准备：装好 Node.js、Python、Git 和常用构建工具
OpenClaw 本体依赖 Node.js 运行时，同时它的一些插件会用 Python 执行子任务。这一节把 Linux 环境里缺的运行时全部补齐，并且解释一下每条依赖到底是干什么的。
3.1 系统软件源和基础包更新
先按官方方式更新包索引，然后再装几个基础包：
sudo apt update sudo apt install -y curl wget git build-essentialcurl和wget用来下载安装脚本和压缩包；git用来克隆源码仓库或检查依赖版本；build-essential提供make、gcc等编译工具链。有些 npm 包在安装时需要现场编译原生模块，没有工具链会直接报错。
建议顺手装ca-certificates：
sudo apt install -y ca-certificates这一步保证 HTTPS 证书能被正确识别，避免下载时出现证书校验失败。
3.2 用动态版本管理工具安装 Node.js
Node.js 建议不要直接 apt 安装。Ubuntu 仓库里的 Node.js 版本经常滞后，而 OpenClaw 对 Node 版本有最低要求，装太旧的版本会在启动时打印一堆语法兼容错误。
我用的是 nvm 这种方式。它会装在你的用户目录下，不影响系统其他组件，也能随时切换 Node 版本：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash执行完后，重新加载 shell 配置：
source ~/.bashrc然后安装 Node.js 的长期支持版本：
nvm install --lts nvm alias default --lts检查版本：
node -v npm -v如果能看到 v20 或 v22 之类的版本号，就说明 Node 环境没问题。这里不用管具体数字，只要它是 LTS 版本就行。
3.3 为什么需要 Python、Git 和那些小工具
Python 不需要太新，OpenClaw 的辅助脚本通常用 Python 3.10 以上就能跑。Ubuntu 自带的 Python 3 版本通常已经够用，不信可以看：
python3 --version如果版本偏低，用 apt 安装也行。
Git 和编译工具链则属于“不一定马上用，但一旦要用就必不可少”的类型。比如安装 OpenClaw 插件时，有些插件是直接从 GitHub 仓库安装的，没有 Git 会直接失败。而某些原生依赖需要预编译二进制找不到的时候，还会自动走源码编译，那 build-essential 就开始发挥作用了。
提示：在 Linux 环境里，环境变量 PATH 是否干净，直接影响后续安装结果的可用性。为了减少问题，建议在装完依赖后，重启一次 WSL：在 PowerShell 执行
wsl --shutdown，再重新进入 Ubuntu，这样能确保 shell 配置被完整加载。
4. 安装 OpenClaw：下载、校验、初始化
依赖就绪后，安装 OpenClaw 就只是一套标准流程了。整个环节我拆成四步：获取安装包、校验完整性、初始化配置、执行环境自检。
4.1 获取安装包和确认完整性
OpenClaw 作为一个开源命令行工具，正常发布渠道会提供两类安装方式：一是在官网安装脚本，二是手动下载对应平台的发布压缩包。我更推荐先看官方文档的安装脚本方式，因为它会把依赖检查一起做掉：
curl -fsSL 官方安装地址 | bash但这里的“官方安装地址”在不同版本里可能有区别。如果你想完全掌控安装过程，不依赖脚本，那就走手动下载：
- 进入项目的 GitHub Release 页面，找到
linux-x64相关的压缩包。 - 下载后，解压到用户目录下，比如
~/openclaw。 - 把可执行文件放到 PATH 范围内，常见做法是建立软链接：
sudo ln -s ~/openclaw/bin/openclaw /usr/local/bin/openclaw软链接的好处是：以后更新时只要替换~/openclaw目录里的内容，系统命令路径不用改动。
校验完整性这一点，以前我经常跳过，但后来被坑过一次。建议至少检查一下压缩包的校验值和发布页是否一致。如果 GitHub 页面上给出了 SHA256 值，就执行：
echo "提供的校验值 下载的压缩包" | sha256sum -c -如果显示OK，就表示文件完好。
4.2 PATH 和配置文件位置
安装完成后，你可能还会碰到一个问题：明明装好了，输入openclaw却提示找不到命令。这就是 PATH 配置没生效。
先看当前可执行文件在哪里：
which openclaw如果没有输出，说明它不在 PATH 里。需要把它的所在目录加进去，编辑~/.bashrc：
export PATH="$HOME/openclaw/bin:$PATH"然后重新加载：
source ~/.bashrcOpenClaw 的配置文件通常生成在~/.openclaw/config.toml。这里存放 API 端点、模型参数、插件开关等设置。第一次启动时它不一定存在，可以通过初始化命令生成。
4.3 首次初始化和环境自检
在项目目录下执行：
openclaw init初始化命令会询问几个基本问题：工作目录、默认终端类型、是否需要启用某些插件。不要直接一路回车，建议认真看一下提示。特别是“工作目录”选项，它决定了后续 OpenClaw 操作文件时的基准路径。
初始化完成后，运行内置诊断工具确认环境没问题：
openclaw doctor这个命令会检查运行时版本、配置文件权限、依赖命令是否齐全。如果某项标红，就按提示修。最常见的结果是某条命令版本太低，升级一下对应组件就行。
如果一切正常，就可以做个快速验证，直接进入交互模式：
openclaw它会进入一个命令行交互界面，类似普通终端但多了一些快捷键和状态栏。如果能看到启动界面，说明核心安装已经成功。
4.4 基础用法和常见命令
OpenClaw 常用命令并不复杂，安装完先熟这几个就够用：
| 命令 | 作用 |
|---|---|
openclaw | 进入交互式对话界面 |
openclaw run "任务描述" | 单次执行任务，适合脚本调用 |
openclaw doctor | 检查环境健康状态 |
openclaw plugin list | 查看当前已启用插件 |
openclaw config show | 查看当前配置信息 |
把交互界面当主战场，把run当脚本后门。日常我习惯用openclaw run去处理批量任务，比如写一个定时脚本调用它处理日志，而手动调试时才进交互模式。
5. Windows 与 WSL 的协同使用：把它当成一个普通命令
装好 OpenClaw 只是第一步。真正好用的状态是：你坐在 Windows 桌面，打开任意终端，敲openclaw就能用，不用每次手动跑到 WSL 窗口里。这里有几个协同技巧。
5.1 从 PowerShell 调用 WSL 里的命令
WSL 提供了一个从 Windows 侧发起命令的入口：
wsl.exe openclaw这个命令会在 WSL 默认发行版中运行openclaw。如果你只装了 Ubuntu，那它就会在 Ubuntu 里启动。
但每次敲wsl.exe openclaw比较麻烦，尤其你想接参数的时候。可以创建 Windows 侧别名。在 PowerShell 里输入：
Set-Alias openclaw 'wsl.exe openclaw'或者更彻底：做一个简洁的批处理，让“openclaw”在 Windows 的任意位置可用。
5.2 创建一个叫 openclaw.cmd 的包装器
在 Windows 上最常见也最稳定的做法，是写一个.cmd包装脚本，放到 Windows 的 PATH 目录里，比如C:\Users\你的用户名\AppData\Local\Microsoft\WindowsApps。
内容很简单：
@echo off wsl.exe openclaw %*保存为openclaw.cmd，然后重新打开一个终端，输入：
openclaw --help这时你会发现，它就像 Windows 原生装了一个 OpenClaw 一样。所有参数都会原样传给 WSL 里的 openclaw。
提示：不要在包装脚本里把
%*漏掉，否则你没法传参数，每次调用都只能进入交互界面。
5.3 文件交换与两个文件系统间的性能差异
WSL 可以访问 Windows 磁盘，Windows 也可以访问 WSL 里的文件。从 Ubuntu 里看 Windows 盘符，它们被挂载在/mnt/c、/mnt/d这样的位置。反向的访问则基于\\wsl$网络路径，例如\\wsl$\Ubuntu\home\用户名\project。
但这里有个性能大坑：跨文件系统运行程序会很慢。
如果你把 OpenClaw 的项目放在C:\project，然后在 WSL 里进入/mnt/c/project启动 OpenClaw，你会明显感觉到启动变慢，文件监听和编译操作也经常卡顿。原因是 WSL 访问 Windows 文件系统时要经过一层翻译，IO 开销很大。
最佳实践是：把和 OpenClaw 相关的项目文件放在 WSL 自己的文件系统里，比如~/projects，然后通过\\wsl$路径让 Windows 侧的工具去访问它。同样的文件操作，速度差异可以有数倍之多。
5.4 Windows Terminal 的配置建议
如果你还在用默认终端窗口，建议换成 Windows Terminal。它对 WSL 的支持已经非常成熟，可以给每个发行版设独立外观、快捷键、起始目录，而且支持在同一个窗口里开多个 Tab。
在 Windows Terminal 的设置里，把默认配置文件改成 Ubuntu，这样每次打开终端，直接就是 WSL 环境。同时把startingDirectory设置成\\wsl$\Ubuntu\home\你的用户名\project，以后一开终端就能直接操作 OpenClaw 项目。
6. 实测中踩过的坑和对应修复
安装教程讲得顺利，但实际跑起来还是踩了五六个坑。我把这些问题的现象、原因和修复方法完整记录下来，方便你遇到时照着处理。
6.1 “command not found” 的三种常见原因
第一次装完 OpenClaw 后，我兴冲冲地输入openclaw，结果提示命令找不到。排查了一通，通常是这三种原因：
- 可执行文件所在的目录不在 PATH 里。解决办法是把安装目录 export 进
~/.bashrc。 - 用了 nvm 安装 Node，但
~/.bashrc里的 nvm 初始化代码没被加载。这种情况很少见，多半是用了zsh时忘记把 nvm 初始化脚本转移到~/.zshrc。 - 安装脚本实际装到了用户目录，但当前 shell 的 hash 表没有刷新。先执行
hash -r再重试。
逐条排除时，最快的方法是先which openclaw，看它到底在哪里。如果连输出都没有，说明 PATH 没指对；如果有输出但执行失败，那是权限问题。
6.2 执行初始化命令时提示网络超时
OpenClaw 初始化过程中会拉取一些远程配置或模型列表，如果网络不稳定，就会卡在 “request timed out” 之类的提示上。
不同地区的网络环境不一样。我的处理方式是：
- 先确认基础网络是否正常：在 WSL 里执行
ping 一个稳定的公网域名，看丢包率。 - 确保 WSL 的 DNS 解析正常。偶尔 WSL 的 DNS 会因为 Windows 侧网络切换而失效，执行
sudo resolvectl flush-caches可以清掉缓存。 - 如果一直超时，可以选择一个不同的网络连接，或改在流量时段执行初始化。
6.3 内存占用过高或运行卡顿
WSL 2 的默认内存占用策略是：尽量使用宿主机内存。如果你发现 OpenClaw 跑了一会儿，Windows 的内存被占掉不少，可以在用户目录下创建.wslconfig文件，限制 WSL 的内存和 CPU 占用。
我自己的.wslconfig设置大概是：
[wsl2] memory=4GB processors=4 swap=2GB localhostForwarding=true其中localhostForwarding=true的作用是让 WSL 里启动的服务可以直接用 Windows 浏览器访问localhost，OpenClaw 的本地调试界面也用得上。
改完配置后需要重启 WSL：
wsl --shutdown然后再启动 Ubuntu，配置才会生效。
6.4 Vmmem 进程占用过高
使用 WSL 2 时，Windows 任务管理器里会看到一个叫 Vmmem 的进程，它就是 WSL 虚拟机的内存占用的总入口。
如果 Vmmem 一直高占用，先别急着杀进程，先确认是不是 OpenClaw 正在执行任务。如果确实没有任务，但内存占用还是很离谱，大概率是缓存未释放。重启 WSL 是最快的方法：
wsl --shutdown不要直接在任务管理器里结束 Vmmem 进程，那会让整个 WSL 环境异常退出。
6.5 终端中文显示乱码
OpenClaw 运行时，终端里会出现中文输出。如果 Windows 上的终端没配好字体和编码，中文就会变成乱码。
解决方法是把 Windows Terminal 的字体设置成支持中文的等宽字体，同时确保 WSL 的 locale 已设置为中文或 UTF-8：
sudo apt install -y language-pack-zh-hans sudo update-locale LANG=zh_CN.UTF-8然后重新进入 WSL，中文输出就正常了。这个坑最好提前规避，否则看日志时会很痛苦。
安装到这一步，OpenClaw 在 WSL 里已经能稳定跑起来了。我后来还做了一件事：把openclaw的自动启动脚本放进了 WSL 的启动项，让每次打开 Ubuntu 终端时自动拉起工作目录，省掉了手动cd的步骤。另外一个小习惯是把配置文件备份成config.example.toml，以后重装系统时直接复制回去，几分钟就能恢复一套完整环境。如果你也打算长期用 OpenClaw，建议尽早把 WSL 迁移到非系统盘，并限制好内存上限，这套组合使用起来会舒心很多。
