1. 为什么 Windows 装 OpenClaw 一定要先上 WSL
OpenClaw 是一个跑在命令行里的 AI 智能体框架，能接大模型、能挂技能（skills）、能连飞书这类即时通讯工具，让你在聊天窗口里直接指挥它干活。它本身是跨平台的，但官方文档里对 Windows 用户有一句很直白的话：建议用 WSL2 + Ubuntu。我一开始不信邪，直接在 Windows 原生环境里装，结果就是各种莫名其妙的报错，折腾了大半天才回头老老实实装 WSL。
核心原因在于 OpenClaw 的很多技能和二进制依赖是按 Linux 环境编译和调用的。Windows 原生跑 Node 环境时，路径分隔符、文件权限、进程管理这几块和 Linux 差异很大，技能加载经常失败，后台服务也不好做成守护进程。WSL2 给你的是一个完整的 Linux 内核，跑起来和真机 Ubuntu 几乎没区别，性能也够用，还能把 OpenClaw 注册成 systemd 服务，开机自启、一键重启都很省心。
这篇教程面向的是零基础用户，我会把安装前检查、WSL 配置、OpenClaw 安装、模型配置、飞书接入、报错排查整条链路走一遍。你只要跟着敲命令，大概率能一次跑通。适合谁？适合想在 Windows 上玩 AI 智能体、又不想折腾双系统或者买云服务器的朋友。整个过程不需要额外硬件，一台能跑 Win10/11 的电脑就行。
先说安装前的检查清单，这几项确认了能省掉后面一半的坑：
第一，确认你的 Windows 版本。WSL2 需要 Win10 版本 2004 及以上（内部版本 19041+）或者 Win11。在 PowerShell 里输入winver就能看到版本号。
第二，确认虚拟化已开启。WSL2 依赖 Hyper-V 的虚拟化能力，任务管理器 → 性能 → CPU，看右下角「虚拟化」是不是「已启用」。如果是禁用状态，需要进 BIOS 打开 VT-x / AMD-V。
第三，磁盘空间留够。Ubuntu 系统加 OpenClaw 依赖，建议至少留 20GB 空闲。
第四，网络能正常访问外网，因为安装脚本要拉 Node.js 和 npm 包。
这几项检查完，我们就可以进入正式安装了。下面每一步我都会给出完整命令和预期结果，你对照着看就行。
2. WSL2 与 Ubuntu 环境的一键配置实操
这一章是整篇的地基，WSL 没配好，后面 OpenClaw 装上去也是各种报错。我踩过的坑基本都集中在这里，所以写得细一点。
2.1 一键安装 WSL2 和 Ubuntu
以管理员身份打开 PowerShell（开始菜单搜 PowerShell，右键「以管理员身份运行」），执行：
# 一键安装 WSL2 和默认 Ubuntu 发行版 wsl --install这条命令会自动开启所需的 Windows 功能、下载 WSL2 内核、安装默认的 Ubuntu。执行完会提示你重启电脑。重启后系统会自动弹出一个 Ubuntu 窗口，让你创建默认用户。用户名自己定，比如diary，然后设置密码（输入时屏幕不显示是正常的）。
如果你想指定更稳定的 Ubuntu 24.04 LTS，可以先看有哪些可选：
# 列出可在线安装的发行版 wsl --list --online # 指定安装 Ubuntu 24.04 wsl --install -d Ubuntu-24.04装完之后，用管理员 PowerShell 进入 Ubuntu：
wsl -d Ubuntu第一次进去先更新系统、装好 curl 和 git，后面安装脚本要用：
# 更新已安装的软件包 sudo apt update && sudo apt upgrade -y # 安装 curl 和 git sudo apt install curl git -y2.2 开启 systemd，让 OpenClaw 能当服务跑
WSL 默认不启用 systemd，而 OpenClaw 的守护进程模式依赖它。先检查是否已经开启：
sudo less /etc/wsl.conf如果输出里有systemd=true，说明已经配好了，直接跳到下一节。如果没有，执行下面这段写入配置（按 Esc 然后输入:q退出 less）：
sudo tee /etc/wsl.conf > /dev/null <<'EOF' [boot] systemd=true EOF然后在 Windows PowerShell 里彻底重启 WSL：
wsl --shutdown重新进入并验证：
wsl -d Ubuntu systemctl --user status能看到正常的服务状态输出，就说明 systemd 已经生效。这一步很关键，不然后面openclaw onboard --install-daemon会失败。
2.3 安装 OpenClaw 本体
以管理员身份运行 WSL 终端，切换到你的用户目录（比如/home/diary），执行官方一键安装脚本：
curl -fsSL https://openclaw.ai/install.sh | bash这个脚本会做三件事：自动检测并安装 Node.js 22+、全局安装openclaw@latest、启动 onboarding 向导。跟着提示一路选 Yes，看到安装完成的提示即可。
接着进入新手向导，并把 OpenClaw 注册为系统服务：
openclaw onboard --install-daemon向导里会依次问你：是否知晓使用风险（方向键选 Yes 回车）、选择 QuickStart 模式、选择 AI 大模型、连接即时通讯平台、联网配置、skill 和 hooks 配置。这里除了模型那一步，其他都可以先选Skip for now，后面单独配。模型这一步如果你暂时没有 API Key，也可以先跳过，我们下一章专门讲怎么接。
向导跑完，会给你一个 Dashboard URL，复制到浏览器打开，能看到 OpenClaw 的 Web 界面就说明主体装好了。
3. 模型与飞书接入的可复制配置片段
OpenClaw 装好只是空壳，得给它接上大脑（大模型）和嘴巴（飞书），它才能真正干活。这一章给出可直接复制的配置片段。
3.1 配置 AI 模型
重新进入向导配置模型：
wsl -d Ubuntu openclaw onboard在模型选择界面，以千问的免费模型为例，有两个常用选项：
| 模型 ID | 适用场景 |
|---|---|
| qwen-portal/coder-model | 日常文本问答、代码辅助、通用助手 |
| qwen-portal/vision-model | 图像识别能力 |
选中后输入对应的 API Key。如果你用的是其他厂商的模型，OpenClaw 也支持自定义 Base URL 和 Model ID，配置结构大致如下（以本地配置文件为例）：
{ "models": { "default": { "provider": "openai-compatible", "baseUrl": "https://taotoken.net/api", "apiKey": "你的API_KEY", "modelId": "你的模型ID" } } }注意：Base URL、API Key、Model ID 这三件套必须同时正确，缺一个都会在请求时报错。如果你用的是兼容 OpenAI 协议的服务，把 baseUrl 指向对应地址即可。
配置完模型，先别急着接飞书，在 Web 界面里发一句话测试，能正常回复说明模型通了。
3.2 飞书机器人接入参数
飞书接入分两边：飞书开放平台建应用，OpenClaw 这边配渠道。
先在飞书开放平台（open.feishu.cn）进入开发者后台，创建「企业自建应用」，然后：
第一步，添加机器人能力。在应用功能里找到「机器人」，启用它。
第二步，配权限。左侧「权限管理」，在开通权限的搜索框输入im:，把出现的权限全部勾选，点「批量开通」。
第三步，拿凭证。进入「凭证和基础信息」，记下App ID和App Secret，这两个是 OpenClaw 要填的参数。
第四步，创建版本并发布。进入「版本管理和发布」→「创建版本」，填版本信息保存，然后发布。
回到 OpenClaw 这边配置渠道：
openclaw config选择local（本地配置），然后选Channels→Link添加新渠道，渠道类型选飞书。把刚才的 App ID 和 App Secret 填进去，一路到 finish。
接着配置私聊访问策略，新手可以先选 No 跳过。然后回到飞书开发者后台，把订阅方式配成「长连接」，并添加「接收事件」。再发布一个新版本让配置生效。
最后重启 OpenClaw 服务：
openclaw daemon stop openclaw daemon start到飞书客户端给机器人发任意消息，能看到回复就说明通了。如果它让你执行一条配对指令，把那条指令复制到 WSL 窗口执行即可完成配对。
4. 验证请求与成功结果对照
配置完最怕的就是「看起来好了其实没通」。这一章给你一套逐步验证动作，每一步都有明确的成功标志。
第一步，验证 OpenClaw 服务状态：
openclaw status openclaw gateway status openclaw healthopenclaw status能看到整体运行状态，gateway status显示 Gateway 在跑，health返回健康检查通过。三个都正常，说明服务层没问题。
第二步，验证模型请求。在 Web Dashboard 里发一句「你好，介绍一下你自己」，如果几秒内返回一段合理的文本，说明模型链路通了。如果卡住或者报错，看下一章的排查。
第三步，验证飞书长连接。在飞书里给机器人发消息，观察 WSL 里的日志：
openclaw daemon logs日志里能看到收到事件、调用模型、返回响应的完整链路。如果飞书没反应，先看日志有没有收到事件，没有就是飞书那边的订阅配置没生效。
第四步，验证配对。如果机器人回复了一条配对指令，把它复制到 WSL 执行，然后再发消息，这次应该能正常对话。
成功的结果长这样：你在飞书里发「帮我写个 Python 快速排序」，几秒后机器人返回一段带代码的回复。到这一步，整条链路就打通了。
提示：验证顺序建议严格按「服务 → 模型 → 飞书」来，不要跳步。跳步的话出问题很难定位是哪一层。
5. 常见报错逐条排查
这一章按真实报错来，你遇到哪个对哪个。
报错一：npm error code 3221225477或npm error code 128
这是 Windows 原生环境装 OpenClaw 最典型的报错，本质是 Node 在 Windows 下的兼容性问题。解决方案就是本文的核心思路：先装 WSL2，在 Ubuntu 里装。如果你已经在 WSL 里还报这个，检查是不是在 Windows 的 PowerShell 里跑的安装命令，切到wsl -d Ubuntu里再跑。
报错二：401 Unauthorized
模型请求返回 401，说明 API Key 不对或者没带上。检查三件套：Base URL 是否指向正确的 API 地址、API Key 是否复制完整（前后别带空格）、Model ID 是否是服务商支持的模型名。改完配置后记得openclaw daemon restart。
报错三：local proxy failed
本地代理失败，通常是网络层的问题。检查 WSL 的网络模式，确认能正常访问外网。可以在 WSL 里curl -I https://taotoken.net/api看能不能通。如果 WSL 网络异常，wsl --shutdown重启一次往往能解决。
报错四：reading choices相关错误
这个报错一般出现在解析模型返回时，说明返回结构不符合预期。常见原因是 Base URL 指向了一个不兼容 OpenAI 协议的端点，或者 Model ID 填错了导致返回了错误结构。换成兼容 OpenAI 协议的地址，并确认 Model ID 正确。
报错五：飞书 OAuth 或事件订阅失败
飞书这边如果报 OAuth 相关错误，检查 App ID 和 App Secret 是否填对，以及应用是否已经发布版本。事件订阅失败，重点看订阅方式是不是「长连接」，以及「接收事件」有没有添加。改完飞书配置后，一定要重新发布版本，否则不生效。
报错六：openclaw daemon启动失败
多半是 systemd 没开。回到第 2.2 节检查/etc/wsl.conf里有没有systemd=true，改完wsl --shutdown重启。
排查通用思路：先看openclaw daemon logs的日志，日志里通常有具体的错误堆栈，比界面上的提示详细得多。定位到是哪一层（服务/模型/飞书）再针对性处理。
6. 长期跑 Agent 的配置建议与入口
OpenClaw 跑通之后，如果你打算长期用它做编码辅助或者挂 Agent 任务，有几个配置建议。
第一，把 OpenClaw 注册成 systemd 服务后，设置开机自启，这样每次开机不用手动拉。第二，模型这块如果调用量大，建议用支持 Coding Plan 的服务，成本更可控，适合长期编码和 Agent 场景。第三，飞书渠道配好后，可以再挂其他渠道，OpenClaw 支持多渠道并行。
如果你在配置模型时需要申请 API Key，可以走这个入口：
- 模型对话体验：https://taotoken.net/api?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=model_chat
- Coding Plan（长期编码/Agent 推荐）：https://taotoken.net/api?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=coding_plan
- 控制台：https://taotoken.net/api?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=console
- API Keys 管理：https://taotoken.net/api?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=api_keys
- 接入文档：https://taotoken.net/api?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=doc
常用命令再贴一遍，方便你日常维护：
openclaw status # 查看整体状态 openclaw gateway status # 查看 Gateway 运行状态 openclaw health # 健康检查 openclaw configure # 重新配置模型、频道等 openclaw daemon restart # 重启后台服务 openclaw daemon logs # 查看运行日志 openclaw onboard # 重新运行向导最后说个实用技巧：OpenClaw 的配置文件改完后，养成openclaw daemon restart的习惯，很多「改了没生效」的问题都是忘了重启。日志是你最好的朋友，出问题先看openclaw daemon logs，比瞎猜快得多。
