Hermes Agent 接入飞书钉钉 WeCom：一个网关进程搞定三大平台，跨平台记忆无缝续聊

💡 摘要: 企业内部沟通分散在飞书、钉钉、WeCom 三大平台，AI 助手如果只接一个平台，覆盖面远远不够——用户在飞书问的问题，到钉钉继续追问时，助手完全不记得之前的对话。Hermes Agent 的多平台网关架构支持一个进程同时接入多个消息平台，国内三大平台开箱即用。本文从网关架构原理、三种连接模式对比、飞书/钉钉/WeCom 全流程接入、跨平台统一记忆机制、定时推送，到五个实战踩坑案例，完整演示从零到三平台联调的深度实践，附带平台功能对比表和 hermes gateway setup 交互式配置截图。

📅 技术栈版本: Hermes Agent v0.12+ | 飞书开放平台 API v2 | 钉钉开放平台 API v2 | WeCom API v3 | 更新时间: 2026-06

一、场景引入：三个平台，一个助手

我负责的内部工具团队有 40 多人，分布在三个业务线。

产品组用飞书做需求评审，运维组用钉钉接告警通知，管理层用 WeCom 审批流程。

之前我们尝试过给每个平台各部署一个 AI 助手，结果维护成本翻倍，更致命的是——用户在飞书问的问题，到钉钉继续追问时，助手完全不记得之前的对话。

直到我们用 Hermes Agent 的多平台网关统一接入，一个进程搞定三个平台，记忆和人格全部打通。

这才是企业级 AI 助手该有的样子。

1.1 多平台 vs 单平台的量化对比

很多团队觉得"先接一个平台试试"就够了，但实际运营数据告诉我们，单平台接入的覆盖率和用户体验都严重不足。

二、Hermes 多平台网关架构

Hermes 的多平台能力来自网关进程（Gateway）。网关负责接收各平台的消息事件，转发给核心 Agent 处理，再把响应推回对应平台。

核心设计原则：一个网关进程，同时接入所有平台。

不需要为每个平台单独部署服务，也不需要维护多套配置。

架构要点：

• 平台适配器：每个平台一个 Adapter，处理该平台特有的消息格式和 API 调用
• 会话存储：按聊天维度（per chat）维护会话状态，确保多轮对话连续
• 消息路由器：统一接收所有 Adapter 的消息，路由到 Agent 核心
• 统一记忆：无论消息来自哪个平台，共享同一份对话记忆和人格配置
• 定时调度器：每 60 秒 tick 一次，执行到期的 cron 任务
• 语音转文字：网关内置语音消息转文字能力，发送语音也能正常对话

2.1 三种连接模式对比

选择连接模式直接影响部署难度和是否需要公网 IP，是接入前必须做的关键决策。

实测结论：内网环境下选 WebSocket 长连接，无需公网 IP、无需内网穿透，是 95% 场景的推荐方案。飞书和 WeCom 均原生支持 WebSocket 模式。钉钉当前主要走 HTTP Webhook，但 v0.12+ 已实验性支持 Stream 模式。

2.2 国内三大平台功能支持对比

不同平台的消息能力差异较大，接入前了解功能边界可以避免后期踩坑。

飞书的功能支持最完整（8/8），钉钉缺失语音和输入提示，WeCom 缺失线程和表情反应。这会影响用户体验——比如在钉钉中发送语音消息，Hermes 无法转录，只能回复"请输入文字消息"。

三、飞书接入实战

3.1 创建飞书自定义机器人

登录飞书开放平台，进入「开发者后台」。

点击「创建应用」，选择「企业自建应用」，填写应用名称和描述。

上图展示了 hermes gateway setup 交互式向导的启动界面，通过方向键选择要配置的平台。

创建完成后，进入应用详情页，记录下 App ID 和 App Secret。

3.2 配置应用权限

在「权限管理」页面，开通以下权限：

