OpenClaw 接入飞书：从创建应用到消息验证

当前官方推荐使用 channels login 向导连接企业自建应用，默认通过 WebSocket 接收事件。先让仅自己或少量测试用户可用的私聊链路工作，再考虑群聊与文档工具。

本站未登录你的飞书租户，也没有代你完成管理员审核、权限审批或真实消息收发实测。

前置条件

• 官方飞书页面要求 OpenClaw 2026.5.29 或更高版本；执行前重新核对当前文档。
• 需要能创建和管理企业自建应用，启用机器人、事件并发布版本。
• App ID、App Secret 与模型凭据必须放在受控环境，不能进入聊天、截图或仓库。
• 飞书消息会经过飞书服务；云模型、文档、云盘与 Bitable 还会形成各自的数据边界。

openclaw --version
openclaw status

配置步骤

1. 在飞书开放平台创建企业自建应用。
2. 启用机器人能力，并只在受控环境复制 App ID 与 App Secret。
3. 选择 persistent connection（WebSocket），订阅 im.message.receive_v1。
4. 运行 openclaw channels login --channel feishu，选择区域、手动设置与群组策略。缺少官方插件时，向导会安装 @openclaw/feishu。
5. 在开放平台发布应用版本并完成审批，然后重启 Gateway。
6. 先验证私聊 pairing，再验证群聊 allowlist 与 @提及规则。

openclaw channels login --channel feishu
openclaw gateway restart
openclaw gateway status

权限与事件

基础消息权限

事件必须包含 im.message.receive_v1。当前官方页面没有发布一张永远不变的“最小 scope 清单”，具体 scope 以当天向导和飞书控制台的缺失权限提示为准；不要为了省事授予全部组织权限。

可选读写工具

官方插件还可提供 tools.doc、tools.chat、tools.wiki、tools.drive 与 tools.bitable。不用就不要批准对应飞书权限；敏感的 tools.perm 默认关闭。

Bot 对 Bot

这不是基础配置。确有需要时，官方要求额外权限并配置 allowBots；默认不要开放。

验证清单

1. 应用已经发布并获批，机器人进入测试范围。
2. WebSocket 事件与 im.message.receive_v1 已启用。
3. Gateway 与渠道 probe 返回可用状态。
4. 测试用户私聊触发 pairing，审批前核对发送者。
5. 批准后用一条非敏感消息确认回复。
6. 把机器人加入测试群，@机器人确认群策略与提及门槛。
7. 日志中没有持续的凭证、权限、网络或事件订阅错误。

openclaw gateway status
openclaw channels status --probe
openclaw pairing list feishu
openclaw pairing approve feishu <CODE>
openclaw logs --follow

配对只批准私信访问，不自动开放群聊。共享日志前移除 token、Secret、消息正文和完整个人路径。

常见故障

现象	核对方向
私聊收到配对码但没有回复	用 pairing list 核对请求并批准正确 CODE，随后重发测试消息
群里 @机器人无响应	确认机器人已入群、groupPolicy、群 ID、requireMention 和日志拦截原因
完全收不到消息事件	核对应用发布、事件、WebSocket、权限、Gateway 和日志
App ID / Secret 或网络错误	核对 Feishu/Lark 区域和凭据来源；泄露时立即轮换并重启 Gateway
二维码设置无反应	重新运行 channels login，改用企业自建应用的手动设置
文档或云盘权限不足	先确认是否真的需要该工具，再单独批准对应权限

安全边界

• 私信保留 pairing 或明确 allowlist，不直接改成公开访问。
• 群聊默认使用 allowlist 与 @提及，只开放已审核群和发送者。
• 文档、云盘、Bitable 与权限管理按需启用，并保留人工确认。
• OpenClaw 的单信任边界不等于让互不信任用户共享同一高权限 Gateway 的多租户隔离。

其他渠道可回到渠道中心，接入前先完成安全清单；问题无法定位时进入故障排查。