飞书 × OpenClaw 接入指南

使用 WebSocket 长连接模式，无需公网服务器，15-20 分钟完成配置

整理日期：2026-03-05

📊 流程总览

flowchart TD subgraph "飞书开放平台" A["创建企业自建应用"] --> B["开启机器人能力"] B --> C["配置权限"] C --> D["配置事件订阅"] D --> E["发布应用"] end subgraph "OpenClaw 侧" F["安装飞书插件"] --> G["配置凭证"] G --> H["重启网关"] end E --> I{测试连接} H --> I I -->|成功| J["🎉 开始使用"] I -->|失败| K["排查问题"] K --> I

🔧 详细步骤

第一部分：飞书后台配置

Step 1️⃣ 创建应用

打开飞书开放平台
点击「创建企业自建应用」
填写应用名称（如：AI助手）、描述、图标
创建完成后进入应用详情页

Step 2️⃣ 开启机器人能力

复制代码

应用能力 → 机器人 → 开启 → 填写机器人名称

Step 3️⃣ 配置权限

进入「权限管理」→「批量导入」，粘贴以下 JSON：

json 复制代码

{
  "scopes": {
    "tenant": [
      "im:message",
      "im:message.p2p_msg:readonly",
      "im:message:send_as_bot",
      "im:resource"
    ]
  }
}

💡 如需更多功能（图片、文件等），可导入完整权限：

json 复制代码

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "im:chat",
      "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"
    ]
  }
}

Step 4️⃣ 配置事件订阅（⚠️ 关键步骤）

复制代码

事件与回调 → 事件配置

请求方式：选择「使用长连接接收事件」✅
添加事件 ：搜索并添加 im.message.receive_v1

flowchart LR A[事件与回调] --> B[事件配置] B --> C[请求方式: 长连接] B --> D[添加事件: im.message.receive_v1]

⚠️ 重要：必须选择「长连接」模式，不要选 Webhook！

Step 5️⃣ 记录凭证

进入「凭证与基础信息」，复制：

App ID ：cli_xxxxxxxxxx
App Secret：（点击显示后复制）

第二部分：OpenClaw 配置

Step 6️⃣ 安装飞书插件

bash 复制代码

# 检查插件是否已安装
openclaw plugins list | grep feishu

# 如未安装，执行安装
openclaw plugins install @openclaw/feishu

Step 7️⃣ 配置凭证

编辑配置文件 ~/.openclaw/openclaw.json，在 env 部分添加：

json 复制代码

{
  "env": {
    "FEISHU_APP_ID": "cli_xxxxxxxxxx",
    "FEISHU_APP_SECRET": "你的AppSecret"
  }
}

或通过环境变量启动网关：

bash 复制代码

FEISHU_APP_ID=cli_xxx FEISHU_APP_SECRET=xxx openclaw gateway

Step 8️⃣ 重启网关

bash 复制代码

openclaw gateway restart

# 查看日志确认连接
openclaw logs --follow | grep feishu

成功标志：

csharp 复制代码

[feishu] Starting WebSocket long-connection...
[feishu] WebSocket client started (waiting for connection...)

第三部分：发布与测试

Step 9️⃣ 发布应用

复制代码

版本管理与发布 → 创建版本 → 填写更新说明 → 发布

Step 🔟 测试连接

打开飞书 App
搜索你的机器人名称
发送「你好」测试
收到回复即成功 🎉

🔍 常见问题排查

flowchart TD A[机器人不回复?] --> B{检查网关日志} B -->|无 feishu 日志| C[检查凭证配置] B -->|有连接日志| D{检查飞书后台} D --> E[事件订阅是否配置?] D --> F[应用是否已发布?] D --> G[权限是否已添加?] C --> H[重新配置 App ID/Secret] E -->|未配置| I[添加 im.message.receive_v1] F -->|未发布| J[创建版本并发布] G -->|未添加| K[批量导入权限]

问题 1：搜不到机器人

检查应用是否已发布上线
检查应用可用范围是否包含自己

问题 2：机器人不回复

查看 openclaw logs | grep feishu
确认事件订阅已配置（长连接模式）
确认 im.message.receive_v1 事件已添加

问题 3：收到配对码

执行以下命令批准配对：

bash 复制代码

openclaw pairing approve feishu <配对码>

📁 相关文件

文件	路径	说明
主配置	`~/.openclaw/openclaw.json`	凭证和渠道配置
插件目录	`~/.openclaw/extensions/feishu/`	飞书插件源码
日志文件	`/tmp/openclaw/openclaw-YYYY-MM-DD.log`	运行日志

🔗 参考链接

文档整理：八佰 | 2026-03-05