本教程共 25 篇 · 第 15 篇 · 更新于 2026-07-26 · 约 22 分钟阅读

15. 代表性消息平台接入详解

本节目标：搞懂 Telegram、Discord、Slack、WhatsApp、微信、企业微信、钉钉、飞书这八个主流平台各自的接入方式和配置差异，学完你能根据团队情况选对平台并完成基础接入。

上一章我们讲了 30+ 平台共用一个 Gateway 的整体架构。这一章我挑八个最有代表性的平台，挨个拆给你看——它们怎么创建机器人、怎么填凭据、会话模型有什么不同、有哪些专属特性。

先上一张速查表，心里有个数：

平台	连接方式	是否需要公网	凭据获取难度	特色能力
Telegram	Long-poll / Webhook	否（长轮询）	低（BotFather 一条命令）	命令菜单、状态指示
Discord	WebSocket	否	中（开发者后台）	群组会话隔离、WS 健康检查
Slack	Socket Mode	否	中（App Manifest）	一键生成清单、文件协作
WhatsApp	Baileys 桥接	否	低（扫码登录）	个人号即机器人
微信	iLink Bot API	否	低（扫码）	长轮询、AES 加密媒体
企业微信	AI Bot WebSocket	否	中（管理后台）	扫码建机器人、群组放行
钉钉	Stream Mode	否	中（开发者后台）	AI 卡片、表情反馈
飞书 / Lark	WebSocket / Webhook	否（WS）/ 是（Webhook）	中（开发者后台）	互动卡片、文档评论、会议邀请

你会发现一个共性：除了飞书的 Webhook 模式，其余平台都不需要公网 IP，连接都是从你这边主动发起的。这对本地部署和内网环境非常友好。

Telegram：最省心的入门平台

Telegram 是我推荐新手第一个接入的平台。为什么？创建机器人只要跟 BotFather 说一句话，拿到 Token 填进配置就能跑，整个流程五分钟。

创建机器人

在 Telegram 搜索 @BotFather，发送 /newbot。
按提示输入机器人名称和用户名（用户名必须以 bot 结尾）。
BotFather 返回一段 Token，形如 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11，复制保存。

Warning

Token 等于机器人的钥匙，泄露了别人就能冒充你的机器人。别提交到 Git，别发到群里。

配置并启动

把 Token 写进 ~/.hermes/.env：

TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

# 可选：限制谁能用
TELEGRAM_ALLOWED_USERS=你的Telegram用户ID

# 可选：home 频道，用于定时任务推送
TELEGRAM_HOME_CHANNEL=聊天ID

启动网关：

hermes gateway

Telegram 默认走长轮询（long-polling），不需要公网。如果你想用 Webhook 模式（响应更快），可以配置 TELEGRAM_WEBHOOK_URL，但那需要有公网域名或反代。

命令菜单

Telegram 有个很实用的功能：命令菜单。用户点击输入框左下角的 / 按钮，会弹出可用命令列表。Hermes 会自动把技能和插件的命令同步到这个菜单。

# config.yaml
gateway:
  platforms:
    telegram:
      extra:
        command_menu:
          max_commands: 60          # Telegram 上限 100，留点余量
          priority_mode: prepend    # 优先命令排在最前
          priority:
            - my_plugin_command

priority_mode 设成 prepend，你标记的优先命令会排在菜单顶部，方便用户第一时间找到。

状态指示

可以让机器人在处理消息时显示「正在输入」状态，体验更自然：

gateway:
  platforms:
    telegram:
      extra:
        status_indicator: true
        status_online: "🟢 Online"
        status_offline: "🔴 Offline"

Discord：群组会话隔离做得最细

Discord 的接入稍复杂一点，要去开发者后台创建 Application 并添加 Bot。但它的群组会话隔离机制是所有平台里最灵活的。

创建机器人

打开 Discord Developer Portal，点 New Application。
起个名字，创建后进入 Bot 页面，点 Reset Token 拿到 Bot Token。
在 Privileged Gateway Intents 里开启 Message Content Intent（否则读不到消息内容）。
用 OAuth2 -> URL Generator 生成邀请链接，勾选 bot 和 applications.commands，选好权限，用这个链接把机器人拉进你的服务器。

配置

DISCORD_BOT_TOKEN=你的Bot Token
DISCORD_ALLOWED_USERS=你的Discord用户ID

