💡阅读指南

微信的接入方式比较独特，走的是腾讯 iLink Bot 接口，连上来的是一个 bot（机器人）身份，不是个人微信号。

首先接入的一定是微信，大多数人手机里未必有飞书、钉钉、QQ，但一定有微信。

Hermes 接个人微信，走的是腾讯 iLink Bot 接口。连上来的不是一个个人微信号，而是一个 bot 身份，账号格式是 xxx@im.bot。

这个身份带来几个限制，接入之前需要了解清楚。

bot 不能拉进普通微信群。iLink Bot 只支持被添加到特定的"机器人群"中，普通的微信群无法加入。

你只能手动输入消息，或者复制消息发送给 Bot，无法转发消息或者公众号链接。因为你在转发列表里根本看不到这个微信 bot。

咱也不知道为啥要做这样的限制，反正使用起来极其不方便，挺恶心的。

但 1 对 1 和 bot 私聊是没有问题的。

一句话概括：微信接入适合做个人助理，不适合做公共服务。

2.2 接入步骤

确保手机上有微信，并且能正常登录。

打开终端，运行：

Bash
hermes gateway setup

或者，如果你用 Desktop，直接在对话里输入：

我需要将 WeChat 接入 Hermes

终端会列出可选平台列表。用上下键浏览，按空格选中 WeChat（前面出现 ✓ 标记），再按回车确认。

💡提示

如果列表里没有 WeChat 选项，确认 Hermes 版本是否支持。目前 WeChat 通道通过 iLink Bot 接口接入，可能需要特定版本或配置。

选中后，终端会弹出二维码。打开手机微信，扫码授权。授权成功后，Hermes 会自动完成后续配置。

配置完成后，终端输出一段摘要：

code
✓   Bot connected: Hermes WeChat Bot
✓   DM pairing enabled.
    Unknown users can request access; approve with `hermes pairing approve`.

  Home chat ID (optional, for cron/notifications):
  • Bot connected：微信 bot 已连接成功
  • DM pairing enabled：私聊配对已开启，陌生人发消息需要先配对
  • Home chat ID：询问是否设置"主频道"，用于接收定时任务和通知。直接回车跳过，后续可以随时配置。

接着会问是否安装为后台服务。选 Y（默认），让网关一直在后台运行。

code
✓ Service installed and loaded!

到这一步，微信接入已经完成。

📌gateway 是什么？

gateway 是 Hermes 的「后台守门员」，专门负责和外部的聊天平台（微信、飞书、Telegram 等）打交道。你可以把它理解成一个常驻后台的「收发室」——接收你从微信发来的消息，转给 Hermes 处理，再把结果发回微信。后面会有一整节专门讲 gateway 的配置和原理。

2.3 测试收发

打开微信，找到 Hermes bot。在通讯录里搜索机器人名称，找到后发一条消息：

你好，能收到吗？

如果是第一次对话，bot 不会直接回复，而是返回一串配对码：

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

这是 Hermes 的安全机制：陌生用户需要经过主人批准才能通信。在终端里执行那条配对命令（注意把最后的配对码换成收到的那个）：

Bash
hermes pairing approve wechat LAB3M1CE

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

再试一条有实际内容的：

帮我算一下 5280 除以 16 等于多少

Hermes 算完会把结果发回来。消息路径和飞书一样：

code
微信 App  ──→ 微信服务器 ──→ Hermes 网关 ──→ Hermes Agent
                                                         │
微信 App  ←── 微信服务器 ←── Hermes 网关 ←─────────────── 回复

2.4 核心概念

配置完成后，有两个概念值得理解：Home Channel 和 DM 私聊策略。

Home Channel：消息的默认投递地址

Home Channel 是 Hermes 的一个重要概念。当机器人在非回复场景下需要主动发送消息，比如定时任务执行完了、系统出了通知、跨平台消息需要转发，它该往哪个会话发？

每个平台都可以设置一个 home channel。在微信里，向 Hermes 输入 /sethome 命令，把当前对话设为 home channel：

/sethome

设好之后，所有非回复性的消息都会投递到这个对话里。不设也不影响正常收发，只是定时任务的结果和系统通知不会主动推送过来。

设置时机不限。可以在配置完成后立刻设，也可以等 Hermes 提醒时再设。

DM 私聊策略的四个选项

Hermes 的微信 bot 面对陌生人发来的消息，有四种处理方式。可以在 config.yaml 中设置，也可以通过 hermes 命令设置。

Use DM pairing approval（推荐）

陌生人第一次发消息，bot 不直接回复，而是返回一个配对码。把配对码拿到终端里用 hermes pairing approve 批准，之后才能正常通信。

这是最推荐的方式。既不让陌生人随意使用 Hermes，也不像白名单那么死板，临时有人需要联系，给个配对码就行。

Allow all direct messages

来者不拒。任何人给 bot 发消息，Hermes 都会处理并回复。

最方便，也最不安全。适合测试环境或完全公开的机器人。

Only allow listed user IDs

只响应指定的微信用户。其他人的消息全部忽略。

最严格的安全策略。适合固定的小范围使用场景，比如几个家人或同事。

Disable direct messages

私聊功能完全关闭。bot 不会响应任何私聊消息。

如果暂时不想开放微信通道，只想用 Hermes 处理其他平台的消息，可以用这个选项暂时关闭。

四种策略可以在运行中随时切换，不需要重新配置网关。

2.5 局限性提醒

最后再强调一下微信接入的边界。

第一，bot 身份不能进普通微信群。如果需要群聊能力，飞书或 Telegram 是更好的选择。

第二，群事件收不到。即使 bot 在群里，也无法感知群成员变动、消息撤回等事件。

第三，iLink Bot 接口的稳定性取决于腾讯的服务。偶尔可能出现消息延迟或连接断开的情况，网关会自动重连。

微信接入最适合的场景是：一个人私聊使用，收发指令、接收通知。如果需要复杂的群聊互动或事件驱动的工作流，建议配合飞书或其他平台一起使用。

两条通道各有各的位置，不冲突。

2.6 ■ 学点英语

中文 English 音标 说明
微信集成 WeChat Integration /ˈwiːtʃæt ˌɪntɪˈɡreɪʃən/ 把微信消息接入外部系统的方案
聊天界面 Chat Interface /tʃæt ˈɪntərfeɪs/ 用户通过对话发送指令和接收结果的界面
消息回调 Message Callback /ˈmesɪdʒ ˈkɔːlbæk/ 平台在收到消息后主动通知服务端的机制
会话绑定 Session Binding /ˈseʃən ˈbaɪndɪŋ/ 把平台用户和系统会话关联起来的过程