Hermes Agent 接入飞书教程(2026):扫码创建机器人、WebSocket 免公网 IP 与群聊 @ 唤醒配置
TL;DR: 飞书是 Hermes 原生支持的消息平台,不用公网 IP、不用云服务器。核心流程只有四步:
hermes update更新版本 →hermes gateway setup选「飞书 / Lark」并手机扫码 → 配置白名单与群聊策略 →hermes gateway启动网关。全程约 5 分钟,扫码那一步会自动帮你创建机器人应用。和微信接入最大的区别是:飞书走官方开放平台,不存在个人号被风控的问题,更适合工作群和团队使用。
飞书是 Hermes 目前国内场景里最稳的一个入口:官方开放平台、原生适配器,支持文本、图片、语音、文件、审批卡片和文档评论,还能把定时任务的结果直接推到指定群。这篇教程把从零到跑通的全流程走一遍;Hermes 本体还没装的,先看 Hermes 安装与使用教程。
📚 本文目录(点击跳转)
- 一、准备工作:飞书账号、Hermes 版本与权限认知
- 二、第一步:更新 Hermes 并确认网关可用
- 三、第二步:一条命令创建飞书机器人(推荐扫码)
- 四、第三步:选择连接模式 WebSocket 还是 Webhook
- 五、第四步:白名单、群聊策略与 Home Channel
- 六、第五步:启动网关并在飞书里验证
- 七、第六步:进阶玩法:群规则、审批卡片与文档评论
- 飞书接入方案的优缺点分析
- 适合人群与适用场景
- 常见问题 FAQ
- 相关教程
一、准备工作:飞书账号、Hermes 版本与权限认知
| 检查项 | 要求 | 怎么确认 |
|---|---|---|
| Hermes Agent | 已安装且能正常运行 | 终端里执行 hermes 能进入对话;没装先看 安装教程 |
| Python | 3.10 或更高版本 | 终端执行 python --version |
| 飞书账号 | 能登录飞书开放平台的账号,免费团队空间即可 | 企业空间里安装应用通常需要管理员同意 |
| 网络 | 能正常访问 open.feishu.cn | 国际版 Lark 用 open.larksuite.com |
NOTE
先分清飞书和微信的差别:微信接入走的是第三方 iLink 接口,存在个人号风控风险;飞书是官方开放平台,Hermes 以「机器人应用」的身份接入,不碰你的个人账号。代价是企业空间里应用安装、权限申请和版本发布需要管理员点头;自己注册的免费团队空间里,通常自己就能创建自建应用。
二、第一步:更新 Hermes 并确认网关可用
飞书适配器是较新的能力,旧版本可能还没有,先更新:
hermes update更新完确认网关命令可用:
hermes gateway --help能看到 setup、start、status、restart 这些子命令,说明网关模块正常。飞书适配器依赖 lark-oapi 和 websockets,配置向导通常会按需安装;如果后面报缺少模块,按文末排错表处理即可。
三、第二步:一条命令创建飞书机器人(推荐扫码)
在终端运行:
hermes gateway setup用方向键选中 飞书 / Lark,回车。Hermes 会在终端里生成一张二维码,用手机飞书扫码,它会自动完成三件事:
- 在你的飞书里创建一个机器人应用;
- 开通收发消息需要的权限;
- 把 App ID、App Secret 等凭据写进 Hermes 配置。
TIP
扫码创建是官方推荐路径,省去在开发者后台逐项勾权限。二维码有时效,过期了重新运行
hermes gateway setup生成新码即可。
扫码不可用时:手动创建应用
如果扫码失败,或者你的飞书空间不允许扫码建应用,就手动来:
- 打开飞书开发者后台 open.feishu.cn(国际版是 open.larksuite.com);
- 创建「企业自建应用」;
- 在 凭证与基础信息 里复制 App ID 和 App Secret;
- 在 应用功能 → 机器人 里开启机器人能力;
- 在 事件与回调 → 事件配置 里订阅
im.message.receive_v1,接收方式选 长连接; - 授予收发消息权限,至少要有
im:message和im:resource(图片、文件); - 回到终端运行
hermes gateway setup,选飞书,粘贴 App ID 和 App Secret。
WARNING
App Secret 等于机器人的钥匙。拿到它的人可以冒充你的应用发消息、读消息。不要贴到公开仓库、群聊或截图里;怀疑泄露就立刻在开发者后台重置。
也可以在 ~/.hermes/.env(Windows 是 %LOCALAPPDATA%\hermes\.env)里手写凭据,效果等同向导:
FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=secret_xxx
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocketFEISHU_DOMAIN 填 feishu 是国内飞书,填 lark 是国际版。
四、第三步:选择连接模式 WebSocket 还是 Webhook
| 模式 | 适合场景 | 是否需要公网 IP | 说明 |
|---|---|---|---|
| WebSocket(默认,推荐) | 笔记本、家用电脑、内网服务器 | 不需要 | Hermes 主动向飞书建长连接,断线自动重连 |
| Webhook | 已有可访问域名或公网端口 | 需要 | Hermes 自己起一个 HTTP 服务接收飞书事件 |
绝大多数人保持默认的 WebSocket 就行,不用买服务器、不用做端口映射,也不用备案。只有当你已经把 Hermes 部署在飞书能访问到的公网地址后面,才考虑 webhook:
FEISHU_CONNECTION_MODE=webhook
FEISHU_WEBHOOK_HOST=127.0.0.1
FEISHU_WEBHOOK_PORT=8765
FEISHU_WEBHOOK_PATH=/feishu/webhookwebhook 模式在生产环境还要配签名和 token 校验,这两项都能在飞书后台的「事件订阅」里找到:
FEISHU_ENCRYPT_KEY=你的加密密钥
FEISHU_VERIFICATION_TOKEN=你的验证TokenWebSocket 模式下签名由飞书 SDK 自己处理,这两项可以不配。
五、第四步:白名单、群聊策略与 Home Channel
接线完成只是「通了」,接下来决定「谁能用、在哪儿用」。
用户白名单
FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy填的是飞书用户的 open_id,逗号分隔。不配白名单时,能接触到机器人的人都可能调用它。生产环境建议一定配上。
群聊策略
FEISHU_GROUP_POLICY=allowlist # 默认值| 取值 | 行为 |
|---|---|
open | 任意群里任意用户 @ 机器人都响应 |
allowlist | 只有 FEISHU_ALLOWED_USERS 里的用户 @ 才响应(默认) |
disabled | 完全忽略群消息,只保留私聊 |
不管哪种模式,群消息默认都要求明确 @ 机器人(或 @所有人)。想让它在群里读所有消息、不用 @,才改:
FEISHU_REQUIRE_MENTION=false每个群单独设规则
不想一刀切,可以在 ~/.hermes/config.yaml 里按群配置:
platforms:
feishu:
extra:
default_group_policy: "open"
admins:
- "ou_admin_open_id"
group_rules:
"oc_工作群":
policy: "allowlist"
allowlist:
- "ou_用户1"
- "ou_用户2"
"oc_只读群":
policy: "disabled"可选策略有 open、allowlist、blacklist、admin_only、disabled,单个群还能用 require_mention: false 覆盖全局的 @ 要求。
Home Channel:定时任务的推送地址
在飞书聊天里给机器人发 /set-home,这个会话就会成为 cron 任务和通知的默认投递频道。也可以预先写死:
FEISHU_HOME_CHANNEL=oc_xxxIMPORTANT
共享群里的会话是隔离的。同一个群里,每个用户的对话历史默认互不可见(group_sessions_per_user: true)。除非你明确希望全群共用一个上下文,否则不要改。
六、第五步:启动网关并在飞书里验证
先在前台跑起来,方便看日志:
hermes gateway需要长期运行就用它的常驻模式:
hermes gateway installWindows 上会注册成登录时启动的计划任务,Linux/macOS 上是用户级服务。不管哪种方式,网关进程都得在线,消息才收得到。
验证分两步:
- 在飞书里私聊机器人,发一句「你好」,能正常回复说明链路通了;
- 把它拉进一个测试群,@ 它再发一句话,能回复说明群策略也对了。
随时可以查看状态:
hermes gateway status七、第六步:进阶玩法:群规则、审批卡片与文档评论
跑通基础对话后,飞书适配器还有几项别的平台没有的能力。
1. 危险命令审批卡片
Agent 要执行危险命令时,会在飞书里发一张带「允许一次 / 本次会话 / 始终允许 / 拒绝」按钮的卡片。这项能力需要额外配置,否则点按钮会报 200340:
- 开发者后台 → 事件与回调 → 回调配置,订阅
card.action.trigger(注意是「回调配置」标签,不是「事件配置」); - 同页把接收方式设为 长连接(WebSocket 模式);
- 应用功能 → 机器人 里启用 交互式卡片;
- 版本管理与发布 里创建版本并发布,企业应用还要等审核。
配置没生效时,卡片能正常发出来,但按钮点不动——因为飞书在把点击事件送到 Hermes 之前就拒了。
2. 文档评论里的 @ 回复
有人在飞书文档里评论并 @ 机器人时,Hermes 会读取文档内容和评论上下文,直接在线程里回复。需要:
- 事件订阅
drive.notice.comment_add_v1; - 权限
docs:doc:readonly和drive:drive:readonly;
用 ~/.hermes/feishu_comment_rules.json 配允许的文档和用户,默认是显式授权,不会对所有人开放。
3. 定时任务推送
cron 任务跑完的结果可以推到飞书的 home channel。典型用法是每天早上的资讯简报、周报汇总、网站变更监控。
配置好 /set-home 之后,在对话里直接说「每天早上 8 点整理一次 XX 的新闻发到这个群」即可。
4. 媒体与格式
文本、图片、音频、视频、文件都能双向收发;带 Markdown 的回复会自动转成飞书富文本消息,格式不被支持时回退成纯文本,保证消息一定能送达。机器人处理消息时会在你的消息上显示 Typing 表情,处理完清除。
飞书接入方案的优缺点分析
优点
- 官方接口,无账号风险:不碰个人账号,不存在微信那套风控和封号顾虑
- 不需要公网 IP:默认 WebSocket 长连接,家用宽带也能跑
- 配置极短:扫码创建应用,凭据自动写入
- 办公场景完整:审批按钮、文档评论、会议邀请、图片文件都支持
- 权限粒度细:白名单、按群规则、@ 触发、每人独立会话
- 能主动推送:cron 结果可以固定发到某个群或私聊
不足
- 需要有飞书账号:个人版能自己建,企业空间要管理员批准安装和权限
- 群聊默认只认 @:想让它读全群消息要额外改配置,也意味着更高的 token 消耗
- 卡片和文档评论要额外配权限:不配只能用基础聊天
- 网关要常开:电脑关机就断线,长期在线建议放服务器
- 一个应用只能接一个实例:多开要给每个实例单独建应用
- 界面和权限项会变:飞书后台改版频繁,以页面实际提示为准
适合人群与适用场景
适合你,如果:
- 团队日常用飞书,想把 AI 助手放进工作群、项目群
- 想要一个比个人微信更安全、不会因自动化被风控的入口
- 需要机器人处理文档评论、会议邀请、审批按钮这类办公动作
- 想让定时任务的结果每天自动发到固定群
不适合你,如果:
- 只想用个人微信,不想注册飞书
- 没有权限在飞书空间里安装应用,也不想去申请
- 机器不能长时间开机,又不打算放到服务器上
- 只想在终端里用,不需要消息平台入口
常见问题 FAQ
Hermes 接入飞书会封号吗?
扫码创建应用失败,或者没有出现二维码怎么办?
群里 @ 了机器人却不回复?
接入飞书需要公网 IP 或云服务器吗?
一个飞书应用能同时接几个 Hermes?
点击消息里的审批按钮报错 200340?
能接飞书国际版 Lark 吗?
电脑关机后机器人在飞书里还能用吗?
相关教程
- Hermes 接入微信教程 — 想接个人微信?先看清第三方接口的风控边界
- Hermes 安装与使用教程 — Windows 一键安装、模型配置与常见报错
- Hermes 桌面版安装教程 — 不想碰命令行,用图形界面配模型、开网关
- Hermes 教程专栏 — 模型版本、上手流程和全部接入教程