Tip

Discord 用户 ID 怎么拿？开启开发者模式（用户设置 -> 高级 -> 开发者模式），右键点自己头像选「复制用户 ID」。

群组会话隔离

这是 Discord 的亮点。在一个共享频道里，多个人同时跟机器人聊天，默认情况下每个人的会话是独立的——A 说的话机器人不会记到 B 的上下文里：

group_sessions_per_user: true   # 默认值：每人独立会话
# group_sessions_per_user: false  # 改成 false：整个频道共享一个会话

什么时候改成 false？比如你想做个「团队协作机器人」，所有人在同一个频道里共同讨论一个任务，这时候共享上下文更合理。

WebSocket 健康检查

Discord 用 WebSocket 长连接，网络抖动可能让连接「假死」（看起来连着，实际收不到消息）。Hermes 内置了健康检查：

discord:
  websocket_liveness_interval_seconds: 15      # 每 15 秒探活一次
  websocket_liveness_failure_threshold: 2       # 连续 2 次失败才判定断连
  websocket_heartbeat_ack_max_age_seconds: 60   # 心跳响应超过 60 秒算超时
  websocket_max_latency_seconds: 30             # 延迟超过 30 秒触发重连

这套参数我建议保持默认，除非你网络环境特别差，可以适当放宽阈值。

Slack：App Manifest 一键搞定权限

Slack 接入的痛点在于权限范围（Scopes）多且容易漏配。Hermes 提供了一条命令直接生成 App Manifest，省去手动勾选的麻烦。

用 Socket Mode（推荐）

Socket Mode 是 Slack 的出站 WebSocket 模式，不需要公网。步骤：

去 Slack API 创建一个 App。
在 Basic Information 里找到 App Manifest，贴入 Hermes 生成的清单：

hermes slack manifest --agent-view --write

这条命令会生成符合当前配置的 Manifest 并写入剪贴板或文件。贴进 Slack 后台，权限会自动配好。

开启 Socket Mode，生成一个 App-Level Token（以 xapp- 开头）。
把 Bot Token（xoxb-）和 App Token 填进配置：

SLACK_BOT_TOKEN=xoxb-你的Bot Token
SLACK_APP_TOKEN=xapp-你的App Token
SLACK_ALLOWED_USERS=你的Slack用户ID

必要的权限范围

如果你想手动配权限，至少需要这些 Scopes：

scopes:
  - chat:write              # 发消息
  - app_mentions:read       # 读 @提及
  - channels:history        # 读公开频道历史
  - channels:read
  - groups:history          # 读私有频道历史
  - im:history              # 读私信历史
  - im:read
  - im:write
  - mpim:history            # 读群聊历史
  - mpim:read
  - users:read
  - files:read              # 读文件
  - files:write             # 传文件

Note

Slack 在频道里必须 @mention 机器人才会响应，私信则不需要。这和 Discord、钉钉的行为一致。

WhatsApp：个人号即机器人

WhatsApp 的接入方式比较特殊——它不是官方提供的 Bot API，而是通过 Baileys 这个第三方库桥接你的个人 WhatsApp 账号。这意味着你用自己的手机号当机器人。

扫码登录

hermes whatsapp

这条命令会启动配置向导，终端打印一个二维码，用 WhatsApp 手机端扫描登录。登录态保存在 ~/.hermes/whatsapp-session/，重启网关不需要重新扫码。

两种模式

whatsapp:
  mode: bot         # bot 模式：别人发消息给这个号，机器人回复
  # mode: self-chat  # self-chat 模式：自己给自己发消息，当私人助手用
  session_path: ~/.hermes/whatsapp-session
  auto_reconnect: true
  qr_code_size: 20

self-chat 模式适合把 WhatsApp 当成「给自己发指令的入口」，比如你在外面想到一个点子，发给自己号，机器人帮你记到笔记里。

Warning

WhatsApp 桥接用的是非官方协议，存在封号风险。建议用小号或专门号码，别拿主号试。

微信（个人号）：iLink Bot API

微信个人号的接入走的是腾讯的 iLink Bot API，通过扫码连接一个「iLink 机器人身份」。注意，这个身份和你扫码用的微信号不是一回事。

扫码连接

hermes gateway setup

