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

飞书接入 OpenClaw 指南

本指南旨在帮助开发者在飞书内搭建稳定对话的 AI 机器人，重点解决步骤繁琐和排查困难的问题。OpenClaw 已内置官方飞书插件 @openclaw/feishu，功能更完整、维护更及时。

一、老用户迁移到官方插件（两种方式任选）

适用人群：以前用过独立桥接或 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（可用 cat 查看）
   • 若找不到：去飞书开放平台 https://open.feishu.cn/app → 你的应用 → 凭证与基础信息 复制

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":

导入后：创建新版本 → 发布（让新权限生效）。

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. 准备 App ID / App Secret 同上。

2. 补权限 同方式一（批量导入 + 创建新版本 + 发布）。

3. 安装并配置

# 安装官方飞书插件
openclaw plugins install @openclaw/feishu
# 添加飞书渠道（交互式引导）
openclaw channels add
# → 选择 Feishu
# → 粘贴 App ID
# → 粘贴 App Secret
# 移除旧的 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 logs --follow

日志里看到类似 feishu ws connected 或 feishu provider ready，说明连上了。去飞书里给机器人发消息，能正常回复即完成。

如果机器人回复了配对码（一次性安全操作），执行：

openclaw pairing approve feishu <配对码>

迁移后清理（可选）

稳定运行几天后可清理旧文件：

# 删除旧的 launchd 配置（桥接用户）
rm -f ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist

二、新手从零：配置飞书 AI 机器人（15–20 分钟）

适用人群：第一次用 OpenClaw + 飞书。前提：OpenClaw 已安装并正常运行。

第一步：创建飞书应用（机器人）

• 打开飞书开放平台 https://open.feishu.cn/app
• 创建'企业自建应用'，填名称/描述/图标

第二步：启用机器人能力

你的应用 → 应用能力 > 机器人 → 开启 → 命名机器人

第三步：配置权限（批量导入）

你的应用 → 权限管理 → 批量导入 → 粘贴权限 JSON（与上文完全相同）

这里按流程一键导入需要的权限。

第四步：配置事件订阅（必须长连接）

警告：这一步必须在 OpenClaw 网关启动后再做，否则保存会失败。

• 你的应用 → 事件与回调 > 事件配置
• 请求方式：选择 使用长连接接收事件
• 添加事件：im.message.receive_v1（接收消息）

第五步：记下凭证

你的应用 → 凭证与基础信息：

• App ID（cli_xxxxx）
• App Secret（不要分享）

第六步：发布应用

你的应用 → 版本管理与发布 → 创建版本 → 提交 → 发布/上线

第七步：在 OpenClaw 中配置飞书

# 1. 安装飞书插件
openclaw plugins install @openclaw/feishu
# 2. 添加飞书渠道（交互式，跟着提示走）
openclaw channels add
# 选择 Feishu → 粘贴 App ID → 粘贴 App Secret
# 3. 重启网关
openclaw gateway restart
# 4. 查看日志，确认连接成功
openclaw logs --follow

第八步：发消息测试（配对码处理）

飞书里给机器人发'你好'。如果出现配对码：

openclaw pairing approve feishu <配对码>

批准后即可正常对话。

如果之前跳过了'事件订阅'，现在网关已启动，回去把第四步补上，保存后再 openclaw gateway restart。

第九步（可选）：开机自启

结合 OpenClaw 命令 openclaw gateway install，该命令可将网关安装为开机自启服务。

三、常见问题 & 排查清单

1）没有消息发送框？（最常见）

结论：事件订阅没有配置。权限批量导入不会自动配置事件订阅。

• 飞书开放平台 → 你的应用 → 事件与回调
• 添加事件：im.message.receive_v1
• 订阅方式：使用长连接接收事件
• 版本管理 → 创建新版本 → 发布上线

提醒：配置事件订阅前，确保 OpenClaw/Clawdbot Gateway 已启动，否则长连接验证会失败。

