Hermes Agent 支持配置个人微信（Weixin）和企业微信（WeCom），两者是完全不同的系统，配置方法、接口和技术原理都不一样。

本文分成两个独立部分，详细介绍配置步骤。

个人微信与企业微信的区别

• 个人微信：使用 iLink Bot API，长轮询方式，无需公网
• 企业微信：使用 AI Bot WebSocket，无需公网

第一部分：Hermes 配置个人微信（Weixin）

1. 前置条件

• 一个个人微信账号
• 已安装 Python 环境
• 安装以下 Python 包：

pip install aiohttp cryptography
# 可选：让终端显示二维码更方便
pip install qrcode

这些包的作用：

• aiohttp：负责网络通信
• cryptography：处理微信媒体文件的加密解密
• qrcode：在命令行里直接显示二维码（不装也没关系，Hermes 会给你二维码链接）

2. 使用设置向导（推荐）

1. 在终端输入命令：hermes gateway setup
2. 当它问你选哪个平台时，选择 Weixin
3. 向导会自动向 iLink Bot API 请求一个二维码，在终端显示二维码（或者给你一个链接）
4. 用手机微信扫描二维码并确认登录
5. 成功后会提示"微信连接成功，account_id=xxxxxxxx"

所有账号信息（account_id、token 等）会自动保存到 ~/.hermes/weixin/accounts/ 文件夹里，后面不用手动填。

3. 配置环境变量

打开文件 ~/.hermes/.env，至少添加下面这行：

WEIXIN_ACCOUNT_ID=你的 account_id  # 从向导里复制

其他常用可选配置：

# 限制谁能私聊机器人（默认任何人可以）
WEIXIN_DM_POLICY=open       # 改成 allowlist 则只允许白名单
WEIXIN_ALLOWED_USERS=用户 ID1，用户 ID2     # 白名单用逗号隔开

# 群聊默认关闭（防止机器人被拉进很多群乱回复）
WEIXIN_GROUP_POLICY=disabled

# 定时任务或通知发到哪个聊天（可选）
WEIXIN_HOME_CHANNEL=聊天 ID
WEIXIN_HOME_CHANNEL_NAME=Home

# 老版本多行消息拆分行为（一般不用改）
WEIXIN_SPLIT_MULTILINE_MESSAGES=true

4. 启动 Hermes Gateway

hermes gateway

启动后，Hermes 会自动恢复保存的凭证，开始长轮询接收消息。你就能在个人微信里和 AI 聊天了。

5. 个人微信支持的功能

• 无需公网：全程长轮询，不需要服务器端口
• 扫码登录：超级简单
• 支持私聊 + 群聊：群聊默认关闭，可手动打开
• 支持图片、视频、文件、语音：自动加密解密
• Markdown 格式：标题、表格、代码块都会自动优化成微信好看的样式
• 智能分消息：一条回复尽量保持在一个气泡里，只有超长才合理拆分
• 正在输入提示：AI 思考时微信会显示"正在输入…"
• 消息去重：防止重复处理
• 自动重试：网络抖动也能自动恢复

6. 访问策略

私聊策略（DM Policy）：

• open（默认）：任何人可以私聊
• allowlist：只允许白名单用户
• disabled：完全关闭私聊
• pairing：配对模式（初期调试用）

群聊策略（Group Policy）：

• disabled（默认）：所有群都不回复（推荐先这样设置）
• open：所有群都回复
• allowlist：只在指定群回复

7. 媒体文件处理

微信媒体全部走 AES-128-ECB 加密 CDN，Hermes 自动处理：

• 收到图片/视频/文件 → 自动下载、解密、缓存
• 发送图片/视频/文件 → 自动加密上传

第二部分：Hermes 配置企业微信（WeCom）

1. 前置条件

• 一个企业微信组织账号（公司/团队已开通企业微信）
• 在企业微信管理后台创建 AI Bot：
  1. 登录企业微信管理后台
  2. 进入应用→创建应用→AI Bot
  3. 填写机器人名字和描述
  4. 复制 Bot ID 和 Secret（非常重要！）
• 安装 Python 包：pip install aiohttp httpx

2. 配置方式

方式一（推荐）：使用设置向导

hermes gateway setup

选择 WeCom，输入刚才复制的 Bot ID 和 Secret。

方式二：手动写环境变量

WECOM_BOT_ID=你的 Bot_ID
WECOM_SECRET=你的 Secret

# 可选：限制私聊用户
WECOM_ALLOWED_USERS=用户 ID1，用户 ID2

# 可选：定时任务发到哪个聊天
WECOM_HOME_CHANNEL=聊天 ID

3. 启动 Hermes Gateway

hermes gateway

启动后，Hermes 会通过 WebSocket 实时连接企业微信。

4. 企业微信支持的功能

• WebSocket 实时通信：速度更快，更稳定
• 支持私聊 + 群聊：群聊默认开启
• 每个群可以单独设置白名单：超精细控制
• 支持图片、文件、语音、视频
• Markdown 富文本
• 回复模式流式输出：AI 回复会直接接在用户消息下面，体验更自然
• 自动重连：断网也能自动恢复

5. 访问策略（企业微信版）

私聊策略和个人微信一样（默认 open）。

群聊策略默认 open（所有群都回复）。

每个群单独白名单是最强大的功能，在 config.yaml 里可以这样配置：

platforms:
  wecom:
    enabled: true
    extra:
      bot_id: "your-bot-id"
      secret: "your-secret"
      groups:
        群 ID1:
          allow_from:
            - "用户 Alice"
            - "用户 Bob"
        "*":  # 其他所有群的默认规则
          allow_from:
            - "管理员"

6. 媒体文件处理

• 收到媒体 → 自动下载缓存（支持 URL 或 base64）
• 部分媒体有 AES-256-CBC 加密 → Hermes 自动解密
• 发送媒体 → 支持图片（10MB）、文件（20MB）、语音、视频，超大会自动降级成普通文件

常见问题

• 配置完启动没反应？ 检查 .env 文件路径是否正确，命令是否在正确目录运行
• 想改配置？ 修改 .env 或 config.yaml 后，重启 hermes gateway 即可
• 安全提醒：不要把 Secret、Token 泄露给别人。企业微信的 Bot ID/Secret 尤其重要
• 测试方法：配置完成后，在微信里@机器人或私聊发一句"Hello"，看是否回复

总结

• 个人微信：扫码登录 → 简单快速 → 适合个人使用
• 企业微信：创建 AI Bot → 更稳定、支持群精细控制 → 适合团队/公司使用