OpenClaw Lark/飞书 插件

English | 中文版

这是 OpenClaw 的官方 Lark/飞书 插件，由 Lark/飞书开放平台团队开发和维护。它将你的 OpenClaw Agent 无缝对接到 Lark/飞书 工作区，赋予其直接读写消息、文档、多维表格、日历、任务等应用的能力。

特性

本插件为 OpenClaw 提供了全面的 Lark/飞书集成能力，主要包括：

| 类别 | 能力 | |------|------| | 💬 消息 | 消息读取（群聊/单聊历史、话题回复）、消息发送、消息回复、消息搜索、图片/文件下载 | | 📄 文档 | 创建云文档、更新云文档、读取云文档内容 | | 📊 多维表格 | 创建/管理多维表格、数据表、字段、记录（增删改查、批量操作、高级筛选）、视图 | | 📈 电子表格 | 创建、编辑、查看电子表格 | | 📅 日历日程 | 日历管理、日程管理（创建/查询/修改/删除/搜索）、参会人管理、忙闲查询 | | ✅ 任务 | 任务管理（创建/查询/更新/完成）、清单管理、子任务、评论 |

此外，插件还支持：

• 📱 交互式卡片：实时状态更新（思考中/生成中/完成状态），提供敏感操作的确认按钮
• 🌊 流式回复：在消息卡片中提供实时的流式响应
• 🔒 权限策略：为私聊和群聊提供灵活的访问控制策略
• ⚙️ 高级群组配置：每个群聊的独立设置，包括白名单、技能绑定和自定义系统提示词

安全与风险提示（使用前必读）

本插件对接 OpenClaw AI 自动化能力，存在模型幻觉、执行不可控、提示词注入等固有风险；授权飞书权限后，OpenClaw 将以您的用户身份在授权范围内执行操作，可能导致敏感数据泄露、越权操作等高风险后果，请您谨慎操作和使用。 为降低上述风险，插件已在多个层面启用默认安全保护以降低上述风险，但上述风险仍然存在。我们强烈建议不要主动修改任何默认安全配置；一旦放开相关限制，上述风险将显著提高，由此产生的后果需由您自行承担。 我们建议您将接入 OpenClaw 的飞书机器人作为私人对话助手使用，请勿将其拉入群聊或允许其他用户与其交互，以避免权限被滥用或数据泄露。 请您充分知悉全部使用风险，使用本插件即视为您自愿承担相关所有责任。

免责声明：

本软件的代码采用MIT许可证。 该软件运行时会调用Lark/飞书开放平台的API，使用这些API需要遵守如下协议和隐私政策：

• 飞书用户服务协议
• 飞书隐私政策
• 飞书开放平台独立软件服务商安全管理运营规范
• Lark用户服务协议
• Lark隐私政策

安装与要求

在开始之前，请确保你已准备好以下各项：

• Node.js: v22 或更高版本。
• OpenClaw: OpenClaw 已成功安装并可运行。详情请访问 OpenClaw 官方网站。

注意：OpenClaw 版本需在 2026.2.26 及以上，可通过 openclaw -v 命令查看。如果低于该版本可能出现异常，执行以下命令升级：

npm install -g openclaw

使用说明

OpenClaw Lark/飞书官方插件使用指南

配置字段说明

以下为 openclaw.json 中飞书渠道（channels.feishu）支持的所有配置项。

带 🔒 标记的字段为只读字段，由系统固定，用户不可修改。 带 ⚙️ 标记的字段为后端自动填充字段，请勿手动配置。

凭证与身份

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | appId | string | — | 飞书开放平台应用 App ID | | appSecret | string | — | 飞书开放平台应用 App Secret | | encryptKey | string | — | 事件订阅加密密钥（Encrypt Key），用于验证回调签名 | | verificationToken | string | — | 事件订阅验证令牌（Verification Token） | | name | string | — | 账号显示名称，仅用于日志和诊断，不影响功能 | | enabled | boolean | true | 是否启用该账号；false 时不建立 WebSocket 连接 |

连接配置

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | domain | 'feishu' | 'lark' | string | feishu | 飞书/Lark 域名；'feishu' 国内、'lark' 国际、'https://...' 自建服务 | | connectionMode | 'websocket' | 'webhook' | 'websocket' | 接收消息的连接方式；当前仅 websocket 完整实现 | | webhookPath | string | — | webhook 模式下的 HTTP 接收路径 | | webhookPort | number | — | webhook 模式下的监听端口 |

