飞书 × OpenClaw 接入指南

老张的码
31 阅读2分钟

飞书 × 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️⃣ 创建应用
  1. 打开 飞书开放平台
  2. 点击「创建企业自建应用」
  3. 填写应用名称（如：AI助手）、描述、图标
  4. 创建完成后进入应用详情页
Step 2️⃣ 开启机器人能力
应用能力 → 机器人 → 开启 → 填写机器人名称
Step 3️⃣ 配置权限

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

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

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

{
  "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️⃣ 配置事件订阅（⚠️ 关键步骤）
事件与回调 → 事件配置
  1. 请求方式：选择「使用长连接接收事件」✅
  2. 添加事件：搜索并添加 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️⃣ 安装飞书插件
# 检查插件是否已安装
openclaw plugins list | grep feishu

# 如未安装，执行安装
openclaw plugins install @openclaw/feishu
Step 7️⃣ 配置凭证

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

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

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

FEISHU_APP_ID=cli_xxx FEISHU_APP_SECRET=xxx openclaw gateway
Step 8️⃣ 重启网关
openclaw gateway restart

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

成功标志：

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

第三部分：发布与测试

Step 9️⃣ 发布应用
版本管理与发布 → 创建版本 → 填写更新说明 → 发布
Step 🔟 测试连接
  1. 打开飞书 App
  2. 搜索你的机器人名称
  3. 发送「你好」测试
  4. 收到回复即成功 🎉

🔍 常见问题排查

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：收到配对码

执行以下命令批准配对：

openclaw pairing approve feishu <配对码>

📁 相关文件

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

🔗 参考链接

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

avatar
文章
阅读
粉丝