关键提醒：飞书权限修改后，必须点击「创建版本」并发布，否则权限不会生效。这一点文档写得比较隐蔽，我第一次踩坑排查了两个小时。

3.3 配置事件订阅

在「事件与回调」页面：

1. 订阅方式选择**「长连接」**（内网友好模式，无需公网 IP）
2. 添加事件：im.message.receive_v1（接收消息事件）

Why 选长连接而非 Webhook：长连接模式下，Hermes 网关主动连接飞书服务器，无需暴露公网端口，适合内网部署。如果选 Webhook 模式，需要配置 https://your-gateway-host:8080/webhook/feishu，且要求服务器有公网 IP。

3.4 获取凭证并配置 Hermes

Hermes 网关需要飞书的 App ID 和 App Secret 来调用开放平台 API，同时需要 Verification Token 来验证回调请求的合法性。

# config/gateway.yaml - 飞书平台配置
gateways:
  feishu:
    enabled: true
    app_id: "cli_a5xxxxxxxxxxxxx"
    app_secret: "${FEISHU_APP_SECRET}"    # 推荐使用环境变量
    verification_token: "${FEISHU_VERIFICATION_TOKEN}"
    encrypt_key: "${FEISHU_ENCRYPT_KEY}"
    webhook_path: "/webhook/feishu"
    connection_mode: "websocket"  # 推荐：无需公网 IP

也可以用交互式向导一键配置：

# 交互式配置飞书（推荐新手）
hermes gateway setup
# 依次选择: feishu → 输入 App ID → 输入 App Secret → 
# 选择 websocket 模式 → 确认安装服务

3.5 验证连通

启动网关后需要确认飞书消息能正常到达 Hermes，这是整个接入流程的验证节点。

# 启动 Hermes 网关
hermes gateway start --config config/gateway.yaml

# 查看网关状态，确认飞书适配器已加载
hermes gateway status

预期输出：

Gateway Status: RUNNING
Adapters:
  - feishu: CONNECTED (app_id: cli_a5xxxxxxxxxxxxx, mode: websocket)

在飞书中找到刚创建的机器人，发送一条消息，观察网关日志是否收到事件。

四、钉钉接入实战

4.1 创建钉钉企业内部应用

登录钉钉开放平台，进入「应用开发」。

选择「企业内部开发」，点击「创建应用」，填写应用名称和描述。

创建完成后，进入应用详情页，记录下 Client ID 和 Client Secret。

4.2 添加机器人能力

钉钉应用默认不具备消息收发能力，必须手动添加"机器人"能力才能接收用户消息。

1. 进入刚创建的应用，在「应用能力」区域找到「机器人」
2. 点击「+ 添加」，为应用开通机器人能力
3. 设置机器人名称和头像

4.3 配置应用权限

在「权限管理」页面，申请以下权限：

4.4 配置消息接收

在「消息接收」页面，设置回调地址：

https://your-gateway-host:8080/webhook/dingtalk

同时需要在「安全设置」中配置 IP 白名单，添加 Hermes 网关服务器的公网 IP。

订阅事件：

• chatMessage：接收单聊消息

4.5 获取凭证并配置 Hermes

钉钉使用 Client ID / Client Secret 认证体系，与飞书的 App ID / App Secret 不同，Hermes 网关为每个平台提供了独立的配置段。

# config/gateway.yaml - 钉钉平台配置（追加到 gateways 下）
dingtalk:
  enabled: true
  client_id: "dingxxxxxxxxxxxxxxxx"
  client_secret: "${DINGTALK_CLIENT_SECRET}"
  webhook_path: "/webhook/dingtalk"
  # 钉钉回调签名验证 Token
  sign_token: "${DINGTALK_SIGN_TOKEN}"
  # AES 加解密密钥
  aes_key: "${DINGTALK_AES_KEY}"

4.6 验证连通

钉钉的回调验证比飞书多一步签名校验，需要确认签名逻辑正确。

# 重启网关加载新配置
hermes gateway restart --config config/gateway.yaml

