💡阅读指南

这一节直接动手，把飞书接到 Hermes 上，让飞书能发消息给 Hermes。Hermes 能回消息给飞书。整节只做一件事：搭通这条双向通道。

3.1 准备工作

确保已经注册了飞书账号，并用该账号登录了 飞书开放平台。个人版即可，不需要企业管理员权限。

另外建议在电脑上安装飞书桌面端，扫码授权和后续的日常使用会更方便。也可以安装飞书移动端 App。PC/移动端的飞书你起码要装一个，建议两个都安装。PC 端飞书用于在电脑前工作时使用，移动端的飞书是你出门在外的时候使用。

这就类似我们大部分时间在手机上用微信，但也可以在PC 端使用微信。

3.2 传统 8 步配置（仅供感受）

要让飞书同 Hermes 双向交流，最原始的方式是在飞书开放平台手动创建一个应用：

登录 飞书开放平台 → 创建企业自建应用 → 获取 App ID 和 App Secret → 启用机器人能力 → 配置权限 → 配置事件订阅 → 配置长连接 → 添加接收消息事件 → 发布应用。

整个过程 8 步，每一步都依赖前一步，中间还要处理权限范围和订阅验证的问题。不过这只是为了让你感受一下传统方式的繁琐——我们根本不需要走这条路。

但这一套虽然繁琐，却适配任何想接入飞书的应用。我在《Coze 编程》书中使用的就是这种方式。而且有大量的非智能体应用，只能使用这种传统的方式接入。

3.3 三步搞定：让 Hermes 自动连接

💡提示

建议先在电脑上安装飞书桌面端，扫码授权直接在桌面端完成，这样你可以在桌面飞书同 Hermes 交互，不用每次都掏手机。

实话说，上面那套手动配置的方式挺痛苦的，基本上一个新手要搞大半个小时。好在 Hermes 是一个超级智能体，且针对飞书做了优化，现在 Hermes 可以自动完成飞书应用的创建和配置，你只需要几步（非常简单，基本都是一路按回车）。

第一步，运行命令。 打开终端，敲一条命令：

Bash
hermes setup gateway

第二步，选择飞书。 用上下键浏览列表，按空格选中 Feishu / Lark（前面会出现 ✓ 标记），再按回车确认。

💡提示

如果界面上一直显示「No platforms selected」，说明没有成功勾选。确保先按空格（不是回车）打上标记，再按回车提交。我开始的时候就因为没看清楚，折腾了老久。如果没选中，就回车，那相当于是退出，没有配置。

第三步，在浏览器中完成授权。 终端里会弹出一个二维码和一串 URL。这里有两种方式：

  • 方法一：扫码——打开飞书手机端或桌面端扫二维码，在 App 内完成授权。
  • 方法二（推荐）：复制 URL 到浏览器——把终端里的那串链接复制下来，粘贴到电脑浏览器打开，在网页上完成飞书授权。
alt text

建议用第二种，浏览器操作更直观。授权成功后，Hermes 会自动在飞书开放平台创建应用、配置权限、订阅事件、建立长连接——前面说的那 8 步全部自动化。

第四步，设置响应时机。 授权完成后会看到一个交互界面，选择你希望的响应方式，如图： alt text

第五步，查看配置结果。 选完后终端会输出一段配置摘要：

code
✓   Bot created: 姜磺的 Hermes
✓   DM pairing enabled.
    Unknown users can request access; approve with `hermes pairing approve`.
    Group chats enabled (bot must be @mentioned).

  Home chat ID (optional, for cron/notifications):
  • Bot created——飞书里的机器人应用已经创建好了，后面的名字是你的飞书账号名
  • DM pairing enabled——单聊通道已开启，别人可以直接给机器人发消息
  • Unknown users can request access——陌生用户发消息会触发配对请求，用 hermes pairing approve 批准后才能通信，这是安全机制
  • Group chats enabled——群聊也已开启，但机器人在群里需要被 @ 才会响应
  • Home chat ID——最后一行问你要不要设一个「家庭聊天」，用于接收定时任务和系统通知，直接回车跳过，后续随时可以配

接着终端会输出最终确认信息：

code
✓ 🪽 Feishu / Lark configured!
    App ID: cli_aa9b6a72f178dbc3
    Domain: feishu
    Bot: 姜磺的 Hermes

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Messaging platforms configured!

  Install the gateway as a launchd service? (runs in background, starts on boot) [Y/n]:

第六步，安装后台服务。 最下面一行问你要不要将消息网关安装为系统服务，让它一直在后台运行，开机自动启动。直接按回车选 Y（默认就是 Yes），之后就不需要每次手动 hermes gateway run 了。

终端会接着输出：

code
✓ Service installed and loaded!

Next steps:
  hermes gateway status             # Check status
  tail -f ~/.hermes/logs/gateway.log  # View logs

  Start the service now? [Y/n]: Y