选 Weixin，终端显示二维码，用微信扫码确认。连接成功后凭证自动保存到 ~/.hermes/weixin/accounts/。

配置环境变量

WEIXIN_ACCOUNT_ID=你的account_id
# Token 通常自动保存，一般不用手动填
# WEIXIN_TOKEN=你的bot token

# 访问控制
WEIXIN_DM_POLICY=open
WEIXIN_ALLOWED_USERS=user_id_1,user_id_2

# home 频道
WEIXIN_HOME_CHANNEL=chat_id

iLink 机器人身份的限制

这是微信接入最容易踩坑的地方，我必须重点说：

Warning

扫码连接的是 iLink 机器人身份（比如 a5ace6fd482e@im.bot），不是一个可以完全脚本化的普通微信号。后果是：

这个机器人身份通常无法被邀请进普通微信群。

iLink 通常不会把普通微信群消息推送给网关。

@ 扫码用的微信号 ≠ @ 机器人，两者是独立身份。

实际部署中，私聊机器人基本能稳定工作；群聊能不能用，取决于 iLink 是否为你的账号类型返回群事件，大多数情况下不行。这不是 Hermes 的问题，是 iLink 侧的限制。

如果你需要企业微信群聊，用下一节的 WeCom 适配器，别用个人微信。

媒体加密

微信的媒体文件走 AES-128-ECB 加密的 CDN，Hermes 会自动处理加解密，你不需要管。前提是装了 cryptography 包：

pip install aiohttp cryptography

企业微信（WeCom）：扫码建机器人

企业微信的接入比个人微信稳定得多，走的是官方的 AI Bot WebSocket 网关，支持群聊，连接也更可靠。

扫码创建

hermes gateway setup

选 WeCom，用企业微信 App 扫码，Hermes 自动创建一个机器人应用并配好权限。如果想手动建，去企业微信管理后台，在「应用管理」里创建 AI Bot，拿到 Bot ID 和 Secret。

配置

WECOM_BOT_ID=你的Bot ID
WECOM_SECRET=你的Secret
WECOM_ALLOWED_USERS=user_id_1,user_id_2
WECOM_HOME_CHANNEL=chat_id

群组策略

企业微信的群组策略默认是 open（响应所有群），这点和个人微信不同：

WECOM_GROUP_POLICY=open       # 默认：所有群都响应
# WECOM_GROUP_POLICY=allowlist # 只响应白名单里的群
# WECOM_GROUP_POLICY=disabled  # 关闭群聊

还能做更细的「按群放行」：

platforms:
  wecom:
    enabled: true
    extra:
      bot_id: "your-bot-id"
      secret: "your-secret"
      group_policy: "allowlist"
      group_allow_from:
        - "group_id_1"
        - "group_id_2"
      groups:
        group_id_1:
          allow_from:           # 这个群里只允许这几个人用
            - "user_alice"
            - "user_bob"
        group_id_2:
          allow_from:
            - "user_charlie"
        "*":                    # 其他群的默认规则
          allow_from:
            - "user_admin"

Tip

企业微信的媒体文件是 AES-256-CBC 加密的，同样需要 cryptography 包。文件大小上限 20MB，超过会被拒收。

钉钉：Stream Mode + AI 卡片

钉钉用 Stream Mode（长连接 WebSocket），不需要公网。它有两个特色：AI 卡片和表情反馈。

创建应用

打开钉钉开发者后台，创建一个 H5 微应用。
在「凭证与基础信息」里拿到 Client ID（AppKey）和 Client Secret（AppSecret）。
给应用添加「机器人」能力，消息接收模式选 Stream Mode。

配置

DINGTALK_CLIENT_ID=你的AppKey
DINGTALK_CLIENT_SECRET=你的AppSecret
DINGTALK_ALLOWED_USERS=user-id-1,user-id-2

或者直接用向导扫码授权，连开发者后台都不用去：

hermes gateway setup

选 DingTalk，终端出二维码，钉钉 App 扫码后自动回填 Client ID 和 Secret。

AI 卡片

钉钉的 AI 卡片比纯文本消息展示更丰富，支持流式更新。需要在钉钉开发者后台创建卡片模板，拿到模板 ID：

platforms:
  dingtalk:
    enabled: true
    extra:
      card_template_id: "你的卡片模板ID"

