OpenClaw-飞书APP插件集成操作手册

本文档详细介绍了如何在OpenClaw中集成飞书/Lark机器人，主要包含以下内容：安装飞书插件并添加渠道，提供了向导安装和手动安装两种方式，重点说明了插件重复问题的解决方案，推荐使用源码插件便于调试和保持最新。创建飞书应用的完整流程，包括获取应用凭证、配置权限、启用机器人能力和事件订阅等关键步骤。详细的配置参数说明，涵盖基础配置、私聊/群组策略、消息渲染模式和流式输出等选项。文档特别强调

dingyn

2364人浏览 · 2026-03-01 18:46:26

dingyn · 2026-03-01 18:46:26 发布

OpenClaw 飞书APP集成操作手册-小白必看

本文档说明如何在OpenClaw中集成飞书/Lark机器人，包括插件安装、应用创建、配置步骤和访问控制。注意：如果只是想要聊天直接安装飞书长连接版的Skill即可

一、前置要求

OpenClaw Gateway 已安装并正常运行
已完成初始配置（openclaw onboard）
具备飞书管理员权限（用于创建企业自建应用）
OpenClaw 版本 2.23 之前试用，新版有更新后续补充

二、安装飞书插件并添加渠道

⚠️ 重要说明：当您运行 openclaw channels add 向导添加飞书渠道时（直接改配置新增则不会出现），向导会自动安装飞书插件到 ~/openclaw-data/extensions/ 目录。如果您是源码安装用户，您的源码目录 ~/Applications/openclaw/extensions/feishu/ 也包含飞书插件。这会导致插件重复：

~/openclaw-data/extensions/feishu/ ← 向导自动安装

~/Applications/openclaw/extensions/feishu/ ← 源码自带 如上图可以在选择时直接本地插件安装就能避免警告

解决方案：
如果您想使用源码中的飞书插件（推荐，便于调试和保持最新），请删除向导安装的目录：
rm -rf ~/openclaw-data/extensions/feishu/
并在配置中添加 plugins.allow 白名单（见下方）
为什么推荐使用源码的插件？

保持最新：源码会跟随 OpenClaw 主仓库同步更新，修复 bug 和新功能能第一时间使用

便于调试：如果遇到问题，可以直接查看和修改源码进行调试

版本一致：向导安装的版本可能比源码旧，导致功能或兼容性问题

2.1 通过向导安装（推荐新手）

openclaw channels add

向导会引导您完成以下步骤：

选择 Feishu/Lark (飞书) 渠道
输入飞书应用的 App ID 和 App Secret
配置私聊策略（默认配对模式）
配置群组策略（默认白名单）
向导会自动安装飞书插件

2.2 手动安装（源码用户）

如果您想使用源码目录中的飞书插件（便于调试开发）：

# 先删除向导自动安装的（如果有）
rm -rf ~/openclaw-data/extensions/feishu/

# 然后安装源码目录的插件
openclaw plugins install ./extensions/feishu

或者使用 pnpm：

pnpm openclaw plugins install ./extensions/feishu

2.3 配置插件白名单（安全建议）

为避免插件重复加载的警告，建议在配置中添加 plugins.allow 白名单：

{
  plugins: {
    allow: ["feishu", "qwen-portal-auth"],
    entries: {
      feishu: { enabled: true },
      "qwen-portal-auth": { enabled: true },
    },
  },
}

说明：配置 plugins.allow 后，只有列表中的插件才会被加载，同时也能消除"plugins.allow is empty"的警告。

最终安装结果可以通过 openclaw plugins list 查看（此处是本地安装）
在这里插入图片描述

三、创建飞书应用

3.1 打开飞书开放平台

访问飞书开放平台登录账号。

注意：如使用Lark国际版，请访问 https://open.larksuite.com/app ，并在配置中设置 domain: "lark"。

3.2 创建企业自建应用

点击 创建企业自建应用
填写应用名称（如 “OpenClaw AI助手”）和描述
上传应用图标（可选）

3.3 获取应用凭证

在应用的 凭证与基础信息 页面，复制以下信息：

凭证	说明	格式示例
App ID	应用唯一标识	`cli_xxxxxxxxxxxxxx`
App Secret	应用密钥	`xxxxxxxxxxxxxxxxxx`

⚠️ 重要：App Secret 只显示一次，请妥善保存。

3.4 配置应用权限

在 权限管理 页面，点击 批量导入，粘贴以下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": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"]
  }
}

3.5 启用机器人能力

在 应用能力 > 机器人 页面：

