WorkBuddy 接入飞书指南

文章目录


文章概述

本文面向有飞书企业账号的开发者与 AI 工具用户,聚焦飞书开放平台项目级接入,不仅涵盖自建应用创建、机器人配置、权限与事件回调等核心流程,还深入讲解飞书 CLI 接入与 AI 托管、飞书项目(Feishu Project)的 CLI + MCP + AAMP 能力,帮助读者快速掌握飞书接入与 AI 自动化全流程。

学习目标

学完本文,你将能够:

  • 独立完成飞书自建应用的创建、权限配置、事件回调与发布全流程
  • 理解 WebSocket 长连接与 URL 回调两种模式的原理差异,并能按场景选型
  • 分清 tenant 与 user 两类权限的作用范围,避免「权限不足」类报错
  • 使用飞书 CLI 让 AI 智能体托管消息、文档、日历等日常飞书任务
  • 了解飞书项目(Feishu Project)面向 AI 的 CLI + MCP + AAMP 接入能力

适合读者与前置知识

项目 说明
适合人群 有飞书企业账号的开发者、AI 工具用户、效率工具爱好者
前置知识 会基本的终端命令操作;了解 JSON 格式即可,无需后端开发经验
环境要求 一台联网电脑(Windows / macOS / Linux 均可)、Node.js 16+(仅 CLI 章节需要)
预计阅读时长 约 25 分钟,跟着实操约 1 小时

相关内容

#mermaid-svg-d58qsbcrd4sA86Bc{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-d58qsbcrd4sA86Bc .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-d58qsbcrd4sA86Bc .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-d58qsbcrd4sA86Bc .error-icon{fill:#552222;}#mermaid-svg-d58qsbcrd4sA86Bc .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-d58qsbcrd4sA86Bc .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-d58qsbcrd4sA86Bc .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-d58qsbcrd4sA86Bc .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-d58qsbcrd4sA86Bc .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-d58qsbcrd4sA86Bc .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-d58qsbcrd4sA86Bc .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-d58qsbcrd4sA86Bc .marker{fill:#333333;stroke:#333333;}#mermaid-svg-d58qsbcrd4sA86Bc .marker.cross{stroke:#333333;}#mermaid-svg-d58qsbcrd4sA86Bc svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-d58qsbcrd4sA86Bc p{margin:0;}#mermaid-svg-d58qsbcrd4sA86Bc .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-d58qsbcrd4sA86Bc .cluster-label text{fill:#333;}#mermaid-svg-d58qsbcrd4sA86Bc .cluster-label span{color:#333;}#mermaid-svg-d58qsbcrd4sA86Bc .cluster-label span p{background-color:transparent;}#mermaid-svg-d58qsbcrd4sA86Bc .label text,#mermaid-svg-d58qsbcrd4sA86Bc span{fill:#333;color:#333;}#mermaid-svg-d58qsbcrd4sA86Bc .node rect,#mermaid-svg-d58qsbcrd4sA86Bc .node circle,#mermaid-svg-d58qsbcrd4sA86Bc .node ellipse,#mermaid-svg-d58qsbcrd4sA86Bc .node polygon,#mermaid-svg-d58qsbcrd4sA86Bc .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-d58qsbcrd4sA86Bc .rough-node .label text,#mermaid-svg-d58qsbcrd4sA86Bc .node .label text,#mermaid-svg-d58qsbcrd4sA86Bc .image-shape .label,#mermaid-svg-d58qsbcrd4sA86Bc .icon-shape .label{text-anchor:middle;}#mermaid-svg-d58qsbcrd4sA86Bc .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-d58qsbcrd4sA86Bc .rough-node .label,#mermaid-svg-d58qsbcrd4sA86Bc .node .label,#mermaid-svg-d58qsbcrd4sA86Bc .image-shape .label,#mermaid-svg-d58qsbcrd4sA86Bc .icon-shape .label{text-align:center;}#mermaid-svg-d58qsbcrd4sA86Bc .node.clickable{cursor:pointer;}#mermaid-svg-d58qsbcrd4sA86Bc .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-d58qsbcrd4sA86Bc .arrowheadPath{fill:#333333;}#mermaid-svg-d58qsbcrd4sA86Bc .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-d58qsbcrd4sA86Bc .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-d58qsbcrd4sA86Bc .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-d58qsbcrd4sA86Bc .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-d58qsbcrd4sA86Bc .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-d58qsbcrd4sA86Bc .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-d58qsbcrd4sA86Bc .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-d58qsbcrd4sA86Bc .cluster text{fill:#333;}#mermaid-svg-d58qsbcrd4sA86Bc .cluster span{color:#333;}#mermaid-svg-d58qsbcrd4sA86Bc div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-d58qsbcrd4sA86Bc .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-d58qsbcrd4sA86Bc rect.text{fill:none;stroke-width:0;}#mermaid-svg-d58qsbcrd4sA86Bc .icon-shape,#mermaid-svg-d58qsbcrd4sA86Bc .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-d58qsbcrd4sA86Bc .icon-shape p,#mermaid-svg-d58qsbcrd4sA86Bc .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-d58qsbcrd4sA86Bc .icon-shape .label rect,#mermaid-svg-d58qsbcrd4sA86Bc .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-d58qsbcrd4sA86Bc .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-d58qsbcrd4sA86Bc .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-d58qsbcrd4sA86Bc :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 飞书接入实战
基础接入
CLI 与 AI 托管
运维保障
前提条件和接入流程概览
创建飞书应用
添加机器人能力
配置应用权限
获取应用凭证
在WorkBuddy中配置飞书
配置飞书事件回调
发布应用
开始使用
飞书CLI安装与配置
登录认证和三层命令架构
AI智能体集成和托管场景
飞书项目CLI+MCP+AAMP
常见问题排查
安全注意事项

