飞书 OpenClaw 接入指南：无需服务器通过长连接运行机器人

本文介绍如何在无服务器环境下，通过 WebSocket 长连接将飞书 AI 机器人接入 OpenClaw。内容涵盖旧版迁移、新手从零配置、权限设置（批量导入）、事件订阅配置、常见问题排查（如无法发送消息、图片接收失败）以及进阶的群组策略与多 Agent 路由。

一、老用户迁移到官方插件

适用人群：以前用过本项目的独立桥接或 npm 插件，现在要迁到 OpenClaw 内置的官方飞书插件。

迁移前须知

• 之前创建的飞书应用可继续使用，无需重建
• App ID / App Secret 不变
• 聊天记录不受影响（记录在飞书端）
• 迁移时机器人会短暂离线（几分钟）

方式一：通过 OpenClaw 升级（推荐）

前提：OpenClaw 版本 ≥ 2026.2。

1. 升级 OpenClaw：升级完成会自动重启网关。
2. 添加飞书渠道：选择 Feishu → 填 App ID → 填 App Secret。
   • App Secret 可能位于 ~/.clawdbot/secrets/feishu_app_secret。
   • 若找不到，去飞书开放平台应用凭证与基础信息复制。
3. 补全飞书应用权限： 去飞书开放平台 → 权限管理 → 批量导入以下 JSON：

{"scopes":{"tenant":["aily:file:read","aily:file:write","application:application.app_message_stats.overview:readonly","application:application.self_manage","application:bot.menu:write","cardkit:card:write","contact:user.employee_id:readonly","corehr:file:download","docs:document.content:read","event:ip_list","im:chat","im:chat.access_event.bot_p2p_chat:read","im:chat.members:bot_access","im:message","im:message.group_at_msg:readonly","im:message.group_msg","im:message.p2p_msg:readonly","im:message:readonly","im:message:send_as_bot","im:resource","sheets:spreadsheet","wiki:wiki:readonly"],"user":["aily:file:read","aily:file:write","im:chat.access_event.bot_p2p_chat:read"]}}

导入后创建新版本并发布。 4. 清理旧插件/桥接：

# 移除旧的 npm 插件
openclaw plugins remove feishu-openclaw 2>/dev/null
# 停掉旧的桥接服务
launchctl unload ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist 2>/dev/null
# 重启网关
openclaw gateway restart

方式二：手动安装插件 + 配置

适用：不想升级 OpenClaw。

1. 准备凭证：同上。
2. 补权限：同方式一。
3. 安装并配置：

# 安装官方飞书插件
openclaw plugins install @openclaw/feishu
# 添加飞书渠道（交互式引导）
openclaw channels add
# → 选择 Feishu
# → 粘贴 App ID
# → 粘贴 App Secret
# 移除旧插件和桥接（同上）
openclaw plugins remove feishu-openclaw 2>/dev/null
launchctl unload ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist 2>/dev/null
openclaw gateway restart

验证与清理

• 验证：查看日志 openclaw logs --follow，看到 feishu ws connected 或 feishu provider ready 即成功。飞书内发消息测试。
• 配对：若收到配对码，执行 openclaw pairing approve feishu <配对码>。
• 清理：稳定运行后可删除旧 launchd 配置 rm -f ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist。

二、新手从零配置（15–20 分钟）

前提：OpenClaw 已安装并正常运行。

1. 创建飞书应用：打开飞书开放平台，创建企业自建应用。
2. 启用机器人能力：应用能力 > 机器人 → 开启。
3. 配置权限：权限管理 → 批量导入上述 JSON。
4. 配置事件订阅（必须长连接）：
   • 事件与回调 > 事件配置
   • 请求方式：使用长连接接收事件
   • 添加事件：im.message.receive_v1
   • 注意：此步建议在 OpenClaw 网关启动后进行，否则保存可能失败。