访问控制

单聊（DM）策略

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | dmPolicy | 'open' | 'pairing' | 'allowlist' | 'disabled' | 'pairing' | 单聊访问策略（见下方说明） | | allowFrom | string[] | — | 单聊白名单；支持通配符 '*'；dmPolicy='open' 时必须含 '*' |

dmPolicy 取值说明：

| 值 | 行为 | |----|------| | 'open' | 接受所有用户的单聊（allowFrom 须含 '*'） | | 'pairing' | 默认值；未知用户触发配对流程，配对后加入白名单 | | 'allowlist' | 严格白名单，仅 allowFrom 中的用户可发起单聊 | | 'disabled' | 关闭所有单聊入口 |

群聊策略

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | groupPolicy | 'open' | 'allowlist' | 'disabled' | 'open' | 群聊全局访问策略 | | groupAllowFrom | string[] | — | 群内发送者全局白名单，适用于所有群 | | requireMention | boolean | — | 群聊中是否必须 @bot 才响应；可在 groups 中单独覆盖 | | groups | object | — | 按群 ID 的细粒度配置（见下方说明） |

groupPolicy 取值说明：

| 值 | 行为 | |----|------| | 'open' | 接受来自所有群的消息（无 groups 配置时） | | 'allowlist' | 仅接受 groups 中列出的群 | | 'disabled' | 关闭所有群聊入口 |

groups 配置说明：

groups 为按群 chat_id 索引的对象，支持特殊键 '*' 作为所有群的默认配置：

{
  "groups": {
    "oc_xxxxx": {
      "groupPolicy": "open",
      "requireMention": true,
      "allowFrom": ["ou_yyyyy"],
      "systemPrompt": "你是该群的专属助手",
      "enabled": true
    },
    "*": {
      "groupPolicy": "allowlist",
      "requireMention": true
    }
  }
}

每个群组配置支持的字段：

| 字段 | 类型 | 说明 | |------|------|------| | groupPolicy | string | 该群发送者访问策略，覆盖全局 groupPolicy | | requireMention | boolean | 是否必须 @bot，覆盖全局 requireMention | | allowFrom | string[] | 该群发送者白名单 | | enabled | boolean | 是否启用该群；false 时拒绝所有来自该群的消息 | | skills | string[] | 该群绑定的技能列表 | | systemPrompt | string | 该群的自定义系统提示词 | | tools | object | 该群的工具权限，覆盖全局 tools |

对话历史

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | historyLimit | number | — | 群聊历史上下文窗口大小（消息条数）；0 表示不保留历史 | | dmHistoryLimit | number | — | 单聊历史上下文窗口大小；不设置时沿用 historyLimit |

消息发送

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | textChunkLimit | number | 4000 | 单条消息最大字符数，超出则分片发送（仅静态模式生效） | | chunkMode | 'newline' | 'paragraph' | 'none' | — | 文本分片策略 | | mediaMaxMb | number | — | 允许接收的最大媒体文件大小（MB） |

chunkMode 说明：

| 值 | 行为 | |----|------| | 'newline' | 按换行符分割 | | 'paragraph' | 按段落（连续多个换行）分割 | | 'none' | 不分割，整体发送一条消息 |

流式回复

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | streaming | boolean | false | 流式卡片总开关；false 时所有回复为静态模式 | | replyMode | string | object | — | 回复模式（见下方说明）；需 streaming: true 才能使用流式 | | blockStreaming | boolean | false | 静态模式下是否启用块级流式推送 | | blockStreamingCoalesce | object | — | 块级流式合并策略（需 blockStreaming=true） |

replyMode 说明：

字符串形式：

| 值 | 行为 | |----|------| | 'static' | 一次性发送完整内容，可能为多条消息 | | 'streaming' | 在单张交互式卡片中实时更新 | | 'auto' | 群聊 → static，单聊 → streaming |

对象形式（按场景分别指定）：

{
  "replyMode": {
    "default": "static",
    "group": "static",
    "direct": "streaming"
  }
}

blockStreamingCoalesce 说明：

| 字段 | 类型 | 说明 | |------|------|------| | minChars | number | 触发发送的最小字符累积量 | | maxChars | number | 单次发送的最大字符量 | | idleMs | number | 空闲超时后强制发送（毫秒） |

