前言
企业办公场景中，将轻量级 AI 框架 OpenClaw 与飞书机器人结合，能快速实现智能交互与流程自动化。但在实际对接中，开发者常因权限配置、环境依赖、回调设置等细节反复试错。本文梳理了 10 个典型踩坑点，每个问题均配套原因分析、排查步骤和实操案例，并补充高效调试技巧，帮助开发者系统性地定位障碍。
一、前置准备
开始前建议确认三点：
- OpenClaw 已正确安装，终端执行
openclaw -v查看版本（建议使用最新版）。 - Node.js 版本不低于 v14，npm 版本不低于 v6，防止依赖过低导致插件安装失败。
- 飞书账号需具备企业开发者权限（个人账号默认具备）。无需提前创建飞书应用，下文将结合案例讲解关键细节。
二、10 个高频踩坑点排查
以下问题按对接流程排序，涵盖应用创建、插件安装、配置、回调、配对全环节。
踩坑点 1：应用类型选择错误
现象：创建飞书应用后，'能力管理'中找不到'机器人'开关。 原因：飞书仅'自定义应用'支持机器人能力，误选'小程序'等类型将无法开启。 解决：删除错误应用，重新创建'自定义应用'（企业内部应用），并在能力管理中开启机器人。
踩坑点 2：App Secret 未保存
现象：输入 App ID 和 App Secret 后提示'凭证验证失败'。 原因：App Secret 仅在首次创建时显示，未及时保存则丢失；或输入包含空格。 解决：点击'重置'获取新 App Secret，立即复制保存（建议加密存储）。在 OpenClaw 中重新输入，避免空格。重置后必须重新发布应用版本，新凭证才能生效。
踩坑点 3：权限配置不全
现象：发送消息无响应，控制台无日志。
原因：未开通'即时通讯'核心权限，或遗漏'通讯录基本信息权限'。
解决：勾选所有即时通讯权限（如 im:message:send）及通讯录权限，保存后重新发布应用。重启 OpenClaw 服务（openclaw restart）后测试。
提醒：飞书权限开通后，必须重新发布应用版本才能生效。
踩坑点 4：插件安装报错
现象：执行 openclaw plugins install @m1heng-clawd/feishu 时报错'spawn npm ENOENT'。
原因：系统环境变量未配置 npm 路径，或 Node.js 未正确安装。
解决：将 Node.js 安装路径添加到系统变量 Path 中，重启终端。若仍不行，进入 OpenClaw 插件目录手动执行 npm install。
踩坑点 5：配置修改未重启
现象：配置完成后，控制台未显示'feishu plugin loaded successfully'。
原因：参数修改后未重启服务，新配置未生效。
解决：执行 openclaw restart 重启服务，观察日志确认插件加载。养成'修改配置→重启服务→验证'的习惯。
踩坑点 6：回调 URL 未公网暴露
现象：配置回调 URL 时提示'验证失败'，或收不到消息。 原因：URL 为本地地址（如 127.0.0.1），未通过内网穿透暴露公网。 解决：利用 ngrok 等工具生成公网 URL，在飞书后台重新配置并验证。确保 OpenClaw 服务运行且穿透工具稳定。
踩坑点 7：回调事件不完整
现象：能接收单聊但无法接收群聊消息。
原因：事件订阅中只添加了部分消息接收事件。
解决：同时添加 im.message.receive_v1（单聊）和 im.message.group_receive_v1（群聊）两个核心事件，保存后重新发布应用。
