飞书机器人

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

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

开始之前

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

扫码添加

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

请立即私聊机器人

窗口里写着「请立即操作——第一个在私聊中向机器人发送消息的用户将成为其所有者。」扫码添加的机器人会打开权限控制，谁先私聊它谁就是主人。主人和访客的区别见 主人与访客权限。

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

完成

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

交给已有的数字人

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

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

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

在群里使用

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

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

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

回复设置

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

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

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

手动设置

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

1. 在 设置 › 消息通道 › 飞书机器人 里点 手动设置。
2. 填 应用 ID（以 cli_ 开头）和 应用密钥。
3. 部署 选 飞书（中国） 或 Lark（国际版）。
4. 在 后端 里选一位数字人，打开 已启用。
5. 看一下 权限控制，建议打开，见 主人与访客权限。

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

一个飞书应用只接一台电脑

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

限制

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

遇到问题

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

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

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

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

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

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

群里不回复

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

更多情况见 机器人不回复。

下一步

• 主人与访客权限：决定群里其他人能让数字人做什么。
• 消息通道概览：让数字人主动给联系人发消息。
• 团队工作台：看团队成员在飞书里接的对话。