飞书应用机器人配置指南
本文介绍如何把飞书的企业自建应用机器人接入 pt-tools:私聊机器人或在群里 @ 它发 ChatOps 命令、和 AI 助手对话,并把每日战报、签到、追剧这些后台通知发到飞书。应用有两种建法:用下一节的扫码一键创建,由 pt-tools 在飞书里建好;或者在飞书开放平台手动创建(第 1 节起)。
pt-tools 用飞书官方 Go SDK 的长连接接收事件:由 pt-tools 主动连出到飞书开放平台,不需要公网地址,也不用开放端口,部署方式和 Telegram 的长轮询一样。
说明
这里说的是「飞书应用机器人」(通道类型 feishu_app),能收命令。「更多通知通道」里的飞书群机器人是群里的自定义机器人,只能发通知、收不到命令,两者的配置互不相通。
扫码一键创建(推荐)
用飞书扫一个二维码,pt-tools 就在你的企业里建好这个应用机器人:三项权限与「接收消息 v2.0」事件已经预填好,不用改订阅方式、不用发布版本,通道建好以后马上连上飞书。
- 打开 pt-tools Web UI,进入 ChatOps → 消息通知,点「添加通道」,通道类型选择「飞书应用机器人」。
- 创建方式保持「扫码一键创建(推荐)」,按需改通道名称(默认「飞书应用机器人」),点「生成二维码」。
- 用要接 pt-tools 的那个企业的飞书账号扫码(在电脑上也可以点「在浏览器里打开」),在飞书的确认页上确认。应用名在确认页上可以改。
- 确认以后,pt-tools 建好通道并打开它的详情页,通道列表里显示「已连接」。私聊机器人发
/help试一下,见第 8 节。
预填的内容与第 3、5 节手动开通的相同:权限 im:message:send_as_bot、im:message.p2p_msg:readonly、im:message.group_at_msg:readonly,事件「接收消息 v2.0」(im.message.receive_v1)。
- 扫码的人自动成为管理员并直接绑定:通道的「管理员 open_id」填的是扫码人的 open_id,不用私聊机器人拿 open_id,也不用生成绑定码,马上就能发命令。要让别人也能用,把他的 open_id 加进通道详情的名单(见第 7 节)并绑定。飞书没有给出扫码人的 open_id 时,通道照样建好,只是管理员空着:按第 7 节拿到 open_id 填进去,再到绑定页绑定。
- 应用建在扫码人所在的企业里。账号不对、那个企业的平台策略不允许时,通道显示「异常」,运行日志里换 tenant_access_token 回
21001(见第 12 节);这时用对的账号重新扫一次。 - 扫码人用的是 Lark 国际版时,通道的平台自动是「Lark 国际版」(Lark 未实测,见第 12 节)。
- 一个应用只给一台 pt-tools 用(见第 12 节)。有几台 pt-tools,就在每一台上各扫一次。
- App ID 与 App Secret 由 pt-tools 直接保存,和手动填写的一样加密保存,只在登录以后的通道详情里回显。
- 二维码 10 分钟内有效,同一时间只有一个:再点「生成二维码」或关掉对话框,之前的二维码就作废了;那一刻你已经在飞书里确认、pt-tools 已经拿到应用的不算,这时通道照常建好,页面会提示;关对话框时取消没送到(网络出错),页面也会写明。上一个正在保存通道时,「生成二维码」会请你稍等几秒。作废的二维码不要再扫:扫了并确认的话,飞书仍可能建出一个应用。这时先看通道列表里有没有刚建好的通道,没有的话再到飞书开发者后台删掉多出来的那个。扫码建的应用默认都叫 pt-tools,按 App ID 认:通道详情里填着的 App ID 是在用的,不要删。二维码只在自己的屏幕上扫,不要截图发给别人。
- 企业要求管理员审核应用时,确认页上会有提示,可能建不成;这时改用下面的手动创建,并找企业管理员审核。
- 建应用的请求由 pt-tools 发出,只跟随环境变量
HTTPS_PROXY与NO_PROXY:这时通道还不存在,通道的代理 URL 用不上(见第 11 节)。 - 扫码一键创建只在登录以后的网页里有:手机 App 与 MCP 里没有,让 AI 助手改配置时也只能填 App ID 与 App Secret 建通道。
下面第 1 节起是手动创建的步骤。
1. 前置条件
- 一个飞书企业(团队)账号,能在飞书开放平台创建企业自建应用。长连接只支持企业自建应用。
- 应用发布要企业管理员审核。只是自己用的话,可以另外创建一个测试企业,自己就是管理员,发布不用等别人审核。
- pt-tools 所在的机器能访问飞书开放平台
open.feishu.cn(Lark 国际版是open.larksuite.com,用来取长连接地址、换取访问凭证、发消息),以及飞书下发的长连接地址(feishu.cn或larksuite.com下的主机)。需要代理时见第 11 节。
2. 创建应用并开启机器人能力
- 打开飞书开放平台,点「创建企业自建应用」,填应用名称(例如
pt-tools)与描述。 - 在应用的「添加应用能力」里添加「机器人」。
- 在「凭证与基础信息」里找到 App ID(
cli_开头)与 App Secret,下一步要用。
注意
App Secret 等同于应用的密码。不要把它发在公开群里或截图里,不要提交到代码仓库。泄露以后在「凭证与基础信息」里重置。
3. 开通权限
在「权限管理」里搜索并开通下面三项:
| 权限 | 名称 | 是否必需 | 用途 |
|---|---|---|---|
im:message.p2p_msg:readonly | 读取用户发给机器人的单聊消息 | 必需 | 私聊机器人发命令 |
im:message.group_at_msg:readonly | 接收群聊中 @ 机器人消息事件 | 可选 | 在群里 @ 机器人发命令 |
im:message:send_as_bot | 以应用的身份发消息 | 必需 | 回复命令、发后台通知 |
pt-tools 不需要通讯录权限:不调用通讯录接口,也不读发消息的人的姓名。群里 @ 了别人时,消息里的「@姓名」会原样交给命令和 AI 助手。开了「获取群组中所有消息」这类更大的权限也没有关系:群里没有 @ 本机器人的消息,pt-tools 一律忽略。
4. 在 pt-tools 里创建通道
打开 pt-tools Web UI,进入 ChatOps → 消息通知,点「添加通道」:
- 通道类型选择「飞书应用机器人」,创建方式选「填写 App ID 与 App Secret」,填写通道名称、App ID 与 App Secret,平台选「飞书」(Lark 国际版选「Lark 国际版」),点「创建通道」。
- 通道创建以后会马上连上飞书。在通道列表里看状态:「已连接」表示长连接已经连上,下一步才能保存事件订阅。
- 点进通道详情,在「凭证与连接」里补全下面的字段,点「保存凭证」。保存以后通道会用新配置重连。
| 字段 | 填写值 | 说明 |
|---|---|---|
| App ID | cli_a1b2c3d4e5f6 | 「凭证与基础信息」里的 App ID |
| App Secret | 应用的 App Secret | 加密保存,只在登录以后的通道详情里回显 |
| 平台 | 飞书 / Lark 国际版 | 默认飞书 |
| 管理员 open_id | ou_ 开头的 open_id | 多个用逗号或换行分开;没填默认会话 ID 时,通知发给其中第一个 |
| 允许的用户 open_id | ou_ 开头的 open_id | 同样能与机器人对话 |
| 默认会话 ID(可选) | oc_…、ou_… 或 on_… | 每日战报、签到这类通知发到这里:oc_ 是群(或单聊会话),ou_ 是个人的 open_id,on_ 是个人的 union_id |
| 代理 URL(可选) | http://127.0.0.1:1080 | 只有这个通道走它,见第 11 节 |
- 两栏名单里只能填 open_id(
ou_开头),填了 user_id、union_id 或其他内容会拒绝保存并写明是哪一项。不知道 open_id 时见第 7 节。 - 只有出现在两栏名单里的人能与机器人对话,两栏都空时谁发来的消息都不处理。名单外的人私聊机器人,会收到一条带他 open_id 的提示(同一个人 10 分钟最多一条);在群里不回。
- 没有指定收件人的通知按这个顺序找收件人:默认会话 ID → 管理员 open_id 里的第一个 → 这个通道上第一个完成绑定的账号。三者都没有时通知发不出去,「ChatOps 绑定」页的通道一栏会写明原因。
5. 订阅事件:改用长连接
回到飞书开放平台的应用页面,打开「事件与回调」→「事件配置」:
- 「订阅方式」选「使用长连接接收事件」并保存。保存时飞书会检查有没有客户端在线,所以 pt-tools 的通道这时要显示「已连接」,否则保存失败。
- 点「添加事件」,搜索并添加「接收消息 v2.0」(
im.message.receive_v1)。
只订阅这一个事件。多订阅的事件 pt-tools 不处理,会回失败,飞书会把它重新推送,运行日志里有「not found handler」的报错(收命令不受影响)。消息已读、机器人进群与被移出群、用户与机器人的单聊首次创建这几种例外:pt-tools 收下以后什么也不做,不报错。
6. 发布版本
权限与事件改动要发布一个版本才生效:
- 打开「应用发布」→「版本管理与发布」,点「创建版本」,填版本号与更新说明。
- 「可用范围」里加上要用机器人的人(或部门)。不在可用范围里的人搜不到机器人,pt-tools 发给他的通知也会失败(错误码 230013)。
- 申请发布,等企业管理员审核通过。在测试企业里,自己审核即可。
以后改了权限或事件订阅,都要再发布一个版本。
7. 获取 open_id
open_id 是用户在这个应用下的 ID,以 ou_ 开头。同一个人在不同应用下的 open_id 不一样,换了应用以后名单与绑定都要重新弄。
最省事的拿法:在飞书里搜索这个机器人,私聊它发一条消息(例如 /help)。你不在名单里时,机器人会回复:
你不在这个 pt-tools 机器人的名单里,发来的消息没有处理。
你的 open_id 是 ou_7f3a9c2d1e…
请 pt-tools 的管理员在通道设置里把它填进「管理员 open_id」或「允许的用户 open_id」。把这个 open_id 填进通道详情的「管理员 open_id」并保存。也可以在开放平台的 API 调试台里查(见如何获取 Open ID)。
8. 绑定与测试命令
发送测试消息
在通道列表里点通道卡片上的「发测试消息」,或在通道详情的「连通性测试」里点「发送测试消息」。飞书里收到机器人发来的测试消息,说明发消息正常。
绑定
名单只决定谁能和机器人说话,执行命令还要先绑定。打开 ChatOps → ChatOps 绑定:
- 最上面「通道」一栏列出飞书通道名单里的每个账号与绑定情况。名单里没绑定的账号可以直接点「绑定」,确认后就能用命令。
- 也可以点「生成绑定码」,选好飞书通道,拿到一个 8 位的码,在飞书里私聊机器人发
/bind 绑定码,机器人回复「绑定成功」即完成。
目前每个完成绑定的账号都拥有管理员权限,可以暂停、删除种子和管理 RSS 订阅。绑定码只发给你信任的人。
测试命令
私聊机器人发 /help,机器人应该回复完整的命令列表;再发 /status 验证读取操作。命令清单见 ChatOps 快速开始。
9. 在群里用
- 手动创建的应用要开通第 3 节的
im:message.group_at_msg:readonly权限并发布版本;扫码一键创建的应用已经带着这项权限,跳过这一步。 - 把机器人拉进群:群设置 →「群机器人」→「添加机器人」,选这个应用。
- 在群里 @ 机器人再写命令,例如
@pt-tools /status。不 @ 机器人的消息、只 @ 了别人或别的机器人的消息,pt-tools 一律忽略。
在群里发命令时,发命令的人同样要在名单里、完成绑定。回复发到群里,群成员都看得到;绑定码也一样,绑定请在私聊里做。想把每日战报这类通知发到群里,把群的会话 ID(oc_ 开头)填进「默认会话 ID」。会话 ID 可以从运行日志拿:名单里的人在群里 @ 机器人发一条消息,运行日志里「收到消息」那一行的 chat_id=oc_… 就是这个群的会话 ID。
10. AI 助手与「确认」
在「系统 → AI 助手设置」打开「通知渠道(ChatOps)」以后,发给机器人的、不以 / 开头的文字交给 AI 助手回答(群里同样要 @ 机器人)。暂停、删除种子这类改动类操作,助手会先回一句「需要你确认:…回复「确认」执行」,回复「确认」(或「确定」「是」「好的」「ok」「yes」)才执行,回复别的内容就取消。只有发起这一轮对话的人说「确认」才算数,群里别人说的不算。详见 AI 助手。
飞书里没有卡片按钮:确认用文字回复;RSS 上新通知只有正文,没有「立即下载 / 忽略」按钮(与 QQ 相同)。
11. 代理
国内网络通常能直连 open.feishu.cn,不需要代理。需要时有两种方式:
- 环境变量:不填通道代理时,飞书应用机器人只跟随
HTTPS_PROXY与NO_PROXY(飞书的地址都是 https,HTTP_PROXY不起作用)。环境变量里的代理同样只能是http://或socks5://,填了https://这类协议的代理时长连接连不上(发消息照常)。如果部署里为了别的站点设了HTTPS_PROXY,又想让飞书直连,把feishu.cn(Lark 国际版是larksuite.com)加进NO_PROXY。 - 通道级代理 URL:在通道详情的「代理 URL(可选)」里填,只有这个通道走它。支持
http://与socks5://两种,要写端口(例如socks5://192.168.1.2:1080),长连接不支持https://协议的代理。
12. 常见问题 FAQ
Q: 发给机器人的消息没有反应
按顺序检查:
- 通道状态是不是「已连接」(ChatOps → 消息通知)。
- 手动创建的应用:「事件与回调」的订阅方式是不是「使用长连接接收事件」,有没有添加「接收消息 v2.0」。
- 手动创建的应用:改完权限与事件订阅以后,有没有发布版本并审核通过。
- 自己在不在应用的「可用范围」里。
- 私聊要有
im:message.p2p_msg:readonly,群里要有im:message.group_at_msg:readonly,群里还要 @ 机器人。 - 自己的 open_id 在不在通道的名单里,执行命令前有没有完成绑定(「ChatOps 绑定」页的通道一栏能看到最近一次往来与结果)。
Q: 保存长连接订阅方式时提示失败
飞书在保存这一项时会检查有没有客户端在线。先确认 pt-tools 里这个通道显示「已连接」,再回开放平台保存。
Q: 通道状态显示「异常」
在运行日志里搜「飞书应用机器人」,常见原因:
- App ID 或 App Secret 填错:日志里有「长连接被飞书拒绝」与「长连接出错」,后面跟着
1000040345: app_id or app_secret is invalid;发测试消息时报code:10014(app secret invalid)。改对以后保存凭证,通道会马上重连。 - 换 tenant_access_token 时飞书回
21001(Access denied due to platform policy):飞书的平台策略拒绝了这个应用,多半是建应用时用的账号或企业不对。用要接 pt-tools 的那个企业的账号重新建应用。 - 应用没有开启机器人能力:取不到机器人信息时也显示异常。这期间 pt-tools 判断不了群消息有没有 @ 机器人,群里 @ 了人的消息会请飞书稍后重新推送(按飞书的文档,一条消息最多再推 4 次,每次运行日志里有一条
还没取到机器人信息),取到机器人信息以后照常处理;私聊照常。 - 同一个飞书应用配置在了两个通道上:只有先启动的那个连接,另一个显示异常,见下一问。
Q: 两台 pt-tools,或者两个通道,能共用一个应用吗?
不能。长连接是集群模式:同一个应用有多个连接时,每条消息只推给其中随机一个,另一边就收不到,看起来像随机丢消息。一个应用只给一台 pt-tools 的一个通道用;有多台机器时,每台建一个应用。
Q: 改了别的通知设置以后,消息隔了一会儿才有回复
改任何一条通知通道的设置,所有通道都会重新连接一次:
- 正在处理的那条消息会被取消(可能已经执行了一部分,不会重来);排着队、尚未开始处理的,重连以后接着处理,每条只处理一次。正在处理的那条一时停不下来时(例如下载器响应慢),重连最多等它 10 秒;之后照常重连,这个人后面的消息仍等那一条结束才处理,别人的消息不受影响。
- 同一个人发的几条消息按发出的先后处理;重连那一刻还在路上、由飞书稍后重推的消息,会排在重推以前已经处理的消息后面。
- 断开的这几秒里发的消息,按飞书的文档通常在约 15 秒以后重新推送,pt-tools 收到后照常处理,不会重复执行。
Q: 发通知失败,错误码 230013 或 230002
- 230013:收件人不在应用的可用范围里。在「版本管理与发布」里把他加进可用范围,再发布一个版本。
- 230002:机器人不在这个群里。把机器人拉进群,或者改掉「默认会话 ID」。
其他错误码与原因写在「最近的通知」和操作审计里。
Q: 机器人回复「这条消息是 N 分钟前发的……没有执行」
按飞书的文档,没有收到应答的消息会在约 15 秒、5 分钟、1 小时、6 小时以后重新推送,所以 pt-tools 离线期间的消息可能在重新上线以后才送到。实测:pt-tools 停了 2 分钟,这期间发的消息在发出以后约 5 分钟送到,照常处理。发出超过 30 分钟才送到的消息不执行,以免很久以前的 /delete 在重新上线以后被执行。需要的话重新发一次。
Q: 支持 Lark 国际版吗?
支持。手动创建时平台选「Lark 国际版」,应用在 Lark 开放平台创建,步骤与飞书相同;扫码一键创建时,扫码人用的是 Lark 国际版的话,通道的平台自动是「Lark 国际版」。这部分按官方文档实现,未实测。