OpenClaw 飞书插件技术原理：从 Bot Token 到 User Token 的架构全解

> 来源: 飞书官方博客 / GitHub / OpenClaw 文档 / 本地源码分析

> 发布时间: 2026-03-05（文章）/ 持续更新中

> 研究时间: 2026-03-29

🎯 一句话版本

飞书插件本质是一个"双身份"系统：OpenClaw 自带的内置插件以机器人身份收发消息，飞书官方插件（字节开发）在此基础上通过 OAuth Device Flow 获取用户的 Access Token，让 AI 能以"你的身份"读文档、发消息、改日历——相当于给龙虾多了一张你的工牌。

🏗️ 替换关系，不是叠加

⚠️ 关键事实：官方插件替换内置插件，不是叠加。

OpenClaw 有一个内置的飞书 channel（@openclaw/feishu，plugin id: feishu），随 OpenClaw 发布。但当你安装飞书官方插件（@larksuite/openclaw-lark）后，内置插件被禁用，官方插件接管一切。

源码和配置证据：

// openclaw.json 中的 plugins.entries
{
  "feishu": { "enabled": false },       // ← 内置插件被禁用
  "openclaw-lark": { "enabled": true }  // ← 官方插件启用
}

两者注册的 channel meta id 都是 'feishu'（源码 plugin.js → meta.id: 'feishu'），不能同时运行。

对比

官方插件是一个完整替代品：自己实现了 WebSocket 连接、消息收发、Bot 操作等全部基础功能，加上 OAuth 用户身份操作。不是在内置插件上面加一层，是独立重写了整个 channel。

安装前:                          安装后:
┌─────────────────────┐         ┌─────────────────────────────────┐
│  @openclaw/feishu   │         │  @larksuite/openclaw-lark       │
│  (内置, enabled)    │  ──→    │  (官方, enabled)                │
│  Bot 身份           │         │  Bot 身份 + User 身份 (OAuth)   │
│  基础工具           │         │  全部工具 + 诊断 + 流式卡片    │
└─────────────────────┘         └─────────────────────────────────┘
                                ┌─────────────────────┐
                                │  @openclaw/feishu   │
                                │  (内置, DISABLED)   │
                                └─────────────────────┘

🔐 OAuth Device Flow：核心授权原理

这是整个插件最关键的技术——如何让 AI 获得用户身份？

流程

基于 RFC 8628（OAuth 2.0 Device Authorization Grant）：

1. OpenClaw 向飞书请求 device_code + user_code
   POST accounts.feishu.cn/oauth/v1/device_authorization

2. 用户在飞书客户端扫码或输入 user_code 授权

3. OpenClaw 轮询 token 端点直到授权完成
   POST open.feishu.cn/open-apis/authen/v2/oauth/token

4. 获得 User Access Token (UAT) + Refresh Token

5. Token 加密存储到本地

为什么用 Device Flow 而不是普通 OAuth？

因为 OpenClaw 运行在终端/服务器上，没有浏览器回调 URL。Device Flow 专为"无浏览器设备"设计——用户在手机/电脑上扫码授权，服务端轮询拿 token。

Token 安全存储

• Service name: openclaw-feishu-uat
• Account key: {appId}:{userOpenId}
• 提前 5 分钟自动刷新 access_token（REFRESH_AHEAD_MS = 5 60 1000）

这意味着用户一次授权后，OpenClaw 能持续使用用户身份，直到用户主动撤销。

🔧 工具层架构

官方插件注册了两套工具：

`oapi/` — 以用户身份调用

`tat/` — 以机器人身份调用

Agent 调用时透明切换身份：当 AI 需要"读群消息"时，工具自动使用用户的 UAT；当 AI 需要"发 bot 消息"时，使用租户的 Tenant Token。用户无感。

🛡️ 权限体系

两套权限范围

租户权限（18 个）：机器人基础操作

im:message:send_as_bot, im:resource, im:message:readonly,
cardkit:card:write, contact:user.employee_id:readonly ...

用户权限（70+ 个）：用户身份操作

docx:document:create, calendar:calendar.event:create,
base:record:create, im:message:readonly, task:task:write,
wiki:node:create, drive:file:upload, search:message ...

安全机制

1. Scope Manager（scope-manager.js）— 运行时检查每个 API 调用是否在授权范围内

2. Owner Policy（owner-policy.js）— 限制谁能触发敏感操作

3. Security Check（security-check.js）— 操作前安全校验

4. App Scope Checker（app-scope-checker.js）— 检查应用是否有所需权限

5. 卡片确认按钮（card-ux-approval.js）— 敏感操作要用户点"确认"

📡 消息流全链路

用户在飞书发消息
    ↓
飞书 WebSocket → OpenClaw Gateway 接收
    ↓
内置 Channel 解析消息 → 路由到 Session
    ↓
LLM 生成回复（可能调用工具）
    ↓
需要用户身份？→ 官方插件用 UAT 调飞书 API
需要 Bot 身份？→ 内置插件用 Tenant Token
    ↓
结果回传给 LLM → 生成最终回复
    ↓
通过飞书卡片/文本消息返回用户
（支持流式：Thinking → Generating → Complete）

⚙️ 关键配置

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_xxx",
      "appSecret": "xxx",
      "dmPolicy": "pairing",         // 首次需配对验证
      "groupPolicy": "allowlist",     // 群聊白名单
      "requireMention": true,         // 需 @ 机器人
      "streaming": true,              // 流式输出
      "threadSession": true           // 话题独立上下文
    }
  }
}

快捷命令

💡 与我们的关联

1. 我们正在使用官方插件

我们的 OpenClaw 配置中，内置 feishu 插件已被禁用，openclaw-lark（v2026.3.17）已启用。所以我们当前的飞书工具调用（日历、消息、多维表格等）全部由官方插件提供：Bot 身份消息收发 + 用户身份 API 调用。

2. 安全启示

Token 存储用 AES-256-GCM 加密是好的，但关键风险在于：一旦 OpenClaw 进程被入侵，加密密钥和 token 都可获取。文章明确建议"先用个人账号玩，别接入真实工作环境"——这个警告是认真的。

3. 多 Agent 玩法

支持一个 OpenClaw 关联多个飞书机器人 → 对应不同 Agent。比如一个机器人做研究助手，一个做日程管理，各有独立上下文和 skill 配置。

4. 飞书 vs 其他渠道的优势

飞书官方插件提供了最丰富的工具集（70+ 用户权限），远超 Telegram/Discord。这是因为飞书开放平台团队亲自做的——他们能给自己开最多的 API。

📊 评分

报告由深度研究助手自动生成 | 2026-03-29

来源: 飞书博客 / GitHub / OpenClaw 文档 / 本地源码 ~/.openclaw/extensions/openclaw-lark/