# OpenClaw  Lark/飞书 插件

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://img.shields.io/npm/v/@larksuite/openclaw-lark.svg)](https://www.npmjs.com/package/@larksuite/openclaw-lark)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D22-blue.svg)](https://nodejs.org/)

[English](./README.md) | 中文版

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

## 特性

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

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

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

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

**免责声明：**

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

- [飞书用户服务协议](https://www.feishu.cn/terms)
- [飞书隐私政策](https://www.feishu.cn/privacy)
- [飞书开放平台独立软件服务商安全管理运营规范](https://open.larkoffice.com/document/uAjLw4CM/uMzNwEjLzcDMx4yM3ATM/management-practice/app-service-provider-security-management-specifications)
- [Lark用户服务协议](https://www.larksuite.com/user-terms-of-service)
- [Lark隐私政策](https://www.larksuite.com/privacy-policy)

## 安装与要求

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

- **Node.js**: `v22` 或更高版本。
- **OpenClaw**: OpenClaw 已成功安装并可运行。详情请访问 [OpenClaw 官方网站](https://openclaw.ai)。

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

## 使用说明
[OpenClaw  Lark/飞书官方插件使用指南](https://bytedance.larkoffice.com/docx/MFK7dDFLFoVlOGxWCv5cTXKmnMh)

---

## 配置字段说明

以下为 `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 索引的对象，支持特殊键 `'*'` 作为所有群的默认配置：

```json
{
  "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 |

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

```json
{
  "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` 字段本身外），账号级配置会覆盖顶层配置：

```json
{
  "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](https://github.com/larksuite/openclaw-larksuite/issues) 或 [Pull Request](https://github.com/larksuite/openclaw-larksuite/pulls)。

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

## 许可证

本项目基于 **MIT 许可证**。详情请参阅 [LICENSE](./LICENSE.md) 文件。