开启机器人能力
设置机器人名称

3.6 配置事件订阅

进入 事件订阅 页面
选择 使用长连接接收事件（WebSocket模式）
添加事件：im.message.receive_v1 重要‼️
点击保存

⚠️ 重要：配置事件订阅前，请确保Gateway已启动，可以去配置中看看是否将当前机器人配置上，否则长连接设置可能无法保存成功。

3.7 发布应用

进入 版本管理与发布 页面
创建新版本并提交发布
等待管理员审批（企业应用通常自动通过）

四、配置参数详解

4.1 基础配置参数

参数	类型	默认值	说明
`enabled`	boolean	-	是否启用该渠道
`appId`	string	-	飞书应用App ID
`appSecret`	string	-	飞书应用App Secret
`encryptKey`	string	-	加密密钥（Webhook模式需要）
`verificationToken`	string	-	验证Token（Webhook模式需要）
`domain`	string	“feishu”	域名：feishu（国内版）或 lark（国际版）
`connectionMode`	string	“websocket”	连接模式：websocket 或 webhook
`botName`	string	-	机器人显示名称

4.2 私聊策略（dmPolicy）

值	说明
`"pairing"`（默认）	陌生用户需配对码才能对话
`"allowlist"`	仅允许白名单用户对话
`"open"`	允许所有用户对话
`"disabled"`	禁用私聊

4.3 群组策略（groupPolicy）

值	说明
`"allowlist"`（默认）	仅允许白名单用户
`"open"`	允许所有群成员
`"disabled"`	禁用群组消息

4.4 消息渲染模式（renderMode）

值	说明
`"auto"`（默认）	自动检测Markdown
`"raw"`	纯文本
`"card"`	使用卡片消息

4.5 流式输出（streaming）

{
  channels: {
    feishu: {
      streaming: true,
      blockStreaming: {
        enabled: true,
        minDelayMs: 30,
        maxDelayMs: 100,
      },
    },
  },
}

4.6 完整配置示例

{
  channels: {
    feishu: {
      enabled: true,
      domain: "feishu",
      connectionMode: "websocket",
      dmPolicy: "pairing",
      groupPolicy: "allowlist",
      requireMention: true,
      textChunkLimit: 2000,
      mediaMaxMb: 30,
      streaming: true,
      renderMode: "auto",
      accounts: {
        main: {
          appId: "cli_xxxxxxxxxxxxxx",
          appSecret: "xxxxxxxxxxxxxxxxxx",
          botName: "OpenClaw AI助手",
          groupPolicy: "open",
          groups: {
            oc_xxxxxxxx: {
              requireMention: false,
            },
          },
        },
      },
    },
  },
}

五、访问控制配置

5.1 私聊访问控制

配对模式（默认）

陌生用户发送消息时，机器人会自动回复配对码：

# 查看待配对列表
openclaw pairing list feishu

# 批准配对请求
openclaw pairing approve feishu <配对码>

白名单模式

{
  channels: {
    feishu: {
      dmPolicy: "allowlist",
      allowFrom: ["ou_xxxxxxxx", "ou_yyyyyyyy"],
    },
  },
}

5.2 群组访问控制

允许所有群组（需要@提及）

{
  channels: {
    feishu: {
      groupPolicy: "open",
      requireMention: true,
    },
  },
}

允许所有群组（无需@提及）

{
  channels: {
    feishu: {
      groupPolicy: "open",
      requireMention: false,
    },
  },
}

特定群组配置

{
  channels: {
    feishu: {
      groups: {
        oc_xxxxxxxx: {
          requireMention: false,
          systemPrompt: "你是一个技术助手",
          enabled: true,
        },
      },
    },
  },
}

六、启动与验证

6.1 重启Gateway

配置完成后，重启Gateway使配置生效：

openclaw gateway restart

6.2 检查状态

# 查看Gateway状态
openclaw gateway status

# 查看所有渠道状态（不加参数）
openclaw channels status

# 带探测的渠道状态（检查连接）
openclaw channels status --probe

6.3 验证连接

在飞书中找到创建的机器人
发送一条测试消息
若使用配对模式，回复配对码并批准
确认机器人能够正常响应

七、获取群组/用户ID

7.1 获取群组ID（chat_id）

格式：oc_xxxxxxxx

方法一：查看日志

openclaw logs --follow | grep "chat_id"

方法二：使用飞书API调试工具获取机器人所在群组列表

7.2 获取用户ID（open_id）

格式：ou_xxxxxxxx

方法一：查看日志

openclaw logs --follow | grep "open_id"

