OpenClaw 接入飞书聊天 — 完整实战教程
🌊 OpenClaw 接入飞书聊天 — 完整实战教程
环境：Windows 10 / PowerShell，OpenClaw 2026.7.1-2（本地模式）
适用：国内飞书（Feishu）。Lark 国际版流程类似，仅域名不同。
状态：2026-08-23 实战验证通过 ✅
一、前置条件
OpenClaw 版本 ≥ 2026.5.29（本机 2026.7.1-2，符合）
一个飞书企业账号（能进入开放平台）
OpenClaw gateway 在运行（飞书是 gateway 通道，不是嵌入式模式）
检查 gateway 是否运行：
openclaw gateway status # 看到 "Runtime: running" 即正常
二、关键准备：放开 PowerShell 执行策略 ⚠️
不先做这一步，执行 openclaw 命令会被拦截，报错：
"无法加载 ...openclaw.ps1，因为在此系统上禁止运行脚本"
解决方法：
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
三、在飞书开放平台创建机器人（需手动操作）
拿到两个关键凭证：App ID 和 App Secret。
打开飞书开放平台：https://open.feishu.cn
登录 → 开发者后台 → 创建企业自建应用
填写应用名称、描述、图标，创建
在「凭证与基础信息」页面复制 App ID（形如
cli_xxx）和 App Secret添加应用能力 → 选择 机器人（Bot）
⚠️ 事件订阅方式必须选「长连接(WebSocket)」：
「事件与回调」→ 订阅方式 → 「使用长连接接收事件/回调」
注意：不要选「使用请求地址(Webhook)」
添加事件：
im.message.receive_v1（接收消息）开通权限范围（scope）：至少包含
im:message、im:chat、contact:user.base:readonly发布应用（不发布 = 收不到消息；发布可能走审核）
四、本机配置向导
在终端（PowerShell）运行：
openclaw channels login --channel feishu
向导会：
自动安装插件
@openclaw/feishu（若缺失）询问连接方式：手动输入（粘贴上面的 App ID / App Secret）
💡 提示：扫码方式在国内飞书 App 常失灵，文档建议改用手动输入。
询问 API 域名：国内飞书选 Feishu (feishu.cn) - China
询问群聊策略：按需选择（单聊场景选 allowlist 即可）
五、重启 gateway 使配置生效
openclaw gateway restart
六、首次使用：批准配对
默认 dmPolicy=pairing，第一次给机器人发私信会触发配对流程：
在飞书 App 里给机器人发一条私信（如"你好"）
机器人会回复一条配对码（形如
UHFMRENX）在终端批准配对：
openclaw pairing list feishu openclaw pairing approve feishu UHFMRENX # 用真实 CODE 替换
批准后再私信，即可正常聊天 ✅
七、常用命令
| 命令 | 作用 |
|---|---|
openclaw gateway status | 查看 gateway 状态 |
openclaw gateway restart | 重启 gateway |
openclaw channels login --channel feishu | 飞书配置向导 |
openclaw pairing list feishu | 查看待批准的配对请求 |
openclaw pairing approve feishu <CODE> | 批准配对 |
openclaw logs --follow | 实时查看日志（排查收不到消息） |
飞书机器人聊天命令（飞书无原生斜杠菜单，用纯文本发送）：
/status— 查看机器人状态/reset— 重置当前会话/model— 查看/切换 AI 模型
八、常见问题排查
| 症状 | 原因 / 解决 |
|---|---|
openclaw 命令被拦截 | PowerShell 执行策略未放开 → 先做第二节 |
| 机器人收到消息但一直不回 | 卡在配对认证 → 批准配对码 |
| 私信无反应、pairing 列表为空 | 消息根本没进入 OpenClaw → 看日志 |
| 日志提示"长连接仅自建应用可用" | 事件订阅方式没选「长连接」→ 去开放平台改 |
| 群里不回复 | 是否 @ 了机器人；groupPolicy 是否 disabled |
| 应用已配好仍收不到 | 是否发布了应用；事件是否添加；scope 是否齐全 |
| App Secret 泄漏 | 开放平台重置 Secret → 更新配置 → 重启 gateway |
九、本次实战踩的坑（重点）
✅ 放开 PowerShell 执行策略
✅ 安装插件
@openclaw/feishu✅ 向导手动输入凭证，域名选 feishu.cn，群策略 allowlist
✅ 重启 gateway
🔍 日志显示通道正常、WebSocket 已启动，但机器人不回复
根因：飞书开放平台事件订阅方式没选「长连接」 → 改正后消息即到达
✅ 首次私信触发配对 →
pairing approve批准✅ 正常聊天
