---
title: "飞书机器人：扫码创建飞书应用并接入数字人"
description: "用手机飞书扫一下，Halo 会替你创建飞书应用并接好数字人，同事私聊或在群里 @ 机器人就能找它办事；也支持 Lark 和手动填写应用 ID。"
type: "how-to"
audience: ["office"]
since: "3.0"
prerequisites: ["digital-humans/channels"]
related: ["digital-humans/permissions", "digital-humans/channels", "digital-humans/wecom-bot", "troubleshooting/channels"]
lang: "zh-CN"
canonical: "https://hello-halo.cc/docs/digital-humans/feishu-bot.html"
last_updated: "2026-10-19T00:11:17+08:00"
source: "Halo 3.0.4 docs"
---
# 飞书机器人

用手机飞书扫一下，Halo 会替你创建飞书应用并接好数字人，同事私聊或在群里 @ 机器人就能找它办事；也支持 Lark 和手动填写应用 ID。

接入要你自己在 Halo 和手机飞书里操作，Halo 不能替你扫码或填写密钥。

## 开始之前 {#before-you-start}

- 一个飞书或 Lark 账号，手机上装着飞书（或 Lark）。
- Halo 开着。机器人靠 Halo 保持连接，Halo 退出或电脑睡眠时它不会回复，见 [让数字人一直在线](https://hello-halo.cc/docs/digital-humans/keep-running.html)。
- 公司的飞书如果开了应用审核，新建的应用要管理员批准后才能用。把可用范围只设成你自己或少数几个人，大多数公司就能直接发布，不用审核。

## 扫码添加 {#scan}

1. 打开 **设置 › 消息通道**，找到 **飞书机器人**，点 **扫描添加**。卡片下写着「扫码即为您创建飞书应用——无需开发者后台，无需配置权限。」
2. 在「扫码添加飞书机器人」窗口里，用手机飞书扫二维码（「在手机上打开飞书并扫码创建机器人」）。
3. 手机上会打开确认页。同意之前可以改机器人的名称和图标；可用范围建议只选你自己或少数几个人。确认同意。
4. Halo 会自动新建一位数字人「Feishu Assistant …」并绑定好，窗口显示「机器人添加成功」。
5. 按提示马上做下一步：「下一步：打开飞书，按名称找到该机器人并向其发送任意消息，您的用户 ID 将自动绑定为所有者。」点 **明白了**。
6. 在飞书里按名称搜到这个机器人，私聊发一句话。它会先回「✅ 已自动绑定你为本机器人的主人，拥有完整权限。」，再回答你。

![「扫码添加飞书机器人」窗口：二维码（已打码）、可以修改名称和图标的说明，以及可用范围建议](https://hello-halo.cc/docs/images/digital-humans/feishu-bot/scan-dialog.zh.webp)

::: warning 请立即私聊机器人
窗口里写着「请立即操作——第一个在私聊中向机器人发送消息的用户将成为其所有者。」扫码添加的机器人会打开权限控制，谁先私聊它谁就是主人。主人和访客的区别见 [主人与访客权限](https://hello-halo.cc/docs/digital-humans/permissions.html)。
:::

![「机器人添加成功」：已绑定的数字人名称、「请立即操作」的提醒，以及管理员审核的说明](https://hello-halo.cc/docs/images/digital-humans/feishu-bot/scan-success.zh.webp)

扫码创建的飞书应用只申请收发消息需要的最少权限。飞书和 Lark 账号都能扫码，Halo 会自动识别是哪一种。

::: done
机器人回复说已把你绑定为主人，之后你发的消息数字人都会回复。在 **设置 › 消息通道** 里，这个机器人前面的圆点变绿，飞书机器人卡片的标题显示「1 已连接」。
:::

## 交给已有的数字人 {#use-existing}

在设置里扫码，每次都会新建一位数字人。想让已有的数字人接机器人，二选一：

- 打开这位数字人，切到 **能力与设置**，在 **消息与通知 › 机器人访问权限** 里点 **扫码添加机器人 › 飞书机器人**，扫码步骤同上。
- 在机器人卡片的 **后端** 里改选别的数字人，确认「重新绑定此机器人？」。

**后端** 也可以选团队里的一位成员（在「团队：团队名」下面）。这样飞书里的人找的是这位成员，它可以拉上队友一起处理，这些对话会出现在团队工作台的 **IM 会话** 里。

## 在群里使用 {#groups}

1. 把机器人加进飞书群。
2. 在群里 @ 机器人再说话。**在群聊中需要 @ 提及** 默认开着，它只回复 @ 它的消息。
3. 群里的回复默认会引用你那条消息（**引用回复（群聊）**）。

想让它回复群里的每条消息，关掉 **在群聊中需要 @ 提及**。不过飞书只有在应用拿到敏感的「所有群消息」权限时才会推送没 @ 它的消息，这个权限要你自己在飞书开发者后台开。

机器人还没有主人时，在群里什么也不做，只提示先私聊它绑定主人。

## 回复设置 {#reply-settings}

在 **设置 › 消息通道** 里点开这个机器人：

| 设置 | 默认 | 作用 |
|---|---|---|
| **后端** | 扫码时新建的数字人 | 谁来回复：一位数字人，或团队里的一位成员 |
| **回复范围** | **所有消息** | **所有消息**：群里被 @ 和私聊都回复；**仅群聊**：私聊会被拒绝；**仅私信**：群消息不回复 |
| **在群聊中需要 @ 提及** | 开 | 开着时群里只回复 @ 它的消息 |
| **引用回复（群聊）** | 开 | 群里的回复引用它回答的那条消息 |
| **流式传输** | 关 | 打开后，回复过程实时显示在一张飞书卡片里，最后换成完整答案 |
| **处理中提示** | 开 | 5 秒内还没回复时，先发「已收到，正在处理…」。**流式传输** 开着时，这句话直接出现在正在写的回复里 |

改动自动保存，**在群聊中需要 @ 提及** 和 **引用回复（群聊）** 改了马上生效，不用重新连接。

## 手动设置 {#manual-setup}

已经在飞书开发者后台自己建好了应用时，可以手动接入。这个应用需要：开启机器人能力；有以机器人身份发消息、接收私聊消息、接收群里 @ 它的消息、读取消息里的文件、上传和下载资源、读取群名称、读取通讯录基本信息（用来显示私聊对象的名字）、创建和更新卡片（**流式传输** 要用）这些权限；订阅「接收消息 v2.0」（`im.message.receive_v1`）事件，并用长连接接收。

1. 在 **设置 › 消息通道 › 飞书机器人** 里点 **手动设置**。
2. 填 **应用 ID**（以 `cli_` 开头）和 **应用密钥**。
3. **部署** 选 **飞书（中国）** 或 **Lark（国际版）**。
4. 在 **后端** 里选一位数字人，打开 **已启用**。
5. 看一下 **权限控制**，建议打开，见 [主人与访客权限](https://hello-halo.cc/docs/digital-humans/permissions.html)。

飞书开发者后台的具体操作以飞书为准，Halo 里没有对应的引导。

## 一个飞书应用只接一台电脑 {#one-computer}

飞书会把每条消息只推给一个连接。同一个应用同时接在两台电脑的 Halo 上，消息会随机分到两边。一个飞书应用只在一台电脑上用。

## 限制 {#limits}

- 一条消息最多 3,500 个字，更长的回复会拆成几条。
- 没有回复时限，随时可以回复或主动发消息。
- 能收图片、文件、视频、语音和表情。
- 联系人和群的名称会从飞书自动读取。

## 遇到问题 {#troubleshooting}

### 卡片显示「已连接 · 尚未收到消息」

连接是通的，但一条消息都没收到。常见原因：应用还在等管理员审核，或者给它发消息的人不在应用的可用范围里。在飞书里私聊它一句试试，收到消息后这条提示就会消失。

### 扫码后提示「授权在飞书中被拒绝。」

在手机上的确认页没有同意。点 **重试** 重新扫，在确认页点同意。

### 二维码提示「二维码已过期，请重新生成。」

二维码过期后，窗口会显示「设置失败」和这句提示。点 **重试**，会生成新的二维码。

### 群里不回复

1. 确认在群里 @ 了机器人。
2. **回复范围** 不是 **仅私信**。
3. 机器人有主人。还没有时，先私聊它一句。

更多情况见 [机器人不回复](https://hello-halo.cc/docs/troubleshooting/channels.html)。

## 下一步 {#next-steps}

- [主人与访客权限](https://hello-halo.cc/docs/digital-humans/permissions.html)：决定群里其他人能让数字人做什么。
- [消息通道概览](https://hello-halo.cc/docs/digital-humans/channels.html#push)：让数字人主动给联系人发消息。
- [团队工作台](https://hello-halo.cc/docs/digital-humans/team-workbench.html)：看团队成员在飞书里接的对话。