# 检查钉钉适配器状态
hermes gateway status

预期输出：

Gateway Status: RUNNING
Adapters:
  - feishu: CONNECTED (mode: websocket)
  - dingtalk: CONNECTED (client_id: dingxxxxxxxxxxxxxxxx)

在钉钉中搜索机器人，发送一条测试消息。

五、WeCom 接入实战

5.1 创建 WeCom 自建应用

登录 WeCom 管理后台，进入「应用管理」。

在「自建应用」区域，点击「创建应用」，填写应用名称、Logo 和可见范围。

创建完成后，记录下 Corp ID（在企业信息页面）和应用的 Secret（在应用详情页面）。

5.2 配置接收消息

在应用详情页的「接收消息」区域，设置 API 接收的 URL：

https://your-gateway-host:8080/webhook/wecom

同时记录下系统生成的 Token 和 EncodingAESKey。

5.3 配置可信域名

在「网页授权及 JS-SDK」区域，添加 Hermes 网关的域名到可信域名列表。

5.4 获取凭证并配置 Hermes

WeCom使用 Corp ID + Secret 的认证方式，消息加解密采用 AES 算法，EncodingAESKey 配置错误是最常见的接入失败原因。

# config/gateway.yaml - WeCom平台配置（追加到 gateways 下）
wecom:
  enabled: true
  corp_id: "wwxxxxxxxxxxxxxxxx"
  agent_id: 1000002
  secret: "${WECOM_SECRET}"
  token: "${WECOM_TOKEN}"
  encoding_aes_key: "${WECOM_ENCODING_AES_KEY}"
  webhook_path: "/webhook/wecom"
  # WeCom也支持 WebSocket 长连接模式（v0.12+）
  connection_mode: "websocket"

5.5 验证连通

WeCom的验证流程会先发送一个 GET 请求验证 URL 有效性，通过后才会推送消息事件。

# 重启网关
hermes gateway restart --config config/gateway.yaml

# 检查全部适配器状态
hermes gateway status

预期输出：

Gateway Status: RUNNING
Adapters:
  - feishu: CONNECTED (mode: websocket)
  - dingtalk: CONNECTED
  - wecom: CONNECTED (corp_id: wwxxxxxxxxxxxxxxxx, agent_id: 1000002, mode: websocket)

在WeCom中找到应用，发送一条测试消息。

上图展示了三平台全部连通后 hermes gateway status 的输出，三个适配器均显示 CONNECTED，网关处于 RUNNING 状态。

六、跨平台统一记忆演示

这是 Hermes 多平台接入最核心的价值：无论用户从哪个平台发消息，Agent 都能记住之前的对话上下文。

6.1 实际操作流程

我在飞书私聊机器人：

用户（飞书）：帮我查一下订单 ORD-20260614-0032 的物流状态
Hermes：订单 ORD-20260614-0032 当前状态：已发货，预计 6 月 15 日送达。
        承运商：顺丰速运，运单号：SF1234567890

10 分钟后，我在钉钉继续追问：

用户（钉钉）：刚才那个订单能加急吗？
Hermes：您说的是订单 ORD-20260614-0032（顺丰速运 SF1234567890）对吗？
        该订单已在运输途中，无法修改配送方式。
        如需加急，建议联系顺丰客服 95338 尝试升级服务。

Hermes 自动关联了飞书中的对话上下文，在钉钉中无缝续聊。

6.2 记忆关联机制

关键点：

• 用户身份映射：Hermes 通过用户 ID 映射表关联不同平台的同一用户（如飞书 UID ou_xxx ↔ 钉钉 UID user123）
• 上下文窗口：默认保留最近 20 轮对话，可通过 memory.max_turns 配置
• 跨平台续聊：在飞书开始的对话，在钉钉也能继续
• 记忆持久化：底层使用 SQLite FTS5 全文搜索 + LLM 摘要，存储在 MEMORY.md 和 USER.md 中

6.3 跨平台记忆的工程细节

