OpenClaw 飞书接入全流程：从创建应用到消息收发的完整指南

两种接入方式，先帮你选

OpenClaw 接入飞书有两条路线：内置插件和官方飞书插件。功能侧重不一样，先看对比再动手：

本文主要讲内置插件的完整配置流程，覆盖 90% 以上的使用场景。官方插件在后面单独一节介绍。

接入飞书前的准备工作

开始之前，确认以下几项：

• OpenClaw 已安装运行（版本 ≥ 2026.2）。没装的先去 安装教程
• 飞书开放平台账号：访问 open.feishu.cn（Lark 国际版用 open.larksuite.com）
• 确认 Gateway 正常运行：

openclaw gateway status

好消息：不需要公网 IP 或域名。内置插件默认走 WebSocket 长连接，是 OpenClaw 主动连飞书服务器，NAT 后面也能用。

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

1. 登录 open.feishu.cn → 进入开发者后台
2. 点击创建企业自建应用
3. 填写应用名称（比如"AI 助手"）和描述，随便写就行
4. 进入应用详情 → 凭证与基础信息 → 复制 App ID（格式 cli_xxx）和 App Secret

⚠️ App Secret 相当于密码，不要提交到 Git，不要发到群里。

Lark 国际版用户：操作步骤完全一样，只是域名换成 open.larksuite.com，后续配置中 domain 设为 "lark"。

第二步：配置飞书机器人权限

飞书权限配置有两种方式：

方式 A：批量导入（推荐，省事）

进入应用 → 开发配置 → 权限管理 → 点击批量开通 → 粘贴以下 JSON：

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

方式 B：手动勾选

在权限管理页面逐个搜索上面的权限名称并开通。权限比较多，建议还是用方式 A。

第三步：开启飞书机器人 & 事件订阅

这一步很关键，少配一项都可能导致机器人没反应。

启用机器人

进入应用 → 应用能力 → 机器人 → 点击启用。

配置事件订阅

进入 事件与回调 → 事件订阅 → 选择**"使用长连接接收事件"**。

然后添加以下事件：

⚠️ 如果没配事件订阅，飞书聊天界面不会出现消息输入框，看起来就像机器人不存在一样。

⚠️ 这也是"飞书应用未建立长连接"最常见的原因——事件订阅没选长连接模式，或者根本没添加任何事件。

第四步：发布飞书应用

配置好权限和事件后，还需要发布应用才能生效：

1. 进入 版本管理与发布 → 创建版本
2. 填写版本号和更新说明 → 提交审核
3. 如果你是租户管理员，一般秒过；普通开发者可能需要管理员审批，看你组织的审核规则

发布成功后，在飞书中搜索你的应用名称（比如"AI 助手"）就能找到机器人了。

第五步：OpenClaw 飞书渠道配置

CLI 快速配置

最简单的方式，交互式引导：

openclaw channels add    # 选择 Feishu，粘贴 App ID 和 Secret
openclaw gateway restart

手动配置

编辑 ~/.openclaw/openclaw.json：

{
  channels: {
    feishu: {
      enabled: true,
      domain: "feishu",            // Lark 国际版用 "lark"
      connectionMode: "websocket",
      dmPolicy: "pairing",
      groupPolicy: "open",
      requireMention: true,
      streaming: true,
      typingIndicator: true,
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "你的 App Secret",
          botName: "AI 助手"
        }
      }
    }
  }
}

配置项说明

第六步：启动 OpenClaw 并配对飞书

启动 Gateway

openclaw gateway           # 启动
openclaw logs --follow     # 实时查看日志

配对流程

1. 在飞书中找到你的机器人，发一条消息（随便说句话）
2. 终端日志会出现一个配对码
3. 在终端中批准配对：

openclaw pairing approve feishu <配对码>

4. 再给机器人发条消息，确认 AI 正常回复

验证连接状态：

openclaw gateway status
# 应该看到 Feishu: connected

到这一步，基础的消息收发就跑通了。

飞书群聊机器人配置

默认配置下群聊已经可用（groupPolicy: "open"），但你可能想做更精细的控制。

群聊白名单

只允许特定群聊使用机器人：

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groups: {
        "oc_xxx": {},                    // 群聊 ID
        "oc_yyy": {
          requireMention: false          // 这个群不用 @，直接回复所有消息
        }
      }
    }
  }
}

群聊 ID 可以在飞书群设置中查看，格式是 oc_ 开头的一串字符。

按群设置是否需要 @

全局的 requireMention 可以在单个群里覆盖，适合不同群有不同用法的场景。

飞书 Webhook 模式配置

如果你的网络环境限制了 WebSocket 出站连接（比如某些企业防火墙），可以换成 Webhook 模式：

{
  channels: {
    feishu: {
      connectionMode: "webhook",
      verificationToken: "来自飞书后台",
      encryptKey: "来自飞书后台",
      webhookPath: "/feishu/events",
      webhookPort: 3000
    }
  }
}

Webhook 模式需要你的服务器有公网可访问的地址，飞书会主动推送事件到你的服务器。在飞书后台的事件订阅中填写你的回调地址即可。

绝大多数情况下 WebSocket 就够了，Webhook 模式仅在网络受限时考虑。

飞书多 Agent 路由配置

如果你有多个 AI Agent，可以按渠道和对话类型分配：