工具与权限

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | tools | object | 全部启用 | 内置飞书工具的启用开关 | | footer | object | 全部关闭 | 交互卡片页脚显示配置（仅流式卡片模式生效） | | markdown | object | — | Markdown 渲染选项 | | configWrites | boolean | — | 是否允许通过运行时 API 动态修改配置；谨慎开启 | | capabilities | object | — | 媒体接收能力开关 | | uat | object | — | User Access Token 配置 |

tools 字段说明：

| 子字段 | 说明 | |--------|------| | doc | 云文档读写工具 | | wiki | 知识库读写工具 | | drive | 云盘操作工具 | | perm | 权限管理工具 | | scopes | 作用域查询工具 |

未设置某项时默认启用；设为 false 可在全局或群级别关闭对应工具。

footer 字段说明：

| 子字段 | 默认值 | 说明 | |--------|--------|------| | status | false | 显示状态文本（"已完成"/"出错" 等） | | elapsed | false | 显示本次回复的耗时 |

markdown 字段说明：

| 子字段 | 取值 | 说明 | |--------|------|------| | tables | 'off' | 'bullets' | 'code' | 表格转换方式；off 不转换，bullets 转列表，code 转代码块 |

capabilities 字段说明：

| 子字段 | 说明 | |--------|------| | image | 是否接收图片消息 | | audio | 是否接收音频消息 | | video | 是否接收视频消息 |

uat 字段说明：

| 子字段 | 说明 | |--------|------| | enabled | 是否启用 UAT | | allowedScopes | 允许使用 UAT 的 OAuth scope 白名单 | | blockedScopes | 禁止使用 UAT 的 OAuth scope 黑名单 |

去重与事件

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | dedup | object | — | 消息去重配置（WebSocket 重连时可能重复投递） | | reactionNotifications | 'off' | 'own' | 'all' | — | 表情反应通知模式 | | threadSession | boolean | — | 话题（线程）消息是否使用独立 session | | heartbeat | object | — | 自动心跳：定时触发 AI 对话 |

dedup 字段说明：

| 子字段 | 默认值 | 说明 | |--------|--------|------| | ttlMs | 43200000（12 小时） | 去重记录保留时长（毫秒） | | maxEntries | 5000 | 最大跟踪条目数（FIFO 驱逐） |

reactionNotifications 说明：

| 值 | 行为 | |----|------| | 'off' | 不处理任何表情反应事件 | | 'own' | 仅处理 bot 自身消息上的反应 | | 'all' | 处理所有消息上的表情反应 |

heartbeat 字段说明：

| 子字段 | 说明 | |--------|------| | every | 触发频率，如 "5m" "1h" | | activeHours.start / .end | 仅在指定时间段内触发 | | activeHours.timezone | 时区，如 "Asia/Shanghai" | | target / to | 目标会话（群 chat_id 或用户 open_id） | | prompt | 心跳消息内容（作为用户消息发给 Agent） | | accountId | 多账号时指定使用哪个账号 |

⚙️ 后端自动填充字段

以下字段由后端自动填入，请勿手动配置：

| 字段 | 说明 | |------|------| | gatewayBaseUrl | AI 网关地址 | | gatewayToken | 网关鉴权 Bearer Token | | uploadHost | yuce-gpt 媒体上传地址 |

🔒 只读字段

以下字段由系统固定，用户不可修改：

| 字段 | 固定值 | 说明 | |------|--------|------| | separateSessionByConversation | true | 单聊和群聊使用各自独立的会话上下文 | | groupSessionScope | 'group' | 群内所有成员共享同一个 AI 会话上下文 |

多账号配置

accounts 字段允许在同一渠道下配置多个机器人账号，每个账号的配置结构与顶层配置相同（除 accounts 字段本身外），账号级配置会覆盖顶层配置：

{
  "channels": {
    "feishu": {
      "dmPolicy": "pairing",
      "accounts": {
        "bot1": {
          "appId": "cli_xxx",
          "appSecret": "xxx",
          "dmPolicy": "open",
          "allowFrom": ["*"]
        },
        "bot2": {
          "appId": "cli_yyy",
          "appSecret": "yyy",
          "groupPolicy": "allowlist",
          "groups": {
            "oc_zzz": { "enabled": true }
          }
        }
      }
    }
  }
}

贡献

我们欢迎社区的贡献！如果你发现 Bug 或有功能建议，请随时提交 Issue 或 Pull Request。

对于较大的改动，我们建议你先通过 Issue 与我们讨论。

许可证

本项目基于 MIT 许可证。详情请参阅 LICENSE 文件。