Hermes + 微信 / 钉钉 / 企微配置指南

总览：Hermes 支持的中国个人即时通讯

平台	支持情况	接入方式	个人可用？	难度
📱 个人微信	✅ 支持	iLink Bot API (腾讯官方)	✅ 个人可注册	⭐⭐⭐
🏢 企业微信	✅ 支持	WeCom AI Bot WebSocket	❌ 需企业账号	⭐⭐
🔷 钉钉	✅ 支持	DingTalk Stream Mode	✅ 个人开发者可申请	⭐⭐
💬 飞书	✅ 支持	Feishu WebSocket/Webhook	❌ 需企业账号	⭐⭐
🟢 其他 (QQ/米聊等)	❌ 不支持	—	—	—

核心结论： 个人微信（微信个人号）可以接入，通过腾讯官方的 iLink Bot API；其他中国个人即时通讯中，钉钉个人开发者也可接入，企业微信和飞书需要企业账号。QQ 等平台目前无原生支持。

架构示意图

一、个人微信 (Weixin) 接入

Hermes 通过腾讯官方 iLink Bot API (ilinkai.weixin.qq.com) 接入个人微信。这是腾讯官方提供的个人微信机器人接口，使用 Long-Poll 模式轮询消息。

1.1 注册 iLink Bot

浏览器打开 https://ilinkai.weixin.qq.com
使用微信扫码登录
注册 Bot 账号，获取 Bot Token 和 Account ID
记录下这两个值

1.2 .env 配置

# ========== 个人微信 (必填) ==========
WEIXIN_TOKEN=your_bot_token_here
WEIXIN_ACCOUNT_ID=your_account_id_here

# ========== 连接配置 (可选) ==========
WEIXIN_BASE_URL=https://ilinkai.weixin.qq.com    # 默认值
WEIXIN_CDN_BASE_URL=https://novac2c.cdn.weixin.qq.com/c2c  # 媒体CDN

# ========== 权限控制 (可选) ==========
WEIXIN_DM_POLICY=open              # open | allowlist | disabled | pairing
WEIXIN_GROUP_POLICY=disabled       # open | allowlist | disabled (默认关闭)
WEIXIN_ALLOWED_USERS=wxid_xxx1,wxid_xxx2  # 允许私聊的用户
WEIXIN_GROUP_ALLOWED_USERS=xxx@chatroom    # 允许响应的群

# ========== 消息调优 (可选) ==========
WEIXIN_SPLIT_MULTILINE_MESSAGES=true    # 拆分行数较多的消息
WEIXIN_SEND_CHUNK_DELAY_SECONDS=1.5     # 分块发送延迟
WEIXIN_SEND_CHUNK_RETRIES=4             # 发送重试次数

1.3 config.yaml 配置

gateway:
  enabled: true
  platforms:
    weixin:
      enabled: true
      token: "your_bot_token"     # 或 WEIXIN_TOKEN env
      extra:
        account_id: "xxx"         # 或 WEIXIN_ACCOUNT_ID env
        dm_policy: "open"
        group_policy: "disabled"  # 群聊默认关闭，需要再开
        split_multiline_messages: true

1.4 注意事项

需要 pip install aiohttp cryptography（加密库用于媒体文件解密）
Bot 需要保持在线，通过 QR 码登录
每条回复需要通过 context_token 关联对话上下文
群聊功能默认关闭（group_policy: disabled），如需开启需谨慎配置白名单
消息去重 TTL 300 秒

二、企业微信 (WeCom) 接入

Hermes 通过 WeCom AI Bot WebSocket 网关 接入企业微信。适用于企业内使用企业微信的场景。

2.1 创建企业微信 AI Bot

登录企业微信管理后台 → 应用管理 → 自建 → 创建应用
选择「机器人」类型，获取 Bot ID 和 Secret
配置消息接收方式为 WebSocket

2.2 .env 配置

WECOM_BOT_ID=your_bot_id
WECOM_SECRET=your_secret
WECOM_WEBSOCKET_URL=wss://openws.work.weixin.qq.com  # 默认
WECOM_DM_POLICY=open          # open | allowlist | disabled | pairing
WECOM_GROUP_POLICY=open       # open | allowlist | disabled

2.3 config.yaml 配置

gateway:
  enabled: true
  platforms:
    wecom:
      enabled: true
      extra:
        bot_id: "your-bot-id"
        secret: "your-secret"
        dm_policy: "open"
        group_policy: "open"
        # 白名单配置：
        # allow_from: ["user_id_1"]
        # group_allow_from: ["group_id_1"]

2.4 功能特点

WebSocket 长连接，无需公网 IP
支持 Markdown 消息发送
消息长度限制 4000 字符
支持图片、文件上传
自动断线重连（指数退避）
消息去重

