小龙虾openclaw避坑指南

安装失败、飞书不响应、模型不工作——这是我装了三次之后才总结出来的12个坑

今年春天，AI圈被一只“小龙虾”刷屏了。

不是夜市大排档那个，是OpenClaw——那个能自己操作电脑、帮你办公的开源AI智能体。说实话，两个月前我根本没听说过这玩意儿，结果现在装都装不上。

朋友圈天天有人晒“我的小龙虾又帮我写报告了”，看得我心痒痒。跟风装了一把，结果三天都没搞定——安装卡住、飞书不回消息、模型罢工，简直离谱。

后来在社区里泡久了发现，不止我一个人这样。问了多个踩坑老哥，终于把这12个最常见的坑理清楚了。

如果你也准备装小龙虾，看完这篇能省掉至少三天弯路。

安装就卡住？先看这3个

坑1：Node.js版本不对

表现：打开终端输入openclaw，显示命令无效或者报版本错误。

原因：OpenClaw v3.28+需要Node.js 22以上，但很多电脑装的是16甚至14的老版本。我自己的Mac就是一开始装的v18，踩了个结结实实。

怎么查：

node -v

显示v20或者更低的话，就需要升级。

怎么解决：

# Windows用wingetwinget install OpenJS.NodeJS.LTS# Mac用brewbrew upgrade node@22# 验证一下，必须是v22开头才行node -v

坑2：网络超时，依赖下不动

表现：安装到一半卡住，显示“downloading dependencies”，等半天最后报timeout。

原因：npm默认的源在国内访问太慢了，之前有一次我从下午三点装到晚上吃饭都没装好。

最快的解决办法：

# 换成国内镜像npm config set registry https://registry.npmmirror.com# 清除缓存重装npm cache clean --forcenpm install -g openclaw@latest

坑3：权限不够

表现：安装时报“EACCES permission denied”，权限被拒绝。

这个问题在Mac和Linux上比较常见。解决思路是给npm换个安装目录，不跟系统目录较劲：

# 创建专属目录mkdir -p ~/.openclaw-global# 设置npm的家npm config set prefix ~/.openclaw-global# 把这个路径加到环境变量，然后重装

模型配置的两个大坑

坑4：API密钥无效

表现：模型完全不理你，或者账单突然暴涨。

常见原因就两个：一是复制密钥的时候手抖多加了空格，二是密钥泄露被人用了。

需要注意的点：

• 粘贴到配置文件之前，先在记事本里检查一遍，确保没有多余空格

• 怀疑泄露立刻去控制台停用，换新的

• 免费额度用完会自动停用，别等到扣费了才反应

正确的配置位置（Windows）：

C:\Users\你的用户名\.openclaw\models.json

{  "openai": {    "apiKey": "sk-xxxx...",     "baseURL": "https://api.openai.com/v1"  }}

坑5：改了配置模型没反应

表现：明明在配置文件里改了模型，AI还是用原来的那个。

很多人以为是配置文件没生效，其实是需要重启gateway：

openclaw config set agents.defaults.model.primary "gpt-4o"# 切记必须重启！openclaw gateway restart

配置文件改完要是不重启，模型是不会变的。

飞书集成的四个无响应

坑6：账号配置位置错了（2026年新坑）

这是最近两个月新踩的最多的坑——飞书消息能发出去，但机器人就是不带回复的。

问题在于配置格式已经改了，很多人还在用老写法：

❌ 错误写法（旧的）：

{  "appId": "xxx",  "appSecret": "xxx"}

{  "channels": {    "feishu": {      "enabled": true,      "accounts": [        {          "id": "default",          "appId": "xxx",          "appSecret": "xxx"        }      ]    }  }}

坑7：长连接模式没开

飞书消息能收到但已读不回？大概率是这里没配置好。

检查步骤：

1. 登录飞书开放平台

2. 点进应用 → 事件订阅

3. 长连接接收事件（WebSocket）这个选项必须打勾

4. 添加事件 im.message.receive_v1

这个选项默认是关掉的，很多人装完了才发现机器人不会说话。

坑8：bindings没写channel

消息能进到系统里，但是AI不处理——binding配置里缺少channel字段。

检查你的配置：

- description: "处理飞书消息"  channel: "feishu"  # 这行必须有！  matches: ".*"  handler: "agent:main"

没有channel: "feishu"这行，飞书消息就会被当成陌生数据直接丢掉。

坑9：飞书插件版本太老

日志里出现“bot open_id recovered via background retry”这类提示，就是插件版本不兼容。

更新命令：

npx -y @larksuite/openclaw-lark@2026.3.29 update

技能插件的两个失效坑

坑10：技能显示missing

安装完成，但是显示missing状态。

先运行：

openclaw skills info 技能名

常见原因是缺少对应的API密钥，或者skill文件路径不对。添加完密钥记得重启。

坑11：自定义skill不触发

自己写的skill怎么都调不出来。

检查三点：

1. 目录名只允许小写字母、数字、连字符

2. SKILL.md必须有YAML frontmatter

3. description字段里要包含触发关键词

最后一个：并发过高

坑12：同时跑太多直接挂

用着用着突然卡死，或者疯狂报错——通常是并发数超了。

在配置里加限制：

{  "limits": {    "maxConcurrent": 2,    "rateLimit": "10/分钟"  }}

免费模型建议开2，付费的可以开4，再多就可能崩。

遇到问题怎么办？

按这个顺序查：

# 1. 自动诊断openclaw doctor --fix# 2. 看实时日志openclaw logs --follow# 3. 飞书专用openclaw logs --channel feishu --follow# 4. 测试模型openclaw models ping# 5. 完整状态openclaw status --all

前两个命令能解决80%的问题。

你是哪种人？

几句掏心话

小龙虾这波火起来，确实让很多人第一次体验到了什么叫“有个AI帮我干活”。但新技术嘛，门槛多少是有的。

踩坑不可怕，可怕的是同一个坑绊倒三次。

记住三点：

1. 版本对：Node.js 22 + OpenClaw v3.28

2. 改前备份：配置文件改之前先复制一份

3. 看日志：出问题别猜，日志里什么都写着

技术会变，但解决问题的思路不会过时。下次遇到新坑，至少你知道去哪找答案了。

祝部署顺利，小龙虾早日上岗给你干活！

有问题评论区见，能帮的都会回。

🌟【AI学习大礼包限时放送】🌟

为帮助大家轻松打开AI新世界的大门🚀，我专门打包了清华内部关于AI人工智能的7本硬核指南！完整版PDF已准备好，已经放在下面的公众号中了！

🎁【3秒极速领取通道】🎁1️⃣ 关注公众号【盼哥聊Ai】解锁宝藏库2️⃣ 后台对话框输入【nb】立即解锁NotebookLM生成PPT风格提示词

这可能是你今年最值的3秒钟投资💎有任何学习疑问随时留言，盼哥一直在哦~💌