跨平台记忆不是"把所有聊天记录塞进 prompt"，而是有精确的检索和压缩机制。

七、定时任务推送

除了被动回复消息，Hermes 还支持主动推送定时任务。

典型场景：每天早上 9 点推送运维日报到飞书群。

7.1 配置定时任务

定时推送是运维场景的刚需，Hermes 内置了 cron 表达式支持，无需额外部署定时任务框架。

# config/schedules.yaml - 定时任务配置
schedules:
  - name: "daily-ops-report"
    cron: "0 9 * * 1-5"          # 工作日每天 9:00
    platform: "feishu"            # 推送到飞书
    chat_id: "oc_xxxxxxxxxxxxx"   # 飞书群聊 ID
    prompt: |
      生成今日运维日报，包含以下内容：
      1. 昨日告警统计（按严重级别分类）
      2. 当前系统健康度评分
      3. 待处理工单列表
      4. 今日预计变更事项

  - name: "weekly-security-scan"
    cron: "0 10 * * 1"            # 每周一 10:00
    platform: "dingtalk"           # 推送到钉钉
    chat_id: "cidxxxxxxxxxxxxx"    # 钉钉群聊 ID
    prompt: |
      执行周度安全扫描总结：
      1. 本周新增安全风险告警
      2. 未修复的高危安全风险列表
      3. 下周安全加固建议

7.2 启动定时任务

# 加载定时任务配置
hermes schedule load --config config/schedules.yaml

# 查看已注册的定时任务
hermes schedule list

预期输出：

Schedules:
  - daily-ops-report: 0 9 * * 1-5 → feishu:oc_xxxxxxxxxxxxx [ACTIVE]
  - weekly-security-scan: 0 10 * * 1 → dingtalk:cidxxxxxxxxxxxxx [ACTIVE]

到了每天早上 9 点，飞书群就会自动收到 AI 生成的运维日报。

调度原理：网关内置的 Cron Scheduler 每 60 秒 tick 一次，检查是否有到期任务。到期后触发 Agent 生成内容，再通过对应平台的适配器推送到指定聊天。

八、踩坑指南

三个平台接入过程中，我踩过的坑都在这里，帮你提前避开。

坑 1：飞书权限变更后不生效

现象：网关日志显示收到消息事件，但调用飞书 API 发送回复时返回 403。

原因：创建应用后只添加了基础权限，没有开通「获取与发送单聊消息」权限。飞书的权限体系是细粒度的，每个 API 调用都需要对应权限。权限变更后没有发布新版本，修改不会生效。

排查步骤：

# 查看网关错误日志
hermes gateway logs --level error --last 10m

典型错误日志：

[ERROR] feishu: Failed to send message, status=403, 
  body={"code":99991668,"msg":"permission denied: im:message"}

解决方案：

1. 回到飞书开放平台，进入应用「权限管理」
2. 搜索 im:message，开通「获取与发送单聊消息」权限
3. 如果是群聊场景，还需要开通 im:message:send_as_bot
4. 权限变更后必须点击「创建版本」并发布——这是飞书的隐性要求

实操建议：把飞书权限配置作为 code review 的检查项，确保每次权限变更都同步发布新版本。

坑 2：钉钉回调地址配置错误

现象：钉钉开放平台配置回调 URL 时，验证始终失败，提示「URL 验证不通过」。

原因：钉钉回调验证会发送一个带签名的 GET 请求，Hermes 网关需要正确解析签名并返回解密后的 challenge 值。如果网关服务器的 IP 不在钉钉的白名单中，请求会被直接拦截。

排查步骤：

# 检查网关是否收到钉钉的验证请求
hermes gateway logs --filter "dingtalk" --last 5m

# 检查服务器公网 IP
curl -s ifconfig.me

解决方案：

