一、飞书开放平台后台配置
-
创建应用
- 登录 飞书开放平台
- 点击"创建企业自建应用"
- 关键：选择 "自定义应用"（不是小程序/H5应用）
- 填写应用名称、描述
-
开启机器人能力
- 左侧菜单 → 应用能力 → 添加能力 → 选择 "机器人"
- 开启后保存
-
配置权限（最容易漏的步骤！）
- 左侧菜单 → 权限管理
-
必须添加以下权限：
- ✅
im:message（消息基础权限） - ✅
im:message:send_as_bot（以应用身份发消息） - ✅
im:message.p2p_msg:readonly（读取私聊消息） - ✅
im:message.group_msg:readonly（读取群聊消息） - ✅
接收群聊中@机器人消息事件（自动关联）
- ✅
-
配置事件订阅（关键！）
- 左侧菜单 → 事件与回调
- 订阅方式：选择 "使用长连接接收事件"（不是 Webhook）
- 添加事件：搜索并添加
im.message.receive_v1（接收消息） - 确保事件开关为开启状态（蓝色）
-
记录应用凭证
- 左侧菜单 → 凭证与基础信息
- 记录 App ID 和 App Secret（后续配置用）
二、OpenClaw 服务端配置
-
安装飞书插件
bash
openclaw plugins install @openclaw/feishu
-
添加飞书通道
bash
openclaw channels add
按提示选择：
- 通道类型：
Feishu/Lark - App ID：输入刚才记录的 App ID
- App Secret：输入刚才记录的 App Secret
- connectionMode：
WebSocket（默认，直接回车） - domain：
feishu（国内用户） - groupPolicy：
open（允许所有群聊） - dmPolicy：
pairing（先保持配对模式，或直接选open）
-
创建并绑定代理
# 创建代理（如已存在可跳过）
openclaw agent add primary# 绑定代理到飞书通道
openclaw agent bind primary feishu-
重启网关
bash
openclaw gateway restart# 或sudo systemctl restart openclaw-gateway
三、飞书应用发布
-
发布版本
- 左侧菜单 → 版本管理与发布
- 点击"创建版本"
- 填写版本号（如
1.0.0） - 点击"保存"并"发布"
-
等待审核
- 企业自建应用通常自动通过
- 状态变为"已发布"即可使用
四、最终配对（如果 dmPolicy 为 pairing）
-
私聊机器人获取配对码
在飞书私聊机器人，它会回复：
text
Your Feishu user id: xxxPairing code: XXXXXXAsk the bot owner to approve with:openclaw pairing approve feishu XXXXXX
-
在终端批准配对
bash
openclaw pairing approve feishu XXXXXX
-
（可选）改为开放模式
避免以后每次都要配对
openclaw config set channels.feishu.dmPolicy "open"
openclaw gateway restart
五、验证测试
bash
# 查看网关日志
sudo journalctl -u openclaw-gateway -f
# 或
openclaw gateway在飞书发消息：
- 私聊：直接发送
你好 - 群聊：
@机器人 你好
看到正常回复即成功！
⚠️ 常见坑点总结
| 步骤 | 易错点 | 正确做法 |
| 应用类型 | 选成小程序/H5应用 | 必须选 "自定义应用" |
| 权限 | 只开了基础权限 | 必须开全 4个消息权限 |
| 事件订阅 | 没开事件开关 | im.message.receive_v1 必须启用 |
| 订阅方式 | 选了 Webhook | 必须选 "长连接" |
| 代理绑定 | 忘了绑定 | openclaw agent bind primary feishu |
| 配对 | 没批准 | 飞书私聊获取配对码后批准 |
| 发布 | 配置完没发布 | 必须创建版本并发布 |
🚀 快速部署命令（完整流程）
bash
# 1. 安装插件
openclaw plugins install @openclaw/feishu# 2. 添加通道（交互式，按提示输入）
openclaw channels add# 3. 创建并绑定代理
openclaw agent add primary
openclaw agent bind primary feishu# 4. 设为开放模式（可选）
openclaw config set channels.feishu.dmPolicy "open"
openclaw config set channels.feishu.groupPolicy "open"# 5. 重启网关
openclaw gateway restart