前置准备
为避免基础环境问题浪费时间，建议在开始前确认以下三点：
- OpenClaw 已正确安装，终端执行
openclaw -v可查看版本（建议使用最新版，旧版本可能存在插件兼容风险）。 - Node.js 版本不低于 v14，npm 版本不低于 v6，通过
node -v和npm -v验证，防止因依赖版本过低导致插件安装失败。 - 飞书账号需具备企业开发者权限（企业账号需管理员授权，个人账号默认具备）。无需提前创建飞书应用，下文将结合案例同步讲解应用创建的关键细节。
高频踩坑点排查
以下问题按对接流程排序，涵盖应用创建、插件安装、配置、回调、配对全环节。每个问题均标注现象、原因、排查步骤及解决方案。
踩坑点 1：应用类型选择错误
现象：创建飞书应用后，在'能力管理'中找不到'机器人'开关。 原因：飞书仅'自定义应用'类型支持机器人能力，若误选'小程序''H5 应用'等类型，将无法开启机器人。 解决：删除错误应用，重新创建'自定义应用'（企业内部应用）。创建后即可在能力管理中开启机器人。
踩坑点 2：App Secret 未保存或泄露
现象：在 OpenClaw 配置中输入 App ID 和 App Secret 后，提示'凭证验证失败'。 原因：App Secret 仅在首次创建或重置时显示，未及时保存则丢失；输入时包含空格或特殊符号。 解决：点击'重置'获取新 App Secret，立即复制保存（建议加密存储）。在 OpenClaw 中重新输入，避免空格。重置后必须重新发布应用版本，新凭证才能生效。
踩坑点 3：权限配置不全
现象：飞书发送消息给机器人，无任何响应，OpenClaw 控制台无日志。
原因：未开通'即时通讯'核心权限，或遗漏'通讯录基本信息权限'，导致飞书无法将消息推送到 OpenClaw。
解决：勾选所有即时通讯权限（如 im:message:send、im:message:read 等）及通讯录权限，保存后重新发布应用。重启 OpenClaw 服务（openclaw restart）后测试。
踩坑点 4：插件安装失败
现象：执行 openclaw plugins install @m1heng-clawd/feishu 时报错，提示无法找到 npm。
原因：系统环境变量未配置 npm 路径，或 Node.js 未正确安装。
解决：
- 方法一：将 Node.js 安装路径添加到系统变量 Path 中，重启终端。
- 方法二：进入 OpenClaw 插件目录，手动执行
npm install并复制插件文件。
踩坑点 5：配置修改后未重启服务
现象：完成配置后，控制台未显示'feishu plugin loaded successfully'。
原因：配置参数修改后，未重启 OpenClaw 服务，新配置未生效。
解决：执行 openclaw restart 重启服务，观察日志确认插件加载。
踩坑点 6：回调 URL 未公网暴露
现象：在飞书后台配置回调 URL 后，保存时提示'验证失败'，或机器人收不到消息。 ：回调 URL 为本地地址，未通过内网穿透暴露公网，或端口未开放。 ：利用 ngrok、花生壳等工具生成公网 URL，在飞书后台重新配置并验证。确保 OpenClaw 服务运行且穿透工具稳定。
