Hermes Agent 接入飞书，在手机上随时聊天

写在前面

为什么选飞书？

在服务器上部署了 Hermes Agent 后，最头疼的问题就是：怎么在手机上方便地跟它对话？

我考虑了三个方案：

方案	优点	缺点
SSH 客户端（Termius 等）	直连服务器，功能完整	手机打字体验差，频繁断开
自建网页	定制化强	需要公网 IP + HTTPS，部署维护成本高
接入即时通讯（IM）	体验最好，推送及时	需要配置开放平台

最终选择了 飞书，原因很简单：

1. WebSocket 连接 ------ 不需要公网 IP，内网服务器也能用

2. 消息推送 ------ 飞书自带推送通知，不用额外搭推送服务

3. 国内直连 ------ 服务器在中国大陆，飞书是国内服务，延迟低

适用场景

服务器在中国境内，需要一个能直连的即时通讯平台来跟 Hermes Agent 聊天。

---

一、环境概览

项目	说明
操作系统	Linux（CentOS 7 / Ubuntu 20.04+）
Hermes Agent	最新版，通过官方安装脚本部署
目标平台	飞书（Feishu，国内版）
连接方式	WebSocket 长连接（无需公网 IP）

---

二、整体架构

┌──────────────┐     WebSocket      ┌──────────────────┐
│  飞书 App     │◄──────────────────►│  Hermes Gateway   │
│  (手机/桌面)  │                    │  (你的服务器)     │
└──────────────┘                    └──────────────────┘

用户在飞书上给 bot 发消息 → Hermes Gateway 收到 → 调用 LLM 生成回复 → 文字推回飞书。

---

三、详细部署步骤

3.1 创建飞书应用

1. 打开 飞书开放平台，用飞书账号扫码登录

2. 点击右上角「创建应用」→ 选择「企业自建应用」

3. 给应用取名（例如 "我的助手"），上传头像（可选）

4. 创建完成后，进入「凭证与基础信息」，记下 App ID 和 App Secret（后面要用）

5. 左侧导航栏「应用功能」→「机器人」→ 开启机器人开关

注意：App Secret 只显示一次，建议立即保存到安全位置。

---

3.2 配置权限

进入「权限管理」，点击「添加权限」，搜索并添加以下权限：

权限	用途
im:message	收发消息
im:message:send_as_bot	以 bot 身份发送消息
im:resource	收发图片、文件
im:chat	获取聊天信息

添加完成后点击「批量开通」。

---

3.3 订阅事件

进入「事件与回调」→「事件配置」：

1. 点击「添加事件」

2. 搜索并选择 im.message.receive_v1（接收消息事件）

3. 连接方式选择 「长连接（WebSocket）」

这是关键一步。选择 WebSocket 模式后，你的服务器不需要公网 IP，只需要能主动访问飞书的 WebSocket 网关即可。内网服务器也能用。

---

3.4 发布应用

右上角「发布」→ 创建版本号（如 1.0.0）→ 填写更新说明 → 提交审核。

个人账号通常秒过 ，企业账号可能需要管理员审批。

---

3.5 配置 Gateway 环境变量

编辑 ~/.hermes/.env，添加以下配置：

# 飞书配置
FEISHU_APP_ID=cli_xxxxxxxxxxxxxxx       # 替换为你的 App ID
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxx   # 替换为你的 App Secret
FEISHU_DOMAIN=feishu                    # 国内版用 feishu，海外版用 lark
FEISHU_CONNECTION_MODE=websocket        # WebSocket 长连接模式

.env 文件如果不存在，直接新建即可。Hermes 启动时会自动读取。

---

3.6 启动 Gateway

# 前台运行（方便看日志排查问题）
hermes gateway run

日志中看到以下内容即为连接成功：

INFO  gateway.run: Connecting to feishu...
INFO  [Feishu] Connected in websocket mode (feishu)
INFO  gateway.run: ✓ feishu connected
INFO  Lark: connected to wss://msg-frontier.feishu.cn/ws/v2?...

确认正常后，可以安装为 systemd 服务以便后台常驻：

hermes gateway install

---

3.7 配对用户

在飞书中给 bot 发送任意消息，bot 会回复一个配对码：

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

回到服务器执行配对：

hermes pairing approve feishu X6UCJW57

输出：

Approved! User ou_xxx on feishu can now use the bot~

建议将用户 ID 加入白名单，避免每次重启都需要重新配对：

echo 'FEISHU_ALLOWED_USERS=ou_xxxxxxxxxxxxxx' >> ~/.hermes/.env

---

3.8 设置主页（可选）

在飞书聊天中发送 /sethome，将当前对话设为 home channel。设置后，该对话可用于接收定时任务推送和跨平台消息转发。

---

四、总结

将 Hermes Agent 接入飞书的核心流程只有几步：

1. 飞书开放平台 创建应用 → 开启机器人 → 配置权限 → 订阅消息事件（WebSocket 模式）

2. 服务器 配置环境变量 → 启动 Gateway → 配对用户

完成之后，你就可以在手机上用飞书随时跟 Hermes 聊天了。不需要公网 IP，不需要搭网页，不需要 SSH 连服务器，打开飞书就能发消息。

---

如果你也在折腾 Hermes Agent 接入即时通讯，欢迎在评论区交流～