Windows 下通过 WSL 安装 OpenClaw，并接入飞书机器人的完整踩坑记录

大家好，我是G探险者！

龙虾热过去一段时间了，我今天在我的老古董电脑上，开始折腾。

以下操作全程均是codex的cli完成的，包括以下的经验总结也是codex整理的。

1. 背景

我的目标是：

• 在 Windows 电脑上安装 OpenClaw
• 使用 Qwen / 阿里云百炼 作为模型
• 接入 飞书机器人
• 实现通过飞书和 OpenClaw 正常对话

最终方案不是在 Windows 原生环境里跑，而是采用：

• Windows + WSL2 + Ubuntu + OpenClaw

这是因为 OpenClaw 在 Windows 上虽然也能装，但实际稳定性上，WSL2 更合适。

2. 什么是 WSL

WSL 全称是：

• Windows Subsystem for Linux

它的作用是：

• 在 Windows 里运行一个 Linux 环境
• 可以装 Ubuntu、Debian 等发行版
• 可以直接访问 Windows 文件系统

比如：

• Windows 的 C:\Users\Lenovo\Desktop
• 在 WSL 里对应 /mnt/c/Users/Lenovo/Desktop

所以：

• OpenClaw 运行在 Ubuntu 里
• 但仍然可以访问 Windows 文件

这一点很重要。

3. 为什么用 WSL 安装 OpenClaw

原因主要有三个：

1. OpenClaw 官方对 Linux / WSL2 支持更稳
2. Node、npm、依赖工具链在 Ubuntu 里更容易处理
3. 方便后续接 AI 工具、命令行、网关服务

但也要注意：

• OpenClaw 在 WSL 里运行时，默认更擅长处理"文件"
• 如果你想操作 Windows 进程，比如关闭 Chrome，需要额外通过 powershell.exe、taskkill.exe 之类桥接

4. Windows 上安装 WSL2

先在管理员 PowerShell 执行：

wsl --install

执行完成后重启电脑。

然后确认 Ubuntu 是否已经安装好：

wsl -l -v

如果看到类似：

  NAME      STATE           VERSION
* Ubuntu    Running         2

说明：

• Ubuntu 已装好
• 而且是 WSL2

这里必须是 VERSION 2。如果是 1，OpenClaw 和 npm 相关能力会出问题。

5. 打开 Ubuntu

可以用两种方式：

1. 开始菜单搜索 Ubuntu
2. PowerShell 执行：

wsl -d Ubuntu

第一次打开 Ubuntu 会要求你设置：

• Linux 用户名
• Linux 密码

6. 安装 Node.js 和 npm

在 Ubuntu 里执行：

sudo apt update
sudo apt install -y curl ca-certificates gnupg
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs

验证：

node -v
npm -v

这里踩过一个坑：

• 早期如果 Ubuntu 实际运行在 WSL1
• npm -v 会直接报：
  • WSL 1 is not supported

所以再次强调：

• 一定要确认是 WSL2

7. 安装 OpenClaw

最开始尝试直接装最新版时，遇到过问题版本。

7.1 错误包名

一开始误用了：

npm install -g @openclaw/cli

这是错的。

正确包名是：

npm install -g openclaw@latest

7.2 全局安装权限问题

普通用户直接执行会报：

• EACCES: permission denied, mkdir '/usr/lib/node_modules/openclaw'

解决方式：

sudo npm install -g openclaw@latest

7.3 最新版包缺依赖

装 latest 后，openclaw --version 能跑，但 openclaw doctor 报错：

• Cannot find module '@buape/carbon'

最后回退到稳定版本：

sudo npm uninstall -g openclaw
sudo npm cache clean --force
sudo npm install -g openclaw@2026.4.2

验证：

openclaw --version
openclaw doctor

8. 初始化 OpenClaw

执行：

openclaw doctor --fix
openclaw config set gateway.mode local
openclaw doctor

这样会完成：

• 基础目录初始化
• gateway 配置
• session 存储目录创建
• shell completion 安装

9. 接入 Qwen / 阿里云百炼

9.1 API Key 获取位置

Qwen 的 API Key 不是在 OpenClaw 里生成，而是在阿里云百炼控制台生成。

正确入口类似：

• 阿里云百炼 / Model Studio / DashScope 的 API Key 页面

拿到的 key 类似：

• sk-xxxx

9.2 最大坑：OpenClaw 2026.4.2 的内置 modelstudio provider 兼容问题

今天最折腾的地方就在这。

现象是：

• 直接配置 qwen / modelstudio provider 后
• OpenClaw 在飞书里回复时会报：

HTTP 401: invalid access token or token expired

但奇怪的是：

• 这把百炼 key 用 curl 直接请求阿里云兼容接口时是正常的
• /models 能列模型
• /chat/completions 也能正常返回回答

也就是说：

• key 本身没问题
• 问题在 OpenClaw 这版对内置 provider 的兼容实现

9.3 最终解决方案：改用阿里云百炼 OpenAI 兼容接口

这是今天真正打通的关键。

最终改成：

• 自定义 provider
• Base URL：
  • https://dashscope.aliyuncs.com/compatible-mode/v1