三、钉钉 (DingTalk) 接入

Hermes 通过 DingTalk Stream Mode（钉钉官方流模式 SDK）接入，个人开发者可申请。

3.1 创建钉钉应用

登录钉钉开放平台
创建应用 → 选择「机器人」能力
获取 Client ID（App Key）和 Client Secret
配置 Stream Mode 接收消息

3.2 .env 配置

DINGTALK_CLIENT_ID=your_client_id       # 必填
DINGTALK_CLIENT_SECRET=your_secret      # 必填
DINGTALK_REQUIRE_MENTION=true           # 是否必须 @ 才响应
DINGTALK_FREE_RESPONSE_CHATS=cidXXX,cidYYY  # 免 @ 的群聊

3.3 config.yaml 配置

gateway:
  enabled: true
  platforms:
    dingtalk:
      enabled: true
      require_mention: true
      free_response_chats:
        - cidABC==
      extra:
        client_id: "your-app-key"
        client_secret: "your-secret"

3.4 功能特点

Stream Mode 长连接，无需公网 IP
支持文本、图片、音频、视频、文件
群聊 @ 提及检测（结构化数据）
支持 AI Cards 富卡片消息（需额外 SDK）
消息长度上限 20000 字符
会话 Webhook 发送回复

四、使用方法

4.1 私聊 (DM)

个人微信 — Bot 注册后，微信好友直接向 Bot 对话窗口发消息
企业微信 — 成员在企业微信中搜索 Bot 名称，发起对话
钉钉 — 在钉钉中搜索机器人名称，发送消息
除非设置了白名单，默认所有用户均可私聊（dm_policy: open）

4.2 群聊

平台	群聊支持	触发方式	默认
个人微信	✅	@Bot 或群内直接回复	❌ 默认关闭 (disabled)
企业微信	✅	@Bot 或直接触发	✅ 默认开启 (open)
钉钉	✅	@Bot 或免 @ 白名单群聊	✅ 需 @ 默认开启

4.3 常用命令

命令	说明
`/help`	查看所有可用命令
`/new`	重置当前会话
`/title <name>`	命名会话
`/retry`	重新生成回复
`/undo`	撤回上一轮
`/model <name>`	切换模型
`/status`	查看会话状态
`/platforms`	查看所有平台连接状态
`/restart`	重启 Gateway
`/sethome`	设置当前聊天为 home 频道

4.4 权限密码学

dm_policy — 私聊策略: open(开放), allowlist(白名单), disabled(关闭), pairing(配对)
group_policy — 群聊策略: open, allowlist, disabled
allow_from / allowed_users — 用户白名单列表
group_allow_from / group_allowed_users — 群聊白名单

4.5 多媒体支持

个人微信 — 图片/文件通过 AES-128-ECB 加密 CDN 传输
企业微信 — 支持图片、文件、语音（AMR 格式）
钉钉 — 支持图片、音频、视频、文件，通过 download code 获取
语音消息支持转录文字（需 STT 组件）

五、能否接入其他中国个人即时通讯？

平台	状态	原因
个人微信	✅ 官方支持	腾讯 iLink Bot API 官方接口
企业微信	✅ 官方支持	WeCom AI Bot WebSocket
钉钉	✅ 官方支持	DingTalk Stream Mode SDK
飞书	✅ 官方支持	Feishu WebSocket/Webhook
QQ	❌ 无官方支持	QQ 官方未开放 Bot API；非官方方案（Mirai/OICQ等）有封号风险，Hermes 不内置
米聊 / 陌陌 / Soul 等	❌ 不支持	无开放 API，非主流平台
短信 (SMS)	✅ 支持	通过 SMS 平台适配器（需第三方服务）

结论： Hermes 目前支持 4 款中国 IM 平台（微信/企微/钉钉/飞书），覆盖了绝大多数中国用户群体。个人用户可用的有 个人微信（iLink）和钉钉，企业用户可全选。QQ 等平台建议使用 Telegram 或微信作为替代。

六、启动与验证

# 安装依赖（按需选择）
pip install lark-oapi                   # 飞书
pip install "dingtalk-stream>=0.20" httpx  # 钉钉
pip install aiohttp cryptography        # 个人微信

# 启动 Gateway
hermes gateway run

# 或安装为后台服务
hermes gateway install
hermes gateway start

# 查看日志
tail -f ~/.hermes/logs/gateway.log | grep -E "weixin|wecom|dingtalk|feishu"

🟢 验证：在对应 IM 平台的 Bot 对话窗口中发送消息，看 Hermes 是否回复。

Hermes + 微信 / 钉钉 / 企微 配置指南