1、前提条件

在开始之前,请确保满足以下条件:

1.1、电脑端要求

  • 已在电脑上安装 WorkBuddy,并开启了 助理 远程控制功能
  • 电脑需保持开机且联网状态(远程控制期间)
  • WorkBuddy 客户端保持登录、处于前台或后台运行状态均可

1.2、飞书账号要求

  • 拥有一个飞书企业账号
  • 该账号需要具备创建企业自建应用的权限(一般企业成员即可,具体取决于企业管理员的开放策略)

1.3、网络要求

  • 电脑能正常访问飞书开放平台(open.feishu.cn
  • 若选择 URL 回调 模式,还需要电脑/服务器具备公网 IP 或已配置内网穿透

2、整体接入流程概览

接入过程共 8 个步骤,按顺序完成后即可使用:

复制代码
创建飞书应用 → 添加机器人能力 → 配置应用权限 → 获取应用凭证
     → WorkBuddy 中填写凭证并注册 → 配置飞书事件回调 → 发布应用 → 开始使用

2.1、两种连接模式对比

WorkBuddy 提供两种连接方式,请根据自身情况选择其一:

对比项 WebSocket 长连接模式 URL 回调模式
适用人群 个人 / 家庭 / 办公室用户 有服务器、有公网 IP 的用户
是否需要公网 IP ❌ 不需要 ✅ 需要
配置复杂度 简单,开箱即用 较复杂,需填写 Webhook 地址
稳定性 依赖本地网络长连接 依赖服务器稳定性
推荐场景 绝大多数个人用户 企业自建服务器、需要集中管理

💡 建议 :绝大多数个人用户直接选择 WebSocket 长连接模式 即可,无需服务器和公网 IP。

2.2、原理解析:两种模式为什么不同?

很多初学者会疑惑:同样是接收飞书消息,为什么一个要公网 IP、一个不要?关键在于**「谁主动找谁」**:

  • URL 回调(Webhook):飞书服务器是「主动方」。用户发消息 → 飞书服务器向你填写的 Webhook 地址发起 HTTP 请求推送事件。这要求你的电脑/服务器必须能被飞书从公网访问到,因此需要公网 IP 或内网穿透。
  • WebSocket 长连接:你的电脑是「主动方」。WorkBuddy 主动向飞书服务器发起一条长连接并保持不断开,事件通过这条连接「顺流而下」推送到本地。因为连接是你主动建立的,所以不需要公网 IP。

#mermaid-svg-COFL4M8VbUSqjv8q{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-COFL4M8VbUSqjv8q .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-COFL4M8VbUSqjv8q .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-COFL4M8VbUSqjv8q .error-icon{fill:#552222;}#mermaid-svg-COFL4M8VbUSqjv8q .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-COFL4M8VbUSqjv8q .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-COFL4M8VbUSqjv8q .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-COFL4M8VbUSqjv8q .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-COFL4M8VbUSqjv8q .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-COFL4M8VbUSqjv8q .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-COFL4M8VbUSqjv8q .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-COFL4M8VbUSqjv8q .marker{fill:#333333;stroke:#333333;}#mermaid-svg-COFL4M8VbUSqjv8q .marker.cross{stroke:#333333;}#mermaid-svg-COFL4M8VbUSqjv8q svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-COFL4M8VbUSqjv8q p{margin:0;}#mermaid-svg-COFL4M8VbUSqjv8q .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-COFL4M8VbUSqjv8q .cluster-label text{fill:#333;}#mermaid-svg-COFL4M8VbUSqjv8q .cluster-label span{color:#333;}#mermaid-svg-COFL4M8VbUSqjv8q .cluster-label span p{background-color:transparent;}#mermaid-svg-COFL4M8VbUSqjv8q .label text,#mermaid-svg-COFL4M8VbUSqjv8q span{fill:#333;color:#333;}#mermaid-svg-COFL4M8VbUSqjv8q .node rect,#mermaid-svg-COFL4M8VbUSqjv8q .node circle,#mermaid-svg-COFL4M8VbUSqjv8q .node ellipse,#mermaid-svg-COFL4M8VbUSqjv8q .node polygon,#mermaid-svg-COFL4M8VbUSqjv8q .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-COFL4M8VbUSqjv8q .rough-node .label text,#mermaid-svg-COFL4M8VbUSqjv8q .node .label text,#mermaid-svg-COFL4M8VbUSqjv8q .image-shape .label,#mermaid-svg-COFL4M8VbUSqjv8q .icon-shape .label{text-anchor:middle;}#mermaid-svg-COFL4M8VbUSqjv8q .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-COFL4M8VbUSqjv8q .rough-node .label,#mermaid-svg-COFL4M8VbUSqjv8q .node .label,#mermaid-svg-COFL4M8VbUSqjv8q .image-shape .label,#mermaid-svg-COFL4M8VbUSqjv8q .icon-shape .label{text-align:center;}#mermaid-svg-COFL4M8VbUSqjv8q .node.clickable{cursor:pointer;}#mermaid-svg-COFL4M8VbUSqjv8q .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-COFL4M8VbUSqjv8q .arrowheadPath{fill:#333333;}#mermaid-svg-COFL4M8VbUSqjv8q .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-COFL4M8VbUSqjv8q .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-COFL4M8VbUSqjv8q .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-COFL4M8VbUSqjv8q .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-COFL4M8VbUSqjv8q .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-COFL4M8VbUSqjv8q .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-COFL4M8VbUSqjv8q .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-COFL4M8VbUSqjv8q .cluster text{fill:#333;}#mermaid-svg-COFL4M8VbUSqjv8q .cluster span{color:#333;}#mermaid-svg-COFL4M8VbUSqjv8q div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-COFL4M8VbUSqjv8q .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-COFL4M8VbUSqjv8q rect.text{fill:none;stroke-width:0;}#mermaid-svg-COFL4M8VbUSqjv8q .icon-shape,#mermaid-svg-COFL4M8VbUSqjv8q .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-COFL4M8VbUSqjv8q .icon-shape p,#mermaid-svg-COFL4M8VbUSqjv8q .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-COFL4M8VbUSqjv8q .icon-shape .label rect,#mermaid-svg-COFL4M8VbUSqjv8q .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-COFL4M8VbUSqjv8q .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-COFL4M8VbUSqjv8q .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-COFL4M8VbUSqjv8q :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} WebSocket长连接模式
沿已有连接下发
主动建立并保持连接
用户发消息
飞书服务器
你的电脑
URL回调模式
HTTP POST 推送
用户发消息
飞书服务器
你的公网服务器

3、创建飞书应用

3.1、登录开发者后台

打开浏览器,访问 飞书开放平台,使用企业账号登录。

3.2、创建企业自建应用

登录后,在首页或「应用」页面中,点击「创建企业自建应用」按钮。

💡 说明:企业自建应用仅在你自己所在的企业内部可用,无需上架飞书应用商店,配置后即可使用。

3.3、填写应用信息

在弹出的创建窗口中填写:

配置项 说明
应用名称 给应用起个名字,如「WorkBuddy 助手」
应用描述 简单描述应用的功能,如「远程控制 WorkBuddy 完成编程任务」
应用图标 上传一个应用图标(可选,但建议上传便于识别)

填写完成后,点击「创建」按钮。

3.4、进入应用详情

应用创建成功后,会自动跳转到应用详情页面。后续所有配置都在这个页面完成。

4、添加机器人能力

在应用详情页的「添加应用能力 」区域,找到「机器人 」卡片,点击「添加」按钮。

添加成功后,「机器人」卡片会显示为已启用状态。机器人能力是接收和回复飞书消息的基础,必须添加。

5、配置应用权限

为了让机器人能够正常收发消息、操作文档等,需要为应用添加必要的权限。

5.1、进入权限管理

在应用详情页左侧菜单中,点击「权限管理 」,然后选择「批量导入 / 导出权限」。

5.2、批量导入权限

在弹出的窗口中按以下步骤操作:

  1. 清空输入框中的所有内容
  2. 将下方的权限列表完整复制并粘贴进去
  3. 点击「确定新增权限

需要导入的权限列表:

json 复制代码
{
  "scopes": {
    "tenant": [
      "contact:contact.base:readonly",
      "docx:document:readonly",
      "im:chat:read",
      "im:chat:update",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message.pins:read",
      "im:message.pins:write_only",
      "im:message.reactions:read",
      "im:message.reactions:write_only",
      "im:message:readonly",
      "im:message:recall",
      "im:message:send_as_bot",
      "im:message:send_multi_users",
      "im:message:send_sys_msg",
      "im:message:update",
      "im:resource",
      "application:application:self_manage",
      "cardkit:card:write",
      "cardkit:card:read"
    ],
    "user": [
      "contact:user.employee_id:readonly",
      "offline_access",
      "base:app:copy",
      "base:field:create",
      "base:field:delete",
      "base:field:read",
      "base:field:update",
      "base:record:create",
      "base:record:delete",
      "base:record:retrieve",
      "base:record:update",
      "base:table:create",
      "base:table:delete",
      "base:table:read",
      "base:table:update",
      "base:view:read",
      "base:view:write_only",
      "base:app:create",
      "base:app:update",
      "base:app:read",
      "board:whiteboard:node:create",
      "board:whiteboard:node:read",
      "calendar:calendar:read",
      "calendar:calendar.event:create",
      "calendar:calendar.event:delete",
      "calendar:calendar.event:read",
      "calendar:calendar.event:reply",
      "calendar:calendar.event:update",
      "calendar:calendar.free_busy:read",
      "contact:contact.base:readonly",
      "contact:user.base:readonly",
      "contact:user:search",
      "docs:document.comment:create",
      "docs:document.comment:read",
      "docs:document.comment:update",
      "docs:document.media:download",
      "docs:document:copy",
      "docx:document:create",
      "docx:document:readonly",
      "docx:document:write_only",
      "drive:drive.metadata:readonly",
      "drive:file:download",
      "drive:file:upload",
      "im:chat.members:read",
      "im:chat:read",
      "im:message",
      "im:message.group_msg:get_as_user",
      "im:message.p2p_msg:get_as_user",
      "im:message:readonly",
      "search:docs:read",
      "search:message",
      "space:document:delete",
      "space:document:move",
      "space:document:retrieve",
      "task:comment:read",
      "task:comment:write",
      "task:task:read",
      "task:task:write",
      "task:task:writeonly",
      "task:tasklist:read",
      "task:tasklist:write",
      "wiki:node:copy",
      "wiki:node:create",
      "wiki:node:move",
      "wiki:node:read",
      "wiki:node:retrieve",
      "wiki:space:read",
      "wiki:space:retrieve",
      "wiki:space:write_only"
    ]
  }
}

等待几秒钟,页面会显示权限已成功添加。

5.3、权限说明

上述权限覆盖了 WorkBuddy 机器人的核心能力,主要用途如下:

权限类别 用途说明
im:message 系列 收发消息、接收用户发送的消息事件
im:chat 系列 读取群聊、群成员信息
contact 系列 获取用户、部门通讯录信息
docx / docs / drive 系列 读写文档、云空间文件
base 系列 操作多维表格(数据表)
calendar 系列 读取和创建日程
task 系列 读写任务
wiki 系列 操作知识库
board 系列 操作白板
search 系列 搜索文档和消息
cardkit 系列 卡片回调与交互

⚠️ 注意 :以上为完整能力所需的权限集合。如果只想实现基础的消息收发,至少需要 im:messageim:message:readonlyim:chat:read 等消息相关权限。

5.4、原理解析:tenant 和 user 权限有什么区别?

仔细观察上面的权限 JSON,会发现权限被分成了 tenantuser 两组,这是初学者最容易混淆的地方:

对比项 tenant(应用身份) user(用户身份)
调用时使用的凭证 App ID + App Secret 换取的 tenant_access_token 用户授权后得到的 user_access_token
数据范围 只能访问「应用被授权的企业级数据」,如机器人所在群的消息 可访问「该用户本人有权访问的数据」,如他的日历、文档
典型场景 机器人收发群消息、回复用户 以用户名义读日程、创建文档、操作多维表格
是否需要用户授权 不需要,应用发布即可用 需要用户完成 OAuth 授权

一句话记忆tenant 是「机器人自己能干什么」,user 是「机器人代替你能干什么」。

📌 本节小结:排查「权限不足」报错时,先确认接口要求的是 tenant 还是 user 权限,再检查对应分组里是否已导入该权限、应用是否已重新发布。

6、获取应用凭证

6.1、查看凭证信息(App ID 与 App Secret)

在应用详情页左侧菜单中,点击「凭证与基础信息」,会看到两个重要凭证:

  • App ID :应用的唯一标识(cli_ 开头的一串字符)
  • App Secret:应用的密钥(点击「查看」按钮后可见)

⚠️ 重要:请务必妥善保管 App Secret,不要泄露给他人!泄露后他人可冒用你的应用身份调用接口。

6.2、获取 Encrypt Key 和 Verification Token

在应用详情页左侧菜单中,点击「事件与回调」,在右侧页面中选择加密策略。

可以点击刷新按钮自动生成,或点击编辑按钮自定义 Encrypt Key 和 Verification Token。

  • Encrypt Key:用于消息内容的加密解密
  • Verification Token:用于校验回调请求的合法性

⚠️ 重要:请务必妥善保管 Encrypt Key 和 Verification Token,不要泄露给他人!

7、在 WorkBuddy 中配置飞书

现在,需要将凭证配置到 WorkBuddy 中,让它能够与飞书通信。

7.1、进入配置页面

在 WorkBuddy 中,点击助理的设置⚙️ 图标后进入助理设置 ,找到飞书集成开始配置。

7.2、填写凭证

将刚才获取的 App IDApp Secret 以及 Encrypt Key 填入对应的输入框。

7.3、选择连接模式并注册

根据自身情况选择以下两种模式之一:

模式一:WebSocket 长连接(推荐)

  • 适用于个人 / 家庭 / 办公室用户(没有公网 IP)
  • 配置更简单,不需要公网地址,开箱即用
  • 操作:选择「WebSocket 长连接 」→ 点击「注册 」按钮 → 配置成功显示已连接

模式二:使用 URL 回调

  • 适用于有服务器、有公网 IP 的用户
  • 需要额外在飞书开放平台填写生成的 Webhook 地址
  • 操作:选择「使用 URL 回调 」→ 点击「注册」按钮 → 系统会生成一个 Webhook 地址 → 点击复制保存

8、配置飞书事件回调

接下来,需要告诉飞书将消息发送到哪里。

8.1、配置事件订阅

返回飞书开放平台,进入应用详情页,在左侧菜单点击「事件与回调」。

  • WebSocket 长连接 :在「订阅方式」中选择「使用长连接接收事件 」,点击「验证」,配置成功显示「连接成功」。
  • 使用 URL 回调 :在「订阅方式」中选择「将事件发送至开发者服务器 」,将复制的 Webhook 地址粘贴到输入框中,点击「保存」。

8.2、添加消息接收事件

在「事件配置 」区域,点击「添加事件 」,搜索并添加「接收消息 」事件(对应 im.message.receive_v1)。

💡 说明:添加「接收消息」事件后,机器人才能收到用户发送的消息并响应。

8.3、配置卡片回调

  1. 切换到「回调配置」页签
  2. 搜索「卡片回传交互 」(对应 card.action.trigger
  3. 点击「确认添加

💡 说明:配置卡片回调后,用户点击机器人消息中的按钮、下拉框等交互组件时,WorkBuddy 才能收到对应的操作。

8.4、原理解析:事件是如何流转的?

配置完成后,一条消息的完整生命周期如下,理解它有助于后续排查问题:
#mermaid-svg-Fj2nKAksFlGMn6FQ{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-Fj2nKAksFlGMn6FQ .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-Fj2nKAksFlGMn6FQ .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-Fj2nKAksFlGMn6FQ .error-icon{fill:#552222;}#mermaid-svg-Fj2nKAksFlGMn6FQ .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-Fj2nKAksFlGMn6FQ .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-Fj2nKAksFlGMn6FQ .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-Fj2nKAksFlGMn6FQ .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-Fj2nKAksFlGMn6FQ .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-Fj2nKAksFlGMn6FQ .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-Fj2nKAksFlGMn6FQ .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-Fj2nKAksFlGMn6FQ .marker{fill:#333333;stroke:#333333;}#mermaid-svg-Fj2nKAksFlGMn6FQ .marker.cross{stroke:#333333;}#mermaid-svg-Fj2nKAksFlGMn6FQ svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-Fj2nKAksFlGMn6FQ p{margin:0;}#mermaid-svg-Fj2nKAksFlGMn6FQ .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-Fj2nKAksFlGMn6FQ .cluster-label text{fill:#333;}#mermaid-svg-Fj2nKAksFlGMn6FQ .cluster-label span{color:#333;}#mermaid-svg-Fj2nKAksFlGMn6FQ .cluster-label span p{background-color:transparent;}#mermaid-svg-Fj2nKAksFlGMn6FQ .label text,#mermaid-svg-Fj2nKAksFlGMn6FQ span{fill:#333;color:#333;}#mermaid-svg-Fj2nKAksFlGMn6FQ .node rect,#mermaid-svg-Fj2nKAksFlGMn6FQ .node circle,#mermaid-svg-Fj2nKAksFlGMn6FQ .node ellipse,#mermaid-svg-Fj2nKAksFlGMn6FQ .node polygon,#mermaid-svg-Fj2nKAksFlGMn6FQ .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Fj2nKAksFlGMn6FQ .rough-node .label text,#mermaid-svg-Fj2nKAksFlGMn6FQ .node .label text,#mermaid-svg-Fj2nKAksFlGMn6FQ .image-shape .label,#mermaid-svg-Fj2nKAksFlGMn6FQ .icon-shape .label{text-anchor:middle;}#mermaid-svg-Fj2nKAksFlGMn6FQ .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-Fj2nKAksFlGMn6FQ .rough-node .label,#mermaid-svg-Fj2nKAksFlGMn6FQ .node .label,#mermaid-svg-Fj2nKAksFlGMn6FQ .image-shape .label,#mermaid-svg-Fj2nKAksFlGMn6FQ .icon-shape .label{text-align:center;}#mermaid-svg-Fj2nKAksFlGMn6FQ .node.clickable{cursor:pointer;}#mermaid-svg-Fj2nKAksFlGMn6FQ .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-Fj2nKAksFlGMn6FQ .arrowheadPath{fill:#333333;}#mermaid-svg-Fj2nKAksFlGMn6FQ .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-Fj2nKAksFlGMn6FQ .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-Fj2nKAksFlGMn6FQ .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Fj2nKAksFlGMn6FQ .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-Fj2nKAksFlGMn6FQ .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Fj2nKAksFlGMn6FQ .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-Fj2nKAksFlGMn6FQ .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-Fj2nKAksFlGMn6FQ .cluster text{fill:#333;}#mermaid-svg-Fj2nKAksFlGMn6FQ .cluster span{color:#333;}#mermaid-svg-Fj2nKAksFlGMn6FQ div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-Fj2nKAksFlGMn6FQ .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-Fj2nKAksFlGMn6FQ rect.text{fill:none;stroke-width:0;}#mermaid-svg-Fj2nKAksFlGMn6FQ .icon-shape,#mermaid-svg-Fj2nKAksFlGMn6FQ .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Fj2nKAksFlGMn6FQ .icon-shape p,#mermaid-svg-Fj2nKAksFlGMn6FQ .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-Fj2nKAksFlGMn6FQ .icon-shape .label rect,#mermaid-svg-Fj2nKAksFlGMn6FQ .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Fj2nKAksFlGMn6FQ .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-Fj2nKAksFlGMn6FQ .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-Fj2nKAksFlGMn6FQ :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 匹配订阅的事件类型
im.message.receive_v1
card.action.trigger
处理任务并调用发送接口
消息推送给用户
用户在飞书发消息
飞书服务器
事件分发
WorkBuddy

三个关键概念:

  • 事件(Event):飞书侧发生的动作,如「收到消息」「卡片被点击」,每个事件有唯一标识
  • 订阅(Subscription):告诉飞书「我关心哪些事件」,没订阅的事件不会推送
  • 回调(Callback):飞书把事件推送给你填写的接收方(长连接或 Webhook)

📌 本节小结:收不到消息时,按「事件是否添加 → 订阅方式是否验证通过 → 连接是否存活」的顺序排查,可定位 90% 的问题。

9、发布应用

应用必须发布后才能在飞书中使用。

9.1、创建版本

点击页面上方的「创建版本」按钮,在弹出的窗口中填写:

配置项 示例
版本号 1.0.0
版本描述 首次发布,集成 WorkBuddy

点击「确定」创建版本。

9.2、发布版本

创建成功后,点击版本右侧的「发布」按钮。

💡 提示:如果您是企业管理员,应用通常会自动审批通过。如果需要审批,请联系您的企业管理员。

9.3、设置应用可用范围(可选)

发布后,可以在「应用可用范围」中设置哪些部门或成员可以使用该应用:

  • 默认情况下,企业内所有成员可见
  • 如需限制,可指定特定部门或成员
  • 仅被纳入可用范围的成员才能在飞书中搜索到并对话该机器人

10、开始使用

10.1、找到机器人

在飞书的搜索框中,输入刚才创建的机器人名称进行搜索。

10.2、开始对话

点击机器人进入对话窗口,或者点击「打开应用」开始使用。

10.3、发送任务

直接发送你的需求,比如「帮我写一个待办事项应用」。WorkBuddy 会在电脑上自动执行任务,并将结果返回给你。

10.4、常用使用场景

场景 示例指令
编写代码 「帮我写一个登录功能」
修复 Bug 「这段代码报错了,帮我看看」
代码解释 「解释一下这个函数的作用」
生成文档 「帮我写一份接口文档」
数据处理 「帮我整理这份 Excel 数据」

🎉 恭喜:你已成功将 WorkBuddy 接入飞书!现在可以通过飞书随时随地远程控制 WorkBuddy 完成各种编程任务了。

11、飞书 CLI 接入与 AI 托管

除前面介绍的「WorkBuddy 机器人」接入方式外,飞书官方还提供了开源的命令行工具------飞书 CLI,可以让 AI 智能体(Agent)直接接管并自动执行飞书上的各类任务,实现「AI 托管」。

11.1、什么是飞书 CLI

飞书 CLI(命令名 lark-cli,npm 包名 @larksuite/cli,开源仓库 larksuite/cli)是飞书开放平台官方开源的命令行工具,专为 AI Agent 与开发者设计,让 AI 从「只能提建议」升级为「能直接执行操作」。

核心能力一览:

维度 说明
业务覆盖 11 大业务领域:即时消息、云文档、多维表格、日历、邮件、任务、云空间、电子表格、知识库、会议、通讯录
命令规模 200+ CLI 命令、2500+ API 端点
内置 Skills 19 个 AI Agent 技能(Skills)
支持工具 Claude Code、Cursor、Codex、Trae、OpenCode 等 AI 编程/智能体工具
安全设计 输入注入防护、写操作 --dry-run 预览、最小权限范围控制

11.2、前置要求

  • 已安装 Node.js 16 或更高版本
  • 支持 macOS、Linux、Windows(x64 与 arm64)
  • 已在飞书开放平台创建自建应用,并获取 App ID 和 App Secret(参考本文第 3~6 章)

11.3、安装与配置

在终端中执行以下命令:

bash 复制代码
# 全局安装飞书 CLI
npm install -g @larksuite/cli

# 安装全部 19 个 AI Agent Skills
npx skills add larksuite/cli -y -g

# 初始化应用凭证
lark-cli config init

# 使用推荐的最小权限登录
lark-cli auth login --recommend

# 验证安装与认证状态
lark-cli auth status
lark-cli doctor

也可使用快速安装命令:

bash 复制代码
npx @larksuite/cli@latest install

💡 提示:也可以直接在 AI 工具中发送指令让 AI 自动安装,例如:「帮我安装飞书 CLI: https://open.feishu.cn/document/no_class/mcp-archive/feishu-cli-installation-guide.md」

11.4、登录认证

飞书 CLI 采用 OAuth 2.0 设备流认证

  1. 执行 lark-cli auth login,终端会输出一个浏览器授权 URL
  2. 在浏览器中打开并完成授权
  3. 凭证使用操作系统原生密钥链加密保存(macOS 钥匙串 / Windows 凭据管理器 / Linux Secret Service),不以明文存储

两种工作模式:

模式 说明
不授权,直接使用 AI 可执行发消息、建文档等操作,但无法访问个人数据(日程、私信、收件箱)
以你的身份操作 AI 可访问你的日历、消息、文档并以你的名义执行操作,需完成一次用户授权

为什么用设备流而不是直接填账号密码?

设备流(Device Flow)是专为命令行工具设计的授权方式:CLI 本身不接触你的飞书密码,授权动作全部在浏览器中由飞书官方页面完成,CLI 只拿到一个有时效、可撤销的访问令牌。这样即使 CLI 配置文件泄露,也不会波及账号密码,且你可以随时在飞书后台撤销授权。

11.5、三层命令架构

层级 说明 示例
快捷命令 + 前缀,适合人类与 AI,具备智能默认值 lark-cli im +messages-send --chat-id "oc_xxx" --text "你好"
API 命令 100+ 精选命令,与 API 端点一一对应 lark-cli calendar events instance_view --params '{...}'
原始 API 直接调用 2500+ API 端点 lark-cli api GET /open-apis/calendar/v4/calendars

常用快捷命令示例:

bash 复制代码
lark-cli calendar +agenda                                  # 查看日程
lark-cli docs +create --title "周报" --markdown "# 进展\n- 完成 X"   # 创建云文档
lark-cli task +get-my-tasks                                # 获取我的任务
lark-cli im +messages-send --chat-id "oc_xxx" --text "Hello"        # 发送消息

11.6、AI 智能体集成

安装 Skills 后,在 AI 工具中即可用自然语言让 AI 托管飞书任务,例如:

text 复制代码
根据我的所在部门、飞书消息、云文档、日程等信息,帮我创建一篇个人使用说明文档。
text 复制代码
帮我看一下【XX】群里所有人的日历,下周找一个大家都合适的时间开一小时讨论会。
text 复制代码
拉取我过去两周的日历,把每个日程分类打标,写入多维表格,然后做一个仪表盘,看时间花在哪里。

11.7、AI 托管自动化场景示例

场景 说明
会后待办提取 从会议妙记中识别待办事项,自动发送文档、创建会议、查找资料
人机共创文档 AI 起草、用户评论把关,或用户起草、AI 审稿并提修改意见
跨时区智能约会 自动查群成员空闲时间、考虑时区,推荐会议时间
会议审计仪表盘 拉取日历数据,自动打标签并生成多维表格仪表盘
未读邮件分类 按优先级分类,重要邮件摘要推送到群聊,自动起草回复

11.8、飞书项目(Feishu Project)的 CLI + MCP + AAMP

如果你在使用飞书项目(项目管理产品),飞书项目在 2026 年生态日发布了面向 AI 时代的接入能力,实现「从对人开放到对 AI 开放」:

能力 说明
飞书项目 CLI 让 Agent 对项目数据进行安全读写,胜任深度分析与批量操作
MCP 能力 升级版,与 CLI 共同完善 Agent 接入方式
AAMP 开源协议 基于标准邮件机制的异步通讯,让平台与个人 Agent 互联互通
AI 节点 把 Agent 配置为流程节点,让 AI 在关键业务节点自动「干活」
AI 字段 沉淀指令与最佳实践,方便随手调用
原生 AI 助手 开箱即用的项目分析、图表生成、进展追踪、风险洞察

💡 说明:飞书项目 CLI 与 AAMP 协议的具体命令与接入文档,可查阅飞书项目开放平台官网文档。
📌 本节小结:飞书 CLI 的学习路径是「安装 → 登录 → 快捷命令 → Skills 自然语言托管」。日常使用中,优先用自然语言描述需求让 AI 自行选择命令,比死记命令更高效。

12、常见问题排查

12.1、机器人没有响应怎么办?

请按以下步骤排查:

  1. 检查应用状态:确认应用已成功发布,且版本已生效
  2. 检查 WorkBuddy:确保电脑上的 WorkBuddy 正在运行,且助理服务已开启
  3. 检查连接状态:确认 WorkBuddy 中飞书集成显示「已连接」
  4. 核对 Webhook:若使用 URL 回调模式,确认 Webhook 地址配置正确且服务器可达
  5. 检查权限:确保所有权限都已正确导入

12.2、收不到消息怎么办?

  1. 确认已添加「接收消息」事件
  2. 确认已配置「卡片回传交互」回调
  3. 检查事件订阅中的 Webhook 地址是否正确
  4. 确认机器人是否被正确 @ 或在单聊中发送(群聊需 @ 机器人)

12.3、群聊中机器人不回复?

  1. 在群聊中需要 @机器人 才会触发响应
  2. 确认群聊是否在应用的可用范围内
  3. 确认已添加 im:message.group_at_msg:readonly 权限

12.4、提示「权限不足」或接口报错?

  1. 检查对应权限是否已导入并通过
  2. 部分权限可能需要管理员审批后才能生效
  3. 重新发布应用使权限变更生效

12.5、WebSocket 长连接断开怎么办?

  1. 检查电脑网络是否稳定
  2. 检查电脑是否进入休眠 / 睡眠状态(建议关闭自动休眠)
  3. 在 WorkBuddy 中重新点击「注册」重连

12.6、URL 回调验证失败?

  1. 确认服务器公网可达,防火墙已放行
  2. 确认 Webhook 地址填写正确(含协议头 https://
  3. 检查 Encrypt Key 和 Verification Token 是否与 WorkBuddy 中填写一致

13、安全注意事项

  1. 妥善保管凭证:App Secret、Encrypt Key、Verification Token 均属于敏感信息,切勿截图外传或提交到公开代码仓库。
  2. 限制应用可用范围:仅在需要的成员范围内开放应用,避免无关人员误用。
  3. 定期检查权限:如不再使用某项能力,可在权限管理中移除对应权限,遵循最小权限原则。
  4. 关注远程控制安全:机器人可远程操作电脑,请确保飞书账号安全,避免账号被盗导致电脑被远程操控。
  5. 及时下线:如不再使用,可在飞书开放平台停用应用或移除机器人能力。

14、课后练习与拓展

学完本文,建议按由易到难的顺序完成以下练习,巩固所学:

14.1、基础练习

  1. 机器人对话:完成应用创建与发布后,在飞书中向机器人发送「帮我写一个 Python 爬虫」,观察 WorkBuddy 的执行过程与返回结果。
  2. 权限裁剪 :在权限管理中移除 calendar 系列权限,重新发布应用,然后让机器人「查看我明天的日程」,观察报错信息,再把权限加回来。
  3. 群聊测试:把机器人拉进一个测试群,分别尝试「直接发消息」和「@机器人发消息」,验证群聊必须 @ 才响应的规则。

14.2、进阶练习

  1. CLI 初体验 :安装飞书 CLI 并完成登录,依次执行 lark-cli calendar +agendalark-cli task +get-my-tasks,查看自己的日程与任务。
  2. AI 托管实战:在 AI 工具中用自然语言让 AI「创建一篇名为《本周工作总结》的云文档,并把链接发到我的文件传输助手」。
  3. 模式对比实验:分别用 WebSocket 和 URL 回调两种模式各接入一次,记录配置步骤的差异与各自的耗时。

14.3、思考题

  • 为什么群聊中机器人必须被 @ 才会响应?这样设计解决了什么问题?
  • 如果公司内网完全隔离外网,WebSocket 长连接模式还能用吗?为什么?
  • tenant 权限和 user 权限同时存在时,一个「读取用户日程」的请求应该走哪类权限?

15、参考资料与延伸阅读

资料 说明
飞书开放平台 应用创建、权限、事件回调的官方入口
飞书开放平台文档中心 API 列表、事件标识、错误码查询
飞书 CLI 官网 lark-cli 安装、命令与 Skills 完整文档
larksuite/cli 开源仓库 飞书 CLI 源码与 Issue 反馈
飞书项目开放平台 飞书项目 CLI、MCP、AAMP 协议接入文档

💡 学习建议:官方文档是最权威的资料,遇到接口报错时优先在文档中心搜索错误码;CLI 相关问题可直接在开源仓库提 Issue。

✒️总结

如果这篇【文章】有帮助到你💖,希望可以给我点个赞👍,创作不易,如果有对前端端或者对python感兴趣的朋友,请多多关注💖💖💖,咱们一起探讨和努力!!!

👨‍🔧 个人主页 : 前端初见

相关推荐
张张123y1 天前
Hermes Agent 是什么?它能做什么,以及如何部署到飞书
人工智能·python·飞书
lisanmengmeng4 天前
飞书 API使用
飞书·监控·日志·日志监控·监控及日志
浪潮BB机5 天前
2026飞书妙记与通义听悟会议录音转写工具实测横评
飞书·语音识别·效率工具·ai工具·录音转写·会议纪要
站长工具箱11 天前
讯飞Loomy测评:整合飞书钉钉QQ消息的AI自动办公工具深度体验
人工智能·钉钉·飞书
edtoplort13 天前
迎战WorkBuddy、千问办公上线、飞书并入豆包,AI办公谁胜出
java·人工智能·飞书
极客猴子13 天前
Android录音转写频繁卡顿?多款APP长时间会议场景稳定性实测
android·人工智能·智能手机·飞书
皮皮虾❀14 天前
企业协同办公平台深度对比:钉钉、飞书、企微的区别与钉钉服务商典铭云赛推荐
钉钉·飞书·企业微信
杰瑞学AI15 天前
一个回答需要10分钟:飞书问答机器人踩坑实录——纯Agent自由检索,差点让我们的机器人“难产”
人工智能·机器人·prompt·transformer·飞书·ai-native
极客猴子18 天前
AI会议记录工具横评:科会通、通义听悟、飞书妙记的自动整理效果有什么区别?
人工智能·飞书