1. 在钉钉开放平台「安全设置」中，添加网关服务器的公网 IP 到白名单
2. 确认回调 URL 使用 HTTPS 协议（钉钉要求生产环境必须 HTTPS）
3. 检查签名验证逻辑：钉钉使用 sign = HmacSHA256(timestamp + "\n" + secret) 计算签名
4. 如果使用 Nginx 反向代理，确保 X-Real-IP 和 X-Forwarded-For 头正确传递

关键提醒：钉钉的 IP 白名单是应用级别的，不是企业级别的。每个应用需要单独配置。

坑 3：WeCom消息加解密失败

现象：网关收到WeCom的消息回调，但解密时报错 PaddingException 或返回乱码。

原因：WeCom使用 AES-CBC-256 加解密，EncodingAESKey 是 43 位字符串，需要补位到 44 位后 Base64 解码得到 32 字节的 AES 密钥。如果配置文件中多了一个空格或少了一个字符，解密就会失败。

排查步骤：

# 测试加解密是否正常
hermes gateway test wecom --decrypt

# 检查配置中的 EncodingAESKey 长度
echo -n "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" | wc -c
# 预期输出：43

解决方案：

1. 仔细核对 EncodingAESKey，确保是完整的 43 位字符，没有多余空格或换行
2. 检查 Token 是否与企业管理后台中配置的一致
3. 确认 Corp ID 和 Agent ID 没有混淆（Corp ID 以 ww 开头）
4. 如果使用配置中心（如 Nacos），注意 YAML 解析时是否对特殊字符做了转义

关键提醒：EncodingAESKey 中可能包含 +、/、= 等 Base64 字符，在 YAML 中建议用引号包裹，避免解析异常。

坑 4：WebSocket 长连接频繁断开重连

现象：飞书和WeCom的 WebSocket 连接每隔几分钟断开重连，日志中反复出现 Connection closed, reconnecting...。

原因：WebSocket 长连接在以下场景会断开——服务器网络抖动、代理服务器超时、飞书/企微服务端维护。Hermes 网关有自动重连机制，但频繁重连会导致消息延迟。

排查步骤：

# 查看重连频率
hermes gateway logs --filter "reconnect" --last 1h | wc -l

# 检查网络稳定性
ping -c 10 open.feishu.cn

解决方案：

1. 如果通过 Nginx 反向代理，增加 WebSocket 超时时间：

# Nginx 配置——增加 WebSocket 超时
location /webhook/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;  # 默认 60s，改为 1 小时
    proxy_send_timeout 3600s;
}

2. 配置 Hermes 网关的心跳间隔（默认 30 秒）：

# config/gateway.yaml
gateway:
  websocket:
    ping_interval: 30      # 心跳间隔（秒）
    reconnect_delay: 5     # 断线后重连延迟（秒）
    max_reconnect_delay: 60  # 最大重连延迟（指数退避上限）

3. 如果是 Docker 部署，确保容器的 --network 模式为 host 或正确配置了端口映射

实操建议：生产环境建议添加 Prometheus 监控网关的重连次数，超过 10 次/小时则告警。

坑 5：跨平台记忆关联失败——用户身份未打通

现象：用户在飞书和钉钉用同一邮箱注册，但 Hermes 没有自动关联两个平台的身份，导致跨平台追问时"失忆"。

原因：Hermes 默认按平台用户 ID 建立会话，不会自动跨平台关联。需要手动配置用户 ID 映射，或通过邮箱/手机号自动匹配。

解决方案：

# config/gateway.yaml - 配置用户身份映射
identity:
  # 自动匹配模式：通过邮箱关联
  auto_match: true
  match_field: "email"   # 可选: email / phone / name

  # 手动映射模式：精确指定
  user_map:
    - feishu_id: "ou_xxxxxxxxxxxxxxxx"
      dingtalk_id: "user123"
      wecom_id: "WangXiaoMing"
    - feishu_id: "ou_yyyyyyyyyyyyyyyy"
      dingtalk_id: "user456"
      wecom_id: "LiHua"

实操建议：团队规模小时用手动映射，规模大时用 auto_match: true + 邮箱匹配。邮箱匹配的前提是飞书和钉钉都开放了邮箱读取权限。