2）机器人完全没反应（收不到消息）

检查顺序：

1. 网关在运行吗？不在就 openclaw gateway restart
2. 飞书应用发布了吗？（版本管理里要有已发布版本）
3. 事件订阅配置了吗？
   • 是否选择'使用长连接接收事件'（不是 Webhook）
   • 是否添加 im.message.receive_v1
4. 权限够吗？最低示例：
   • im:message
   • im:message.p2p_msg:readonly
   • im:message:send_as_bot
5. 看日志：发消息观察日志是否有反应

3）时断时续（有时回复、有时没反应）

常见原因与处理：

• 网络波动（VPN/代理环境尤其容易）：可能频繁断连
• 网关是否反复重启：

openclaw logs |grep -i "restart\|reconnect\|disconnect"

• DNS/代理问题：确保 open.feishu.cn 走直连（不走代理）

4）发图片/发文件，AI 看不到

1. 检查权限：必须有 im:resource
2. 补权限后要 创建新版本 → 发布
3. 重启网关：openclaw gateway restart

5）AI 说生成了图片，但飞书没收到

1. im:resource 权限（用于上传图片到飞书）
2. 看日志 upload 相关错误

6）群聊中机器人不回复

1. 默认需要 @机器人
2. 确认机器人已被加到群
3. 检查 groupPolicy（见进阶配置）

7）回复特别慢

主要由模型响应速度决定；可开启流式输出（默认已开启）；超过 30 秒看日志是否模型调用出错。

8）配对码是什么？怎么用？

首次出于安全，机器人发配对码，管理员批准一次即可：

openclaw pairing approve feishu <配对码>

9）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}}}}}

只允许特定用户在群里使用（allowlist）：

{"channels":{"feishu":{"groupPolicy":"allowlist","groupAllowFrom":["ou_用户 1","ou_用户 2"]}}}

获取群组/用户 ID 的方式：给机器人发消息后看 openclaw logs --follow。

流式输出（默认开启）

{"channels":{"feishu":{"streaming":true,"blockStreaming":true}}}

如要关闭：设 streaming: false。

多 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：已安装插件列表

五、独立桥接模式（进阶用户才需要）

适用于你需要进程隔离（桥接崩溃不影响网关）或有特殊定制需求。大多数用户用官方插件即可。

插件 vs 桥接

• 官方插件：openclaw plugins install，和网关同进程，维护随 OpenClaw 更新，适合日常
• 独立桥接：git clone + npm install，独立进程，互不影响，但需自行维护，适合生产/隔离部署

快速启动

# 克隆项目
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

开机自启（launchd）

# 生成服务配置
node setup-service.mjs
# 加载服务
launchctl load ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist
# 查看状态
launchctl list |grep feishu

日志位置

• ~/.clawdbot/logs/feishu-bridge.out.log（正常输出）
• ~/.clawdbot/logs/feishu-bridge.err.log（错误日志）

调试模式

echo "FEISHU_BRIDGE_DEBUG=1"> .env
tail -n 200 ~/.clawdbot/logs/feishu-bridge.err.log

工作原理

飞书用户 ↔ 飞书云端 ↔（你的电脑上桥接脚本）↔ OpenClaw 网关

桥接通过飞书 WebSocket 长连接接收消息：不需要公网 IP、不需要域名、不需要内网穿透。

六、快问快答

• 需要服务器吗？ 不需要。飞书用 WebSocket 长连接，你的电脑直接连飞书云端，不需要公网 IP。
• 电脑关机了怎么办？ 机器人离线；开机后会自动重连（若配了开机自启）。要 24/7 在线可以用常开设备或云服务器。
• 飞书免费版能用吗？ 可以。自建应用与机器人功能对所有飞书版本开放。
• 能同时接其它渠道吗？ 可以。OpenClaw 支持多渠道，互不影响。
• 用了官方插件后，这个项目还有用吗？ 有：继续提供配置教程、迁移指南、排查与答疑。