大家好，我最近想在 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

  git config --global url."git@github.com:".insteadOf "https://github.com/"

  成功绕过 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

primary: 'qianfan/qianfan-code-latest'

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

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

---

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

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

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

解决
移除社区版插件：

bash

openclaw plugins uninstall @openclaw/feishu   # 不行就直接删目录
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，欢迎留言交流！