飞书长连接SDK配置完全指南：从踩坑到成功

在给OpenClaw配置飞书机器人时，遇到了一个棘手的问题：飞书后台一直提示"应用未建立长连接"。折腾了近一个小时，终于搞定。这篇文章记录完整的配置过程，以及踩过的坑。

什么是飞书长连接SDK？

传统的Webhook方式需要公网服务器和内网穿透，而长连接SDK让应用通过WebSocket直接连接到飞书服务器，优势很明显：

• 无需公网IP或域名
• 无需HTTPS证书
• 无需内网穿透工具（如ngrok）
• 建连后无需解密和验签

前置条件

1. 飞书自建应用（已发布上线）

2. Node.js >= 18

3. 服务器能访问公网（出口带宽即可）

4. 飞书开放平台SDK：@larksuiteoapi/node-sdk ^1.24.0

飞书后台配置

1. 创建自建应用

进入飞书开放平台，创建「自建应用」，添加「机器人」能力。

2. 开通权限（关键！）

进入「权限管理」，必须开通以下权限：

• im:message — 获取与发送消息
• im:message:send_as_bot — 以机器人身份发消息
• im:message.group_at_msg — 接收群聊@消息
• im:message.p2p_msg — 接收单聊消息
• im:resource — 上传/下载图片与文件（收图必需）

3. 事件订阅配置

进入「事件与回调」→「事件配置」：

1. 订阅方式选择：「使用长连接接收事件」

2. 添加事件：im.message.receive_v1（接收消息）

⚠️ 重要：必须先发布应用，才能保存长连接配置！如果提示"应用未建立长连接"，先检查应用是否已发布。

代码实现

使用 @larksuiteoapi/node-sdk 的 WSClient：

import * as Lark from '@larksuiteoapi/node-sdk';

const sdkConfig = {

  appId: process.env.FEISHU_APP_ID,

  appSecret: process.env.FEISHU_APP_SECRET,

  domain: Lark.Domain.Feishu,

  appType: Lark.AppType.SelfBuild,

};

const wsClient = new Lark.WSClient({

  ...sdkConfig,

  loggerLevel: Lark.LoggerLevel.info

});

wsClient.start({ eventDispatcher: dispatcher });

踩坑记录

坑1：应用未发布

症状：飞书后台保存长连接配置时提示"应用未建立长连接"

解决：必须先在「版本管理与发布」中创建版本并发布应用。

坑2：权限未开通

症状：能建立连接，但收不到消息

解决：检查权限管理中的 im:message 相关权限是否全部开通。

坑3：与内置插件冲突

症状：使用OpenClaw时，内置feishu插件与独立桥接冲突

解决：在 openclaw.json 中禁用内置插件，设置 enabled: false

坑4：进程自动退出

症状：桥接程序启动后不久就停止

解决：使用 nohup 或 pm2 保持进程常驻

完整启动脚本

#!/bin/bash

export FEISHU_APP_ID=cli_xxxxxxxxxxxx

export FEISHU_APP_SECRET=xxxxxxxxxx

cd /path/to/feishu-bridge

exec node bridge.mjs

启动命令：nohup ./start.sh > feishu.log 2>&1 &