微信与飞书接入文档

记录日期：2026-07-07 基于 Hermes Agent 的多平台消息网关配置

一、环境概况

操作系统：Linux (6.1.0-40-amd64)
Hermes 版本：0.18.0
模型：agnes-2.0-flash
Provider：custom (apihub.agnes-ai.com)
Gateway 运行方式：systemd 用户服务（hermes-gateway.service）
Linger：已启用（SSH 断开后服务仍持续运行）

二、微信（Weixin）接入

2.1 接入方式

选择 Weixin（个人微信），通过 Baileys 协议桥接，而非企业微信（WeCom）。

2.2 配置步骤

运行网关配置向导
```
hermes gateway setup
```
在交互式菜单中选择 Weixin / WeChat 平台进行配置。
扫码登录

网关会输出一个二维码，用手机微信扫描完成登录。

安装 Gateway 为后台服务

hermes gateway install
hermes gateway start

启用 Linger（防止 SSH 断开后服务停止）
```
sudo loginctl enable-linger $USER
```

2.3 配置文件

~/.hermes/.env 中写入的微信相关变量：

WEIXIN_ACCOUNT_ID=805e47d2138b@im.bot
WEIXIN_TOKEN=805e47d2138b@im.bot:060000d3df84179398a66cd5268e03c75cce9c
WEIXIN_BASE_URL=https://ilinkai.weixin.qq.com
WEIXIN_CDN_BASE_URL=https://novac2c.cdn.weixin.qq.com/c2c

~/.hermes/config.yaml 中无独立的 weixin 区块配置，全部通过 .env 管理。

2.4 用户审批（Pairing）

微信默认采用配对审批机制。新用户首次发送消息时会生成配对码，管理员需审批后才能通信。

# 查看待审批列表
hermes pairing list

# 审批配对码（格式：hermes pairing approve <platform> <code>）
hermes pairing approve weixin <配对码>

当前已批准的用户： - User ID：o9cq8036BWZYIbOfCLsvic_ErTGg@im.wechat

如需允许所有用户免审批直接通信，可在 .env 中添加：

GATEWAY_ALLOW_ALL_USERS=true

或在 config.yaml 的 weixin 部分设置 dm_policy: open。

2.5 连接状态

Gateway 日志确认连接成功：

2026-07-06 15:50:05,332 INFO gateway.platforms.weixin: [Weixin] Connected account=805e47d2 base=https://ilinkai.weixin.qq.com
2026-07-06 15:50:05,338 INFO gateway.run: ✓ weixin connected

三、飞书（Feishu）接入

3.1 接入方式

通过 Hermes 内置的 Feishu 插件接入，使用 WebSocket 模式连接飞书中国版（域名 feishu）。

3.2 飞书开放平台配置

在飞书开放平台后台完成以下配置：

创建或选择已有应用
记录 App ID 和 App Secret
进入 事件与回调 → 事件订阅
添加事件：im.message.receive_v1（接收消息）
- 此步骤至关重要，缺少该事件订阅则机器人无法接收消息
配置验证 Token（Verification Token）— 用于 HMAC 签名校验
确保应用已发布上线（开发阶段仅限创建者/管理员使用）

3.3 配置文件

~/.hermes/.env 中写入的飞书相关变量：

FEISHU_APP_ID=cli_aac1d51fa2781be3
FEISHU_APP_SECRET=kppeoDqzqsjlZoQUiU97revcUSSMlP8F

~/.hermes/config.yaml 中的配置：

gateway:
  feishu:
    app_id: cli_aac1d51fa2781be3
    app_secret: kppeoDqzqsjlZoQUiU97revcUSSMlP8F
    enabled: true

plugins:
  enabled:
    - platforms/feishu
  disabled: []

3.4 连接状态

Gateway 日志确认连接成功：

2026-07-06 17:28:08,944 INFO gateway.run: Connecting to feishu...
2026-07-06 17:28:09,450 INFO hermes_plugins.feishu_platform.adapter: [Feishu] Connected in websocket mode (feishu)
2026-07-06 17:28:09,459 INFO gateway.run: ✓ feishu connected

3.5 已知问题

机器人收不到用户消息：

现象：WebSocket 连接成功（日志显示 [Feishu] Connected in websocket mode），但用户发消息后机器人无反应
排查步骤：
1. 检查 Gateway 日志中是否有 [Feishu] dropping inbound event（DEBUG 级别），有则说明消息到达了但被拒绝
2. 检查飞书开放平台 事件订阅 是否已添加 im.message.receive_v1 事件
3. 检查飞书开放平台 权限管理 是否已开启以下权限：
  - im:message:readonly — 读取用户发给机器人的单聊消息
  - 群组中@机器人时接收消息 — 允许在群聊中通过 @提及触发机器人
4. 确认应用已发布上线，且你的飞书账号在应用的 可用范围 内
5. 确认事件接收方式为 长连接（WebSocket），而非 HTTP 回调
原因：没有开启这获取用户发给机器人单条消息和获取群组中用户@机器人消息权限权限
解决：开启上述权限后重新发布应用，Gateway 无需重启即可生效

3.6 Home Channel

首次使用时会收到提示：

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

解决方法：在飞书聊天中输入 /sethome 将该对话设为主频道，用于接收 Cron 任务结果和跨平台消息。

四、Gateway 服务管理

4.1 常用命令

# 查看状态
hermes gateway status

# 启动 / 停止 / 重启
hermes gateway start
hermes gateway stop
hermes gateway restart

# 查看日志
tail -f ~/.hermes/logs/gateway.log

# 查看特定平台日志
grep -i "feishu|weixin" ~/.hermes/logs/gateway.log | tail -20

4.2 系统服务信息

● hermes-gateway.service - Hermes Agent Gateway - Messaging Platform Integration
   Loaded: loaded (/root/.config/systemd/user/hermes-gateway.service; enabled)
   Active: active (running)
   Main PID: 3352381 (hermes)

4.3 双平台同时运行

重启后 Gateway 日志显示同时运行两个平台：

2026-07-06 17:28:09,568 INFO gateway.run: Gateway running with 2 platform(s)

五、关键文件路径

文件	用途
`~/.hermes/config.yaml`	主配置文件（模型、网关、插件等）
`~/.hermes/.env`	环境变量（API Key、平台凭证）
`~/.hermes/logs/gateway.log`	Gateway 运行日志
`~/.hermes/auth.json`	OAuth 令牌和凭证池
`/root/.config/systemd/user/hermes-gateway.service`	systemd 服务单元文件