大家好，我最近想在 Windows 的 WSL（Ubuntu）里从源码编译安装 OpenClaw，本以为一切顺利，结果一路踩坑不断。好在最后都爬出来了，今天就把这段“血泪史”整理成一篇通俗易懂的文案，希望能帮到和我一样在 WSL 里折腾 OpenClaw 的朋友。

第 1 关：pnpm build 一上来就罢工

现象

执行 pnpm build，报错 canvas:a2ui:bundle 失败，退出码 254。

原因

前端构建（A2UI）需要的依赖没装全，或者系统缺少编译工具。

解决

确认 Node.js 版本 ≥ 22（用 nvm install 22）。

安装系统编译依赖：sudo apt install build-essential python3。

升级 pnpm 到最新版，然后删除 node_modules 重新 pnpm install。

教训

源码编译前，一定要先检查环境和依赖，别硬来。

第 2 关：Git 突然抽风，TLS 连接被重置

现象

pnpm install 时 Git 报错 GnuTLS recv error (-110)，无法 clone 一个依赖仓库。

原因

Git 的 TLS 库（GnuTLS）与 GitHub 服务器通信时不稳定，常见于网络波动或 Git 版本问题。

解决

试了好几种方法——

git config –global http.postBuffer 1048576000 增加缓冲区（没用）。

git config –global http.sslVerify false 临时关闭验证（没用）。

最终用 SSH 协议替代 HTTPS：

bash

成功绕过 TLS 问题。

教训

Git 连接问题可以试试切换协议，SSH 往往更稳。

第 3 关：pnpm link –global 找不到全局目录

现象

执行 pnpm link –global，报错 ERR_PNPM_NO_GLOBAL_BIN_DIR。

原因

pnpm 刚装好，还没初始化全局环境。

解决

直接运行 pnpm setup，它会自动配置环境变量和全局 bin 目录，然后 source ~/.bashrc 生效。

教训

新工具先跑一遍 setup，能省很多麻烦。

第 4 关：配置向导里模型报错“Unknown model”

现象

配置向导完成后，对话时提示 Unknown model: baiduqianfancodingplan/qianfan-code-latest。

原因

我在向导里选了百度千帆，但模型 ID 写错了，或者没配置好 provider。

解决

修改为正确的模型名称：

bash

百度千帆官方文档有错，这个坑也被我踩了。

教训

刚上手最好先用通用费模型，减少变量。

第 5 关：飞书插件冲突，两个 feishu 打架

现象

运行 openclaw plugins list，看到两个 feishu 插件，一个官方（loaded），一个社区（disabled）。

原因

之前可能装过社区版，导致插件 ID 重复。

解决

移除社区版插件：

bash

不行就直接删目录 rm -rf /root/.openclaw/extensions/feishu

然后重启网关，冲突消失。

教训

插件别乱装，装前先 list 看看。

第 6 关：安装百度搜索技能，遭遇“限流”和“旧格式”

现象

用 clawhub install baidu-search 时报 Rate limit exceeded；后来用 openclaw plugins install 又报 package.json missing openclaw.extensions。

原因

限流是因为短时间内请求太多，ClawHub 服务端限制了频率。

“旧格式”是因为插件版本太老，缺少新 OpenClaw 必需的 openclaw.extensions 字段。

解决

先登录 ClawHub：clawhub login（授权 GitHub）。

用 npx clawhub@latest 确保使用最新客户端。

换用官方推荐的技能，比如 tavily-search（联网搜索）、file-organizer 等。

教训

安装第三方技能前，先查查文档，看看是不是兼容新版 OpenClaw。

🎉 最后总结

现在，OpenClaw 已经在普通用户下安稳运行，飞书机器人也能正常对话了。回顾整个过程，最大的感悟是：

环境要干净：WSL 里跑 systemd 需要额外配置，最好用普通用户。

工具要熟悉：pnpm、Git、systemd 的坑提前了解能省很多时间。

文档要多看：OpenClaw 官方文档其实写得很详细，只是我一开始没耐心读。

希望我的踩坑经历能帮你少走弯路。如果你也在 WSL 里折腾 OpenClaw，欢迎留言交流！