开启后，所有回复都以卡片形式发送，文字会流式填充进卡片，体验很接近 ChatGPT 的逐字输出效果。

表情反馈

机器人收到消息时自动给原消息加个 🤔 表情，处理完换成 🥳。这个反馈在 DM 和群聊里都生效，用户一眼就能看到处理进度。

Note

钉钉单条消息上限 20000 字符，超出会被截断。群聊里需要 @mention 机器人才会响应，DM 则不需要。

飞书 / Lark：功能最全的平台

飞书（国内版）和 Lark（国际版）共用一套适配器，功能是八个平台里最全的：互动卡片、文档评论智能回复、会议邀请、Bot 间通信。当然配置项也最多。

两种连接模式

FEISHU_CONNECTION_MODE=websocket   # 推荐：WebSocket，不需要公网
# FEISHU_CONNECTION_MODE=webhook    # 备选：Webhook，需要公网可达

WebSocket 模式用官方 SDK 维护长连接，自动重连，本地部署首选。Webhook 模式适合你已经有公网服务器的场景，Hermes 会在 127.0.0.1:8765/feishu/webhook 起一个 HTTP 服务接收飞书推送。

创建应用

打开飞书开放平台（Lark 用 open.larksuite.com），创建应用。
复制 App ID 和 App Secret。
开启「机器人」能力。
配置权限，至少需要：

权限 Scope	用途
`im:message`	接收和读取消息
`im:message:send_as_bot`	以机器人身份发消息
`im:resource`	访问用户发的图片、文件、音频
`im:chat`	访问会话/群组元数据
`im:chat:readonly`	读取会话列表和成员

在「事件与回调」里订阅 im.message.receive_v1（接收消息事件）。
发布应用版本，权限才生效。

配置

FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=secret_xxx
FEISHU_DOMAIN=feishu              # feishu 国内版，lark 国际版
FEISHU_CONNECTION_MODE=websocket
FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy
FEISHU_HOME_CHANNEL=oc_xxx

互动卡片

飞书的互动卡片可以做命令审批——机器人要执行危险命令时，发一张带「允许一次 / 本次会话 / 始终允许 / 拒绝」按钮的卡片，用户点一下就完成授权。

要让卡片按钮可用，飞书后台要做三件事，缺一不可：

在「事件订阅」里订阅 card.action.trigger。
在「应用功能 > 机器人」里开启「互动卡片」开关。
Webhook 模式下还要配置「消息卡片请求 URL」，指向你的 webhook 地址。

Warning

三步漏了任何一步，卡片能发出去但点击按钮会报错 200340。这个错误只在用户交互时才出现，很容易漏配。

文档评论智能回复

飞书适配器有个独有能力：用户在飞书文档里 @机器人，机器人会读取文档内容和评论上下文，在评论里直接回复。权限管理是三级结构：

精确文档规则：针对某个具体文档。
通配规则：匹配一类文档。
顶层规则：整个工作区的默认策略。

规则存在 ~/.hermes/feishu_comment_rules.json，改完自动热加载，不用重启网关。

会议邀请

把飞书机器人拉进视频会议（就像邀请一个人），机器人收到邀请事件后会尝试自动加入。前提是订阅了 vc.bot.meeting_invited_v1 事件，且邀请人在网关的允许列表里。

选平台时的几个判断维度

讲完八个平台，我帮你梳理一下选型思路。

个人用：Telegram 最省事，WhatsApp 次之（但有封号风险）。如果只想自己跟机器人聊，Telegram 私信体验最好。

小团队协作：Discord 或 Slack。Discord 群组会话隔离做得细，适合多人各自独立任务；Slack 文件协作强，适合跟工作流绑得紧的场景。

国内企业：钉钉或飞书。钉钉的 AI 卡片和表情反馈体验好；飞书功能最全，尤其是文档评论和会议邀请，适合深度集成。

微信生态：个人微信只能私聊，群聊基本不可用；企业微信群聊稳定，推荐用 WeCom。

跨平台：Hermes 的 Gateway 天然支持多平台同时在线。你可以 Telegram 做个人入口、飞书做团队协作、钉钉做客户服务，会话互不干扰，记忆和技能共享。

Tip

不管选哪个平台，第一件事都是配 ALLOWED_USERS。别让机器人裸奔——任何人发消息都能触发完整工具链，等于把你的电脑权限开放给陌生人。