方法二：查看配对请求列表

openclaw pairing list feishu

八、多Agent路由配置

通过 bindings 将不同用户/群组路由到不同的Agent：

{
  agents: {
    list: [{ id: "main" }, { id: "assistant", workspace: "~/.openclaw/workspace-assistant" }],
  },
  bindings: [
    {
      agentId: "main",
      match: {
        channel: "feishu",
        peer: { kind: "dm", id: "ou_用户A的open_id" },
      },
    },
    {
      agentId: "assistant",
      match: {
        channel: "feishu",
        peer: { kind: "group", id: "oc_群组ID" },
      },
    },
  ],
}

九、常用命令

命令	说明
`openclaw channels add`	添加新渠道
`openclaw channels status`	查看所有渠道状态
`openclaw channels status --probe`	探测渠道连接状态
`openclaw pairing list feishu`	查看待配对列表
`openclaw pairing approve feishu <code>`	批准配对
`openclaw gateway restart`	重启Gateway
`openclaw logs --follow`	查看实时日志

十、故障排查

10.1 Gateway未启动

openclaw gateway start

10.2 机器人无响应

检查飞书应用是否已发布
检查App ID和App Secret是否正确
查看日志：openclaw logs --follow
验证事件订阅是否配置正确

10.3 配对失败

# 查看配对状态
openclaw pairing list feishu

# 重新批准配对
openclaw pairing approve feishu <配对码>

十一、飞书插件卸载

11.1 彻底卸载步骤

如果您需要彻底卸载飞书插件，可以按照以下步骤操作：

1. 停止Gateway服务

# 停止Gateway服务
launchctl bootout gui/$UID/ai.openclaw.gateway

2. 清理插件文件

# 删除向导自动安装的插件目录
rm -rf ~/openclaw-data/extensions/feishu/

# 注意：源码目录中的插件（~/Applications/openclaw/extensions/feishu/）是源码自带的，不建议删除

3. 清理配置文件
编辑 ~/openclaw-data/openclaw.json 文件，移除以下飞书相关配置：

channels.feishu 配置段
plugins.allow 中的 “feishu” 条目
plugins.load.paths 中的飞书插件路径
plugins.entries 中的 “feishu” 配置
plugins.installs 中的 “feishu” 安装记录

4. 重新启动服务

# 重新安装并启动Gateway服务
openclaw gateway install
openclaw gateway start

5. 验证卸载结果

# 查看插件状态
openclaw plugins list

# 查看渠道状态
openclaw channels status

11.2 飞书开放平台应用清理

如果您不再需要飞书应用，可以在飞书开放平台删除：

登录飞书开放平台
找到您创建的OpenClaw应用
进入应用设置，选择删除应用
确认删除操作

十二、高级配置选项

12.1 多账号配置

您可以在飞书插件中配置多个飞书账号：

{
  channels: {
    feishu: {
      enabled: true,
      accounts: {
        main: {
          appId: "cli_xxxxxxxxxxxxxx",
          appSecret: "xxxxxxxxxxxxxxxxxx",
          botName: "OpenClaw AI助手",
          domain: "feishu"
        },
        lark: {
          appId: "cli_yyyyyyyyyyyyyy",
          appSecret: "yyyyyyyyyyyyyyyyyyyy",
          botName: "OpenClaw Lark Assistant",
          domain: "lark"
        }
      }
    }
  }
}

12.2 消息处理配置

{
  channels: {
    feishu: {
      // 消息分块设置
      textChunkLimit: 2000,  // 单条消息最大长度
      chunkMode: "length",   // 分块模式：length 或 newline
      
      // 媒体文件设置
      mediaMaxMb: 30,        // 最大文件大小
      
      // 会话范围设置
      groupSessionScope: "group_topic",  // 群组会话范围
      topicSessionMode: "enabled",       // 话题会话模式
      replyInThread: "enabled",          // 线程回复模式
      
      // 历史消息设置
      historyLimit: 50,      // 群组历史消息限制
      dmHistoryLimit: 100,   // 私聊历史消息限制
    }
  }
}

12.3 安全配置

{
  channels: {
    feishu: {
      // 访问控制
      dmPolicy: "pairing",      // 私聊策略
      groupPolicy: "allowlist",  // 群组策略
      requireMention: true,      // 群组中需要@机器人
      
      // 白名单配置
      allowFrom: ["ou_xxxxxxxx"],          // 私聊白名单
      groupAllowFrom: ["oc_xxxxxxxx"],     // 群组白名单
    }
  }
}