前置准备（快速自查）
为避免基础环境问题浪费时间，建议在开始前确认以下三点：
- OpenClaw 已正确安装，终端执行
openclaw -v可查看版本（建议使用最新版，旧版本可能存在插件兼容风险）。 - Node.js 版本不低于 v14，npm 版本不低于 v6，通过
node -v和npm -v验证，防止因依赖版本过低导致插件安装失败。 - 飞书账号需具备企业开发者权限（企业账号需管理员授权，个人账号默认具备）。无需提前创建飞书应用，下文将结合案例同步讲解应用创建的关键细节。
10 个高频踩坑点排查（附实操案例）
以下问题按对接流程排序，涵盖应用创建、插件安装、配置、回调、配对全环节。每个问题均标注现象、原因、排查步骤及解决方案，可直接对照自身情况定位。
踩坑点 1：应用类型选择错误，导致机器人能力不可用
现象：创建飞书应用后，在'能力管理'中找不到'机器人'开关。 原因：飞书仅'自定义应用'类型支持机器人能力，若误选'小程序''H5 应用'等类型，将无法开启机器人。 排查：进入飞书开发者后台，在应用详情→基本信息中查看'应用类型'。 解决：删除错误应用，重新创建'自定义应用'（企业内部应用）。创建后即可在能力管理中开启机器人。
案例：某开发者首次创建时误选'小程序'，排查 1 小时后才发现类型错误，删除重建后问题解决。
踩坑点 2：App Secret 未保存或泄露，导致凭证验证失败
现象：在 OpenClaw 配置中输入 App ID 和 App Secret 后，提示'凭证验证失败'。 原因：
- App Secret 仅在首次创建或重置时显示，未及时保存则丢失。
- 凭证泄露后被他人重置，原凭证失效。
- 输入时包含空格或特殊符号，导致不匹配。 排查：检查应用'凭证与基础信息'中的 App ID 是否与输入一致；若 App Secret 已无法显示，说明需重置。 解决：点击'重置'获取新 App Secret，立即复制保存（建议加密存储）。在 OpenClaw 中重新输入，避免空格。重置后必须重新发布应用版本，新凭证才能生效。
踩坑点 3：权限配置不全，机器人无法收发消息
现象：飞书发送消息给机器人，无任何响应，OpenClaw 控制台无日志。
原因：未开通'即时通讯'核心权限，或遗漏'通讯录基本信息权限'，导致飞书无法将消息推送到 OpenClaw。
排查：进入应用'权限管理'，查看'即时通讯'相关权限是否全部开通，并检查是否勾选 contact:user:read。
解决：勾选所有即时通讯权限（如 im:message:send、im:message:read、im:conversation:read 等）及通讯录权限，保存后重新发布应用。重启 OpenClaw 服务（openclaw restart）后测试。
关键提醒：飞书权限开通后，必须重新发布应用版本才能生效，这是极易遗漏的环节。
踩坑点 4：插件安装失败，报错'spawn npm ENOENT'
现象：执行 openclaw plugins install @m1heng-clawd/feishu 时报错，提示无法找到 npm。
原因：系统环境变量未配置 npm 路径，或 Node.js 未正确安装，导致 PowerShell 无法识别 npm 命令。
排查：在终端执行 npm -v，若提示'不是内部或外部命令'，则确认环境变量缺失。
解决：
- 方法一（配置环境变量）：将 Node.js 安装路径（如
C:\Program Files\nodejs）添加到系统变量 Path 中，重启终端。