✓ Service started
  • Service installed and loaded——launchd 服务已安装并加载成功，以后开机自动运行
  • hermes gateway status——随时查看网关运行状态
  • tail -f ~/.hermes/logs/gateway.log——查看网关实时日志，排查问题
  • Start the service now?——问是否立即启动，直接回车或输 Y

看到 ✓ Service started 说明网关已经在后台跑起来了。

第七步，确认配置完成。 最后一行输出：

code
✓ Messaging Platforms (Gateway) configuration complete!

到这里，飞书的全部配置已经完成。下面验证一下。

3.4 测试收发

现在掏出手机，打开飞书（移动/PC 均可）。找到你创建飞书应用时命名的应用名。我的叫“姜磺的 Hermes”。打开会进入一个单聊窗口。

发一条消息：

你好，你现在能收到我的消息吗？

如果这是你第一次跟这位机器人对话，它可能不会直接回复你，而是返回一串配对码：

code
Hi~ I don't recognize you yet!
Here's your pairing code: LAB3M1CE
Ask the bot owner to run:
  hermes pairing approve feishu LAB5M4CE

这是 Hermes 的安全机制——陌生用户需要经过主人批准才能通信。把终端里输出的那条 hermes pairing approve 命令直接复制执行（注意将最后的 pairing code 换成你收到的）：

Bash
hermes pairing approve feishu LAB3M1CE

批准之后，再发一次消息，就能正常收到 Hermes 的回复了。

几秒钟后，终端上的 Hermes 会处理这条消息，然后把回复推回飞书。在手机上能看到 Hermes 的回复弹出来。

再试一条更有内容的：

帮我算一下 3847 + 2918 等于多少

Hermes 算完会把结果发回来：

alt text

这条消息经历了这样的路径：

code
飞书 App  ──→ 飞书服务器 ──→ Hermes 网关 (你的 PC) ──→ Hermes Agent
                                                        │
飞书 App  ←── 飞书服务器 ←── Hermes 网关 (你的 PC) ←────── 回复

整个过程两三秒。Hermes 在 PC 上跑着，手机只是收发消息的入口，和第一节说的模式一模一样。

💡提示

收发测试做完后，Hermes 可能会发来这样一条提醒：

code
No home channel is set for Feishu. A home channel is where Hermes delivers
cron job results and cross-platform messages.

Type /sethome to make this chat your home channel, or ignore to skip.

Home Channel(主频道) 就是 Hermes 推送定时任务结果和跨平台消息的「默认收件箱」。直接在聊天里输入 /sethome 就行，把当前对话设为收件箱。

alt text

3.5 网关做了什么

什么是网关

网关是 Hermes 对外收发消息的「接线员」。你在飞书里发一条消息，飞书服务器不知道 Hermes 在哪，它只认网关。网关收到了消息，再转给 Hermes 处理。Hermes 的回复也先回到网关，再由网关发回飞书。整个过程里，网关是唯一的对外出口。

没有公网 IP，飞书怎么找到 Hermes

这里有一个问题。假设你在自己家的 PC 上跑 Hermes，这台 PC 只有局域网 IP（比如 192.168.x.x），没有公网 IP。理论上，飞书服务器根本找不到这台 PC 的地址，自然也没法把消息发过来。

通常，你需要用一些类似内网穿透的方案，来解决这个问题。

那 Hermes 的网关是怎么解决的？

网关启动后，主动向飞书服务器发起一个 WebSocket 长连接。因为是网关主动找飞书，而不是飞书来找网关，所以不需要公网 IP、不需要端口映射、不需要配置路由器。只要你的电脑能上网，这个连接就能建立。

这和传统方案正好反过来。传统方案需要在路由器上开端口、配 DDNS、搞内网穿透，对普通用户来说门槛太高。Hermes 的出站连接把这些全绕过去了。

约束

网关和飞书之间会维持 WebSocket 长连接不会断。你在飞书里发一条消息，飞书服务器通过这条 WebSocket 推给网关，网关转给 Hermes 处理，回复再通过同一条连接推回飞书。一来一回，通道不变。

当然，这个机制也有缺点：电脑必须开着，网关必须长期保持开启状态。

到这一节为止，飞书的双向通道已经打通。那么现在，你可以尝试把之前章节里监控价格的应用修改一下，当满足价格阈值后，直接给你的飞书发个消息，提醒你去付款？

试一试。

3.6 ■ 学点英语

中文 English 音标 说明
飞书集成 Feishu Integration /ˈfeɪʃuː ˌɪntɪˈɡreɪʃən/ 把飞书消息、文档或审批能力接入自动化系统
权限范围 Permission Scope /pərˈmɪʃən skoʊp/ 应用被授权访问的资源和操作边界
事件订阅 Event Subscription /ɪˈvent səbˈskrɪpʃən/ 让系统接收平台事件通知的配置
访问令牌 Access Token /ˈækses ˈtoʊkən/ 用于证明调用方已获得授权的凭证