{
  bindings: [
    { agentId: "main", match: { channel: "feishu", peer: { kind: "direct" } } },
    { agentId: "team-helper", match: { channel: "feishu", peer: { kind: "group", id: "oc_xxx" } } }
  ]
}

这样私聊走 main agent，特定群聊走 team-helper agent，互不干扰。

OpenClaw 官方飞书插件

官方飞书插件由字节跳动飞书团队维护，功能比内置插件强很多，能操作文档、日历、任务、多维表格、知识库等飞书工作区的几乎所有功能。

版本要求：Linux/macOS ≥ 2026.2.26，Windows ≥ 2026.3.2，Node.js ≥ 22

安装

npm config set registry https://registry.npmjs.org
curl -o /tmp/feishu-plugin.tgz https://sf3-cn.feishucdn.com/obj/open-platform-opendoc/4d184b1ba733bae2423a89e196a2ef8f_QATOjKH1WN.tgz
npm install /tmp/feishu-plugin.tgz -g
rm /tmp/feishu-plugin.tgz
feishu-plugin-onboard install

配对与授权

1. 在飞书中给机器人发消息，获取配对码
2. 批准配对并发送授权通知：

openclaw pairing approve feishu <code> --notify

3. 机器人会回复一条授权链接，点击完成 OAuth 授权
4. 发送 /feishu start 验证插件是否正常工作

诊断命令

遇到问题时用这几个命令排查：

feishu-plugin-onboard doctor           # 检查常见问题
feishu-plugin-onboard doctor --fix     # 自动修复检测到的问题
feishu-plugin-onboard info --all       # 查看完整插件信息

⚠️ 安全提醒：官方插件以你的用户身份访问飞书工作区，拥有你账号的所有权限。不建议在共享的 Bot 上启用，避免其他用户通过 AI 间接访问你的飞书数据。

OpenClaw 飞书常用命令速查

常见问题

需要公网 IP 吗？

不需要。内置插件默认用 WebSocket 长连接，OpenClaw 主动连接飞书服务器，家里的电脑、公司内网都能用。只有 Webhook 模式才需要公网地址。

飞书和 Lark 有什么区别？

功能完全一样，Lark 是飞书的国际版。配置上只需要把 domain 改成 "lark"，开放平台域名用 open.larksuite.com。

内置插件和官方插件怎么选？

只需要消息收发，选内置插件就够了，配置简单。如果需要 AI 帮你操作飞书文档、日历、多维表格这些，选官方插件。

能同时接入其他渠道吗？

能。OpenClaw 支持多渠道同时运行，飞书、Telegram、Discord 可以共享同一个 AI Agent，各渠道独立配置互不影响。

回复很慢怎么办？

先开启 streaming: true（流式输出），体感会快很多。如果还是慢，考虑换一个响应更快的模型，或者检查你的 AI 服务是否有延迟。

App Secret 不小心泄露了怎么办？

立刻去飞书开放平台重置 Secret，然后更新 OpenClaw 配置文件并重启 Gateway。旧 Secret 会立即失效。

飞书聊天界面没有消息输入框怎么办？

这几乎 100% 是事件订阅没配好。回到飞书开放平台，确认已添加 im.message.receive_v1 事件、事件接收方式选的是"长连接"、应用已发布最新版本。

飞书提示"应用未建立长连接"怎么办？

说明飞书服务器没收到 OpenClaw 的 WebSocket 连接。先用 openclaw gateway status 确认 Gateway 在运行，再用 openclaw logs --follow 看有没有连接错误。常见原因：Gateway 没启动、App ID 或 App Secret 填错了、网络不通。确认配置无误后执行 openclaw gateway restart 重启。

机器人完全不回复怎么办？

一步步排查：应用是否已发布（草稿状态不生效）、权限里有没有 im:message:send_as_bot、dmPolicy 是不是设成了 disabled、AI 模型的 API Key 配了没。可以用 openclaw doctor 综合诊断。

群聊中 @机器人没反应怎么办？

确认机器人已加到群里（在群设置中查看）、groupPolicy 不是 disabled。如果用了 allowlist，检查群 ID 是否在列表里。

消息发送失败提示权限不足怎么办？

回飞书开放平台补全权限，补完之后要重新发布一个版本才能生效。

内置插件和官方插件冲突了怎么办？

正常情况下两个插件可以共存——内置插件负责消息收发，官方插件负责工作区操作（文档、日历、任务等），OpenClaw 会自动去重事件。如果确实出现重复回复，可以临时禁用其中一个：feishu-plugin-onboard disable（禁用官方插件）或 openclaw channels disable feishu（禁用内置插件）。

Windows 报 "spawn npm ENOENT" 怎么办？

这是官方插件在 Windows 上的已知问题。推荐用 WSL2 运行 OpenClaw；临时修复方案是找到 exec.js 文件，在 spawn 调用中加上 shell: true。

飞书接入完成，下一步做什么

飞书搞定了，可以继续探索：

• 查看所有支持的渠道 — 50+ 渠道集成
• Skills 技能目录 — 给 AI 装上更多能力
• 问题排查指南 — 通用问题排查
• OpenClaw 完整入门指南 — 从零开始的完整教程
• Telegram 接入指南 — 另一个热门渠道
• Discord 接入指南 — 社区场景首选