九、完整网关配置参考

将三个平台的配置汇总在一起，方便整体审查和部署。实际使用时把占位符替换为真实凭证即可。

# config/gateway.yaml - 完整多平台网关配置
server:
  host: "0.0.0.0"
  port: 8080

agent:
  model: "deepseek-v4"
  memory:
    enabled: true
    max_turns: 20           # 保留最近 20 轮对话
    cross_platform: true    # 开启跨平台记忆

# 跨平台用户身份映射
identity:
  auto_match: true
  match_field: "email"

gateways:
  feishu:
    enabled: true
    app_id: "cli_a5xxxxxxxxxxxxx"
    app_secret: "${FEISHU_APP_SECRET}"
    verification_token: "${FEISHU_VERIFICATION_TOKEN}"
    encrypt_key: "${FEISHU_ENCRYPT_KEY}"
    webhook_path: "/webhook/feishu"
    connection_mode: "websocket"

  dingtalk:
    enabled: true
    client_id: "dingxxxxxxxxxxxxxxxx"
    client_secret: "${DINGTALK_CLIENT_SECRET}"
    webhook_path: "/webhook/dingtalk"
    sign_token: "${DINGTALK_SIGN_TOKEN}"
    aes_key: "${DINGTALK_AES_KEY}"

  wecom:
    enabled: true
    corp_id: "wwxxxxxxxxxxxxxxxx"
    agent_id: 1000002
    secret: "${WECOM_SECRET}"
    token: "${WECOM_TOKEN}"
    encoding_aes_key: "${WECOM_ENCODING_AES_KEY}"
    webhook_path: "/webhook/wecom"
    connection_mode: "websocket"

# WebSocket 长连接优化
websocket:
  ping_interval: 30
  reconnect_delay: 5
  max_reconnect_delay: 60

# 定时任务
schedules: [ ]

敏感凭证使用环境变量引用（${...}），避免明文写入配置文件，这是生产环境的基本安全要求。

# 通过环境变量注入敏感凭证
export FEISHU_APP_SECRET="your_feishu_app_secret"
export FEISHU_VERIFICATION_TOKEN="your_feishu_verification_token"
export FEISHU_ENCRYPT_KEY="your_feishu_encrypt_key"
export DINGTALK_CLIENT_SECRET="your_dingtalk_client_secret"
export DINGTALK_SIGN_TOKEN="your_dingtalk_sign_token"
export DINGTALK_AES_KEY="your_dingtalk_aes_key"
export WECOM_SECRET="your_wecom_secret"
export WECOM_TOKEN="your_wecom_token"
export WECOM_ENCODING_AES_KEY="your_wecom_encoding_aes_key"

# 启动网关
hermes gateway start --config config/gateway.yaml

十、聊天内常用命令速查

接入成功后，在任意平台对话中输入以下斜杠命令：

实用技巧：/new 命令在跨平台场景中特别有用——当你在飞书和钉钉的对话意外串上下文时，发一条 /new 可以重新开始。

十一、总结与适用边界

核心价值

Hermes 多平台网关解决了企业 AI 助手接入的三个核心问题：

适用场景

• 企业内部 AI 助手，需要同时覆盖飞书、钉钉、WeCom
• 运维告警机器人，需要跨平台推送和交互
• 知识库问答，需要在不同渠道保持一致的回答质量
• 定时报告推送，需要主动向群聊推送 AI 生成内容

不适用场景

• 纯外部客户服务（需要额外考虑数据隔离和合规）
• 超大规模并发（单网关进程建议并发不超过 1000 QPS，超出需水平扩展）
• 需要平台原生 UI 能力（如飞书卡片消息的复杂交互）
• 严格的审计日志需求（网关日志默认不持久化，需接入 CLS/ELK）

版本信息

📜 真实性声明

所有配置和命令基于 Hermes Agent v0.12.0 官方文档和本地测试环境验证