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:message、im:message:readonly、im:chat:read 等消息相关权限。

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

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

对比项 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 ID 、App 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 +agenda 和 lark-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感兴趣的朋友,请多多关注💖💖💖,咱们一起探讨和努力!!!

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

相关推荐
宝哥聊编程8 天前
主流 Agent 平台对比:Coze、Dify、飞书、扣子、OpenClaw 落地实操手册
前端·人工智能·飞书
guoran_shini10 天前
Agent系统服务化封装和IM接入
飞书
mudtools12 天前
在飞书 SDK 上用 Microsoft Agent Framework 搭一个能干活的工作搭子
人工智能·ai·.net·飞书·agent
极致了13 天前
飞书插件、RPA、API三条路的真实分界线
飞书·rpa
玩泥巴的14 天前
在飞书 SDK 上用 Microsoft Agent Framework 搭一个能干活的工作搭子
ai·.net·飞书·agent
玩泥巴的15 天前
一份声明,多份产物:飞书 SDK 的 AI 工具面是怎么生成的
ai·.net·飞书·agent
OpenPortal认证计费系统17 天前
基于 飞书认证 通过 华为、H3C 结合 OpenPortal认证计费系统 实现 网络准入 飞书授权 实名认证
华为·飞书·h3c·portal认证·openportal
前进的李工18 天前
飞书企业知识库设计+后端高频八股
数据库·redis·后端·mysql·性能优化·飞书·rag
长弓三石18 天前
钉钉与飞书机器人接入企业级智能体过程及排障实录
人工智能·机器人·钉钉·飞书·企业级harness