• Model：
  • qwen3.5-plus

也就是说，不再依赖 OpenClaw 自带的 modelstudio provider，而是把百炼当成一个 OpenAI 兼容模型服务来接。

最终默认模型变成：

• custom-dashscope-aliyuncs-com/qwen3.5-plus

这个方式是最终稳定跑通飞书回复的关键修复。

10. 接入飞书机器人

10.1 飞书应用创建

在飞书开放平台创建企业自建应用。

拿到两项：

• App ID
• App Secret

10.2 OpenClaw 侧配置

把 Feishu 渠道写进 OpenClaw 配置，关键字段包括：

• enabled = true
• connectionMode = websocket
• domain = feishu
• dmPolicy = pairing

并填入：

• appId
• appSecret

10.3 飞书后台必须配置的内容

机器人能力

需要开启：

• 机器人

事件订阅

在 事件与回调 中：

• 订阅方式选 使用长连接接收事件
• 添加事件：
  • im.message.receive_v1

权限管理

这里踩坑最多。

最开始机器人能连上，但不回复。最后看飞书日志才定位到，缺的是权限。

实际需要重点关注：

• im:message:send_as_bot
• im:message
• im:message:readonly
• im:message.p2p_msg:readonly
• im:message.group_at_msg:readonly
• contact:contact.base:readonly

飞书日志里会很明确地报：

• 缺联系人权限
• 缺发送消息权限

所以排查飞书问题时，一定要看飞书开放平台日志搜索里的真实报错，不要只看页面状态。

11. 飞书打不通时遇到的几个坑

11.1 机器人不回复，不一定是 OpenClaw 没收到消息

有一段时间实际情况是：

• 飞书事件已经推给 OpenClaw 了
• OpenClaw 日志里能看到：
  • received message
• 但因为权限不够，拿不到联系人信息，或者没法发消息
• 所以用户侧看起来就是"机器人没回复"

11.2 pairing 模式会拦住首次私聊

当前 dmPolicy = pairing

这意味着：

• 第一次私聊不会立刻放行
• OpenClaw 会生成一个 pairing request
• 需要手工审批

如果飞书权限当时不完整，配对码回复会失败，于是就会卡住。

后来通过命令查看到待审批请求：

openclaw pairing list feishu

然后批准：

openclaw pairing approve feishu <code>

批准后才真正打通。

11.3 有时飞书后台显示"调用成功"，但机器人仍不回复

这种情况今天也遇到了。

最终定位后发现原因不是只有一个，而是可能叠加：

• pairing 未审批
• 飞书权限未完整生效
• 模型调用失败
• OpenClaw provider 兼容问题
• 临时 DNS 问题

所以必须结合：

• 飞书开放平台日志
• OpenClaw channels logs
• OpenClaw pairing list

一起看。

12. 最终打通链路

最后真正稳定工作时，链路是：

1. 用户在飞书里私聊机器人
2. 飞书通过长连接把消息投递给 OpenClaw
3. OpenClaw 网关收到消息
4. OpenClaw 调用阿里云百炼 OpenAI 兼容接口
5. Qwen 返回结果
6. OpenClaw 再把结果发回飞书

最终现象就是：

• 飞书里机器人可以正常回复

13. 为什么 OpenClaw 能改 Windows 文件，但不擅长直接控制 Windows 进程

这是 WSL 架构决定的。

可以直接处理 Windows 文件

因为 WSL 挂载了 Windows 磁盘：

• C:\ -> /mnt/c/
• D:\ -> /mnt/d/
• E:\ -> /mnt/e/

所以 OpenClaw 运行在 Ubuntu 里，仍然可以读写 Windows 文件。

但不能像原生 Windows 程序那样直接控制进程

比如关闭 Chrome，这不是文件操作，而是操作 Windows 进程。

WSL 下如果要做这种事，要通过桥接命令，例如：

powershell.exe -Command "Stop-Process -Name chrome -Force"

或者：

taskkill.exe /IM chrome.exe /F

所以：

• 文件操作：天然支持
• Windows 进程操作：需要额外桥接

14. 最终结论

如果你想在 Windows 上长期稳定使用 OpenClaw，并接入飞书，建议采用：

• Windows + WSL2 + Ubuntu + OpenClaw

并注意下面几个关键点：

1. 必须确认 Ubuntu 运行在 WSL2
2. OpenClaw 不要盲目追 latest，有问题时要回退稳定版本
3. Qwen / 阿里云百炼在这次环境里，内置 modelstudio provider 存在兼容坑
4. 最终稳定方案是改用：
   • 阿里云百炼 OpenAI 兼容接口
5. 飞书接入时，真正的排障重点是：
   • 事件与回调
   • 权限管理
   • pairing
   • OpenClaw channels logs
   • 飞书后台日志

15. 建议的后续优化

后续还可以继续做这些优化：

• 把 OpenClaw 的 workspace 指到常用 Windows 目录
• 调整 timeoutSeconds
• 切换到更快的 Qwen 模型
• 配置系统命令桥接，让机器人能间接操作 Windows 进程
• 旋转已经暴露过的：
  • 阿里云百炼 API Key
  • 飞书 App Secret