Wong Kosheng如果你手头是一台 Windows 电脑，又眼馋那些能自动写邮件、查资料、订日程的 AI Agent，OpenClaw 很可能是你绕不开的一个名字。它本质上是个把大模型变成“数字管家”的开源项目，你给它一个目标，它能自己拆解步骤、调用工具、执行动作，而不是像普通聊天机器人那样只给你吐一段文字。这篇是东方仙盟系列里“AI人工智能”栏目的第四十五篇，我不打算讲那些玄乎的架构，只聊一件事：怎么在你的 Windows 机器上，把 OpenClaw 老老实实跑起来。
先说结论：OpenClaw 官方文档虽然偏向 macOS 和 Linux，但 Windows 通过 WSL2 或 Docker Desktop 完全能跑。我前后在 Windows 11 和 Windows Server 2022 各部署过一遍，踩了不少坑，最典型的就是那个 could not safely verify the WSL2 environment 报错。这篇会把整个环境准备、依赖安装、配置启动、问题排查按顺序写清楚，也适合第一次接触 AI Agent 的同学照着抄。
1. OpenClaw 是什么？先搞懂你要部署的东西
1.1 核心定位：个人 AI 管家 / 数字员工
OpenClaw 是个可自托管的 AI 代理框架，简单说就是让你的大模型不只会聊天，还能真正“干活”。它给模型提供了一堆工具：发消息、读文件、写文件、查网页、调 API、执行命令，甚至接管手机上的应用。你只需要用自然语言描述任务，比如“帮我把这周的会议记录整理成表格发到邮箱”，它会自己规划步骤，逐步调用工具完成。
和普通聊天机器人最大的区别是：OpenClaw 有“行动闭环”。它不依赖某个云端厂商的固定流程，而是运行在你自己的机器上，数据默认留在本地。这也是它吸引人的地方，你想让它接什么服务、接哪些大模型，你自己说了算。
1.2 为什么 Windows 部署比 Linux 麻烦
OpenClaw 本身是 Node.js 项目，理论上跨平台，但实际运行中依赖很多 Linux 环境特性：文件权限、伪终端、进程管理、WSL 体系调用。如果你直接在 Windows 的 CMD 或 PowerShell 里跑，大概率会遇到路径分隔符、符号链接、依赖编译失败的问题。
更现实的是，官方很多启动脚本和工具链都假设你在 bash 环境里工作。Windows 上最优雅的办法就是装 WSL2，跑一个 Ubuntu 子系统，把 OpenClaw 装在里面。你不需要重新学习 Linux，只需要把它当成 Windows 里的一个“专用运行箱”。
1.3 部署前需要明白的几个概念
- WSL2：Windows Subsystem for Linux，微软官方的 Linux 兼容层，比虚拟机轻量，启动速度快，和 Windows 文件互通。
- Docker Desktop：Windows 下的容器环境，OpenClaw 官方提供 Docker 镜像，适合不想手动装 Node.js 的人。
- Agent Runtime：OpenClaw 的运行时，负责调度模型、工具和外部服务。
- 大模型后端：OpenClaw 本身不内置模型，它需要调用 OpenAI、Anthropic 或本地 Ollama、DeepSeek 等接口。
我建议手头是 Windows 11 的用户优先走 WSL2 + 源码运行方式，因为可定制性最强，出了问题也好定位。如果你只是尝鲜，Docker Desktop 更省事，但性能损耗和磁盘占用会高一些。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. Windows 部署前的环境准备（关键一步，错了全白费）
2.1 启用好 WSL2：版本要求与安装命令
我从头到尾踩过的第一个坑就是 WSL2 环境校验失败。OpenClaw 在启动时会检测 wsl.exe 和当前 WSL 发行版，如果版本不对或内核太旧，会直接拒绝运行。
安装 WSL2 的推荐方式是在管理员权限的 PowerShell 或 CMD 里执行：
powershell复制wsl --install
这条命令会自动启用需要的 Windows 功能、安装 WSL2 内核，并默认装好 Ubuntu。装完后重启系统，执行：
powershell复制wsl --status
确认默认版本是 2。如果显示默认版本 1，用下面命令切换：
powershell复制wsl --set-default-version 2
还要检查内核版本：
powershell复制wsl --update
把内核更新到最新。Windows 10 的话，要求版本 19041 或更高；Windows 11 一般没问题。如果你本机已经开了 Hyper-V 或虚拟机平台，WSL2 会更顺畅，但注意不要在老旧的 BIOS 机器上忘记开启虚拟化。
2.2 安装 Docker Desktop 还是直接装 Node.js？
这是两套方案，我分别说下适用场景。
方案 A：WSL2 + Node.js 源码运行。适合要改代码、调试插件、折腾细粒度配置的人。因为 OpenClaw 更新很快，直接拉源码跑 git pull 就能升级，依赖也直观。
方案 B：WSL2 + Docker Desktop。适合不想污染 WSL 环境、只想快速跑起来的人。OpenClaw 官方在 Docker Hub 上有镜像，一条 docker run 就能拉起。但容器方式不太方便调试本地文件系统，如果你想把它做成开机自启服务，反而要多写一层容器管理逻辑。
我个人偏好方案 A。原因很简单：容器的“黑盒”会让问题排查变麻烦，比如你想看看日志、改个环境变量，还得 docker exec 进去，不如直接源码跑来得透明。
2.3 需要准备的 API Key 与本地模型选项
OpenClaw 的核心配置是“模型接口”。如果你有 OpenAI 或 Anthropic 的 Key，直接填进去就能用。如果你没有，或者希望离线运行，可以把 OpenClaw 指向本地 Ollama 或 DeepSeek 的接口。
我建议至少准备以下东西：
- 一个可用的大模型 API Key（OpenAI / DeepSeek / Anthropic）
- 一个模型名称（例如
gpt-4o-mini、deepseek-chat） - 本地模型的话，确认 Ollama 已经装好，并且能通过
http://localhost:11434访问
千万不要跳过这一步。OpenClaw 启动时会初始化模型客户端，如果模型接口不可用，进程可能不会报错，但你输入任务后它一直不回复，特别容易误判成部署失败。
3. 实操：在 Windows 上一步步跑起 OpenClaw
3.1 在 WSL 里安装基础依赖（Node.js、Git、pnpm）
打开 WSL 终端（通常用 wsl 命令进入 Ubuntu），先把系统包更新一下：
bash复制sudo apt update && sudo apt upgrade -y
然后安装 Git、curl 等基础工具：
bash复制sudo apt install -y git curl build-essential
OpenClaw 对 Node.js 版本有要求，建议安装 Node.js 20 以上的 LTS 版本。直接用 NodeSource 源安装：
bash复制curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
装完检查版本：
bash复制node -v
npm -v
OpenClaw 官方推荐使用 pnpm 作为包管理器，安装方式：
bash复制sudo npm install -g pnpm
这套环境就绪后，你在 WSL 里看到的路径是 Linux 风格，比如 /home/你的用户名/。访问 Windows 上的文件也可以通过 /mnt/c/...，但我不建议直接把项目放在 /mnt/c 下面，因为跨文件系统读写性能很差，也会带来文件权限乱码问题。
3.2 获取 OpenClaw 源码并安装依赖
在 WSL 里进入项目目录：
bash复制cd ~
git clone https://github.com/openclaw/openclaw.git
cd openclaw
如果你拉代码比较慢，可以换成 GitHub 镜像或代理地址，这个自己灵活处理。拉下来后先看分支：默认主分支可能还在开发中，建议切到最新的 release 标签。可以用：
bash复制git tag
git checkout 最新版本号
然后安装依赖：
bash复制pnpm install
这一步耗时会比较长，因为要拉很多 npm 包。装完后最好跑一遍官方自检：
bash复制pnpm check
如果这里报错，多半是 Node.js 版本不对或缺少系统编译工具。遇到和 node-gyp 相关的报错，回到上一节把 build-essential 装好，再试。
3.3 配置环境变量：模型、密钥、通道
OpenClaw 支持多种配置方式，最直观的是在项目根目录创建 .env 文件。以我常用的 DeepSeek + OpenAI 兼容配置为例：
bash复制cp .env.example .env
然后编辑 .env：
dotenv复制OPENAI_API_KEY=你的KEY
OPENAI_BASE_URL=https://api.deepseek.com/v1
OPENAI_MODEL=deepseek-chat
如果你用的是官方 OpenAI，就不需要改 OPENAI_BASE_URL。如果你本机装了 Ollama，可以写成：
dotenv复制OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=llama3
注意：配置文件里不要出现中文引号，也尽量不要用注释里带中文的编辑器改，避免把编码搞坏。我遇到过一次，因为 Windows 记事本的 UTF-8 BOM 问题，导致 OpenClaw 读取配置时多了一个不可见字符，启动报 JSON 解析错误。
OpenClaw 还支持更复杂的 openclaw.json5 配置文件，用于定义工具通道、定时任务、消息平台等。刚上手阶段用 .env 就够，等你清楚每个参数的含义后再逐步扩展。
3.4 启动与验证：从命令行到 Web 控制台
环境变量配好后，启动：
bash复制pnpm start
首次启动会看到一段日志，类似 OpenClaw is running。此时你可以在同一个终端里输入自然语言指令测试，比如：
code复制帮我列出当前目录下的文件
如果模型接口正常，OpenClaw 会调用工具执行，并返回真实结果。这时候说明核心链路已经通了。
OpenClaw 默认还带一个 Web 控制台，启动日志里会打印 http://localhost:3000 这类地址。在 Windows 浏览器里直接访问即可。如果你在 WSL 里跑的服务，Windows 访问 localhost 通常没问题，因为 WSL2 会自动端口转发。如果访问不了，看 4.2 节排查端口问题。
4. 高频报错与排查实录
4.1 “could not safely verify the WSL2 environment”怎么破
这个报错出现的场景很多，通常是 OpenClaw 启动脚本检查 WSL 环境的时候，发现以下一种或多种问题：
- WSL 内核版本过低
- 没有设置默认 WSL 版本为 2
- 当前系统用户名或路径含空格、中文
- 使用了非官方 WSL 发行版
我的排查顺序是：
bash复制wsl --version
wsl --status
wsl --update
确认版本没问题后，再到 WSL 里跑：
bash复制uname -a
如果内核版本是 5.x 的早期版本，最好升级内核。还有一种坑：你在 Windows 上安装了多个 WSL 发行版，OpenClaw 默认调用的不是 Ubuntu。这时需要在 WSL 里执行：
bash复制wsl -s Ubuntu
设置默认发行版。
如果检查完还是报同样错误，很有可能是用脚本从 Windows 侧直接启动 OpenClaw，导致它拿到了 Windows 的 PATH 而不是 WSL 的 PATH。解决办法是：先 wsl 进入 Ubuntu，再在 Ubuntu 内部执行启动命令，不要通过 wsl openclaw 这种形式。
4.2 WSL2 网络 / 端口访问问题：Windows 访问 WSL 服务
源码跑起来后，Windows 浏览器访问 localhost:3000 偶尔会失败。先排查 WSL2 的 IP：
bash复制hostname -I
拿到类似 172.x.x.x 的地址后，在 Windows 浏览器访问 http://172.x.x.x:3000，如果能访问，说明是端口转发问题。WSL2 大多数情况下自动端口转发，但如果你把 OpenClaw 绑定了 127.0.0.1，Windows 这边的 localhost 转发就会失效。
解决方式是在 .env 里把监听地址改为 0.0.0.0：
dotenv复制HOST=0.0.0.0
PORT=3000
然后重启。注意此时服务会暴露到局域网，如果你在公网环境或不信任的网络里，需要加防火墙规则，只允许本机访问。
4.3 中文字符乱码、文件权限与路径问题
在 Windows 上编辑过的 .env 或配置文件，拿到 WSL 里运行，偶尔会遇到换行符或编码问题。用 file 命令看一下：
bash复制file .env
如果显示 with CRLF line terminators，用 sed 转换：
bash复制sed -i 's/\r$//' .env
WSL 和 Windows 文件系统交互时，权限也会“水土不服”。比如项目放在 /mnt/c/Users/xxx/ 下，WSL 里可能无法执行某些脚本。建议把项目整个移到 WSL 内部，例如 ~/openclaw。
另外，如果你的 Windows 用户名是中文，WSL 里的用户主目录可能显示为 //mnt/c/Users/中文，这种情况更容易出现路径解析异常。最省心的方法是直接新建一个纯英文的 WSL 用户来跑。
4.4 模型请求超时或返回异常
OpenClaw 启动正常，但发任务后一直转圈，几率最大的问题是模型接口超时。特别在本地 Ollama 场景下，模型没有提前加载，第一次请求要花几十秒。可以先在 WSL 里单独测试：
bash复制curl http://localhost:11434/v1/models
确认 Ollama 服务正常。如果是远程 API，检查 .env 里的 OPENAI_BASE_URL 是否多加了空格或尾部斜杠。
还有一种隐蔽问题：OpenClaw 默认的模型厂商配置可能带 max_tokens、temperature 等参数，某些开源模型不兼容。这种情况需要回退到官方文档，看模型预设怎么关掉，或者换一个模型名称。
5. 部署之后：OpenClaw 的实用扩展
5.1 对接本地大模型（Ollama / DeepSeek）
OpenClaw 最大的优势是可以“白嫖”本地模型，尤其适合公司内网或对数据敏感的场景。安装 Ollama 后，拉一个支持工具调用的模型，比如 qwen2.5 或 llama3.1，然后在 .env 里指定兼容接口：
dotenv复制OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=qwen2.5:14b
实测下来，14B 左右的模型在 32G 内存的机器上能跑，但推理速度明显比云端 API 慢。如果不是对隐私要求特别高，我建议日常任务用云端模型，敏感任务切到本地模型，OpenClaw 支持按对话上下文切换模型，这是它很实用的点。
5.2 把它变成定时任务 / IM 机器人 / 群聊助手
OpenClaw 不是只能手动对话，它支持通过配置定义定时任务。比如每天早上九点让它拉取天气、汇总待办邮件，写进 cron 表达式。配置文件里类似：
json5复制schedules: [
{
cron: '0 9 * * *',
task: '检查今天的日历安排并发送摘要'
}
]
它还可以接入即时通讯软件，变成群里的 AI 助手。比如在飞书、钉钉或 Discord 群里 @ 它，让它回答问题、记录会议纪要。注意：接入外部平台需要申请对应的机器人 Token，这一步与 OpenClaw 本身无关，跟着平台的开放文档走就行。
5.3 数据备份与安全建议
OpenClaw 的配置和任务记录都存在项目目录下，部署完成后，至少备份以下内容：
.env文件（含密钥）openclaw.json5或配置目录data/或storage/目录下的会话数据
我建议写成一个简单的备份脚本，用 tar 打包到 Windows 侧目录，每天定时执行。安全方面，不要在公网服务器上裸跑 OpenClaw，因为它有本地文件读写和执行命令的能力，如果被外部访问到，风险很高。如果一定要远程访问 Web 控制台，至少套一层反向代理加认证。
5.4 从 Windows 开机自启到 WSL 后台运行
要让 OpenClaw 开机在 WSL 里自动运行，不能用 Windows 启动快捷方式直接跑 .bat，因为 WSL 进程可能没有被正确初始化。我试过比较稳的方式是：
- 在 WSL 里写一个启动脚本
start-openclaw.sh。 - 用
nohup或pm2让它在后台运行。 - 在 Windows 的任务计划程序里加一个“登录时启动”任务，命令是：
powershell复制wsl.exe -d Ubuntu -- /home/用户名/start-openclaw.sh
用 pm2 管理 OpenClaw 的好处是崩溃后会自动重启，还能看日志。安装方式：
bash复制sudo npm install -g pm2
pm2 start pnpm --name openclaw -- start
pm2 save
最后别忘了 pm2 startup systemd 让它在 WSL 启动时自恢复。
我个人在实际操作中体会最深的，是 Windows 下跑 OpenClaw 需要“先稳住环境，再研究功能”。很多新人一上来就急着接模型、接群聊，结果卡在 WSL2 报错上，折腾几个小时就放弃了。其实只要你按部就班，把 WSL2 检查好、项目放在 WSL 内部、模型接口提前测通，OpenClaw 的部署难度并不高。
如果后续你想进一步扩展，还可以研究 OpenClaw 的插件机制：让它读取本地数据库、调用 PowerShell 脚本、控制智能家居设备。把这些工具逐步加进去之后，它就不只是一个命令行玩具，而是真正能替你跑腿的数字助理。这篇先写到这，有问题可以在评论区留言，我看到后会继续更新这个“东方仙盟”系列的实操技巧。