5. 记下凭证：App ID 和 App Secret。
6. 发布应用：版本管理与发布 → 创建版本 → 提交 → 发布。
7. 在 OpenClaw 中配置：

openclaw plugins install @openclaw/feishu
openclaw channels add
# 选择 Feishu → 粘贴 App ID → 粘贴 App Secret
openclaw gateway restart
openclaw logs --follow

8. 测试：飞书发'你好'，按提示批准配对码。
9. 开机自启：使用 openclaw gateway install。

三、常见问题 & 排查清单

1. 没有消息发送框：事件订阅未配置。去飞书开放平台添加 im.message.receive_v1 事件，选择长连接，发布新版本。
2. 机器人没反应：
   • 检查网关是否运行 (openclaw gateway restart)。
   • 确认应用已发布。
   • 确认事件订阅为长连接且包含 im.message.receive_v1。
   • 检查权限（最低：im:message, im:message.p2p_msg:readonly, im:message:send_as_bot）。
   • 查看日志。
3. 时断时续：网络波动或代理问题。确保 open.feishu.cn 直连。检查日志是否有重连记录。
4. 发图片/文件 AI 看不到：必须有 im:resource 权限，补权限后发布并重启网关。
5. AI 生成图片飞书没收到：检查 im:resource 权限及 upload 相关日志。
6. 群聊不回复：默认需@机器人，确认已加群，检查 groupPolicy。
7. 回复慢：模型响应速度决定，可开启流式输出（默认开启），超时看日志。
8. Lark 用户：配置里指定域名 {"channels":{"feishu":{"domain":"lark"}}}。

四、进阶配置参考

• 配置文件位置：~/.openclaw/openclaw.json
• 基础配置示例：

{"channels":{"feishu":{"enabled":true,"dmPolicy":"pairing","accounts":{"main":{"appId":"cli_xxxxxxxxx","appSecret":"你的 AppSecret","botName":"我的 AI 助手"}}}}}

• 群组配置：
  • 指定群无需@：{"channels":{"feishu":{"groups":{"oc_你的群组ID":{"requireMention":false}}}}}
  • 白名单用户：{"channels":{"feishu":{"groupPolicy":"allowlist","groupAllowFrom":["ou_用户 1","ou_用户 2"]}}}
• 流式输出：{"channels":{"feishu":{"streaming":true,"blockStreaming":true}}}
• 多 Agent 路由：

{"bindings":[{"agentId":"main","match":{"channel":"feishu","peer":{"kind":"dm","id":"ou_用户 A"}}},{"agentId":"另一个 agent","match":{"channel":"feishu","peer":{"kind":"group","id":"oc_某群组"}}}]} 

• 访问控制策略：pairing（默认配对）, allowlist（白名单）, open（所有人）, disabled（禁止私聊）。

五、常用命令速查

• openclaw gateway status：查看状态
• openclaw gateway restart：重启网关
• openclaw gateway install：开机自启
• openclaw logs --follow：实时日志
• openclaw pairing list feishu：查看待授权
• openclaw pairing approve feishu <CODE>：批准配对
• openclaw plugins list：已安装插件

六、独立桥接模式

适用于需要进程隔离或有特殊定制需求。大多数用户用官方插件即可。

• 快速启动：

git clone https://github.com/AlexAnys/feishu-openclaw.git
cd feishu-openclaw
npm install
mkdir -p ~/.clawdbot/secrets
echo "你的 AppSecret"> ~/.clawdbot/secrets/feishu_app_secret
chmod 600 ~/.clawdbot/secrets/feishu_app_secret
FEISHU_APP_ID=cli_xxxxxxxxx node bridge.mjs

• 开机自启：

node setup-service.mjs
launchctl load ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist
launchctl list |grep feishu

• 工作原理：飞书用户 ↔ 飞书云端 ↔ 电脑桥接脚本 ↔ OpenClaw 网关。通过 WebSocket 长连接接收消息，无需公网 IP。