办公聊天软件接入 Hermes Agent 实录（一）：企业微信 WebSocket 长连接 + Dify 知识库问答

基于 Hermes Agent（v0.20.0）+ Dify（1.16.1）实测。文中所有命令、日志片段、性能数据均来自真实运行，未做美化。

目标读者：企业 IT 管理员、AI 应用交付工程师、想给企业接入 AI 助手的独立开发者。
环境版本：Hermes Agent v0.20.0 + Dify 1.16.1 + 企业微信智能机器人（API 模式/长连接）。
读完你将获得：① 零公网 WebSocket 接入完整方案 ② 50s→12s 的性能优化配置 ③ 单机器人调多个 Dify 应用的路由实现 ④ v0.20.0 多机器人会话隔离的已知限制与避坑。

一、为什么做这件事

接到一个很常见的需求：客户想把企业的 AI 能力（知识库问答、业务流程工作流）变成一个「在聊天软件里随叫随到的 AI 助手」——员工在企业微信里直接问，机器人秒回，回答还能追溯到来源。本文以知识库问答为例。

调研阶段确定接入方式时，企业微信的「智能机器人」（Smart Robot）方案优势明显：

• WebSocket 长连接：不需要公网 IP、不需要回调 URL——内网、云服务器都能跑
• 创建即拿凭据：后台创建机器人，选择 API 模式，直接拿到 Bot ID + Secret，配置步骤极少
• 零回调配置：无需配置 URL 校验、加解密策略，长连接自动接收消息

最终选了它，一次跑通。

二、架构总览

一句话：Hermes 管「连接与编排」，Dify 管「知识库与回答」。gateway 负责消息进出，知识库问答全部由 Dify 完成，保证质量和可溯源。

关键机制：Hermes 调的是 Dify 的「已发布 API」

整条链路里最容易忽略的一个前置条件：Dify 应用必须「已发布」+ 有「API Key」，Hermes 才能调用。完整调用链是这样的：

要点：

1. Hermes 调的是 Dify 的 Service API（/v1/chat-messages），认证用 API Key——这就是「应用即 API」：发布 + 建 Key 两步，应用就变成了一个可调用的接口
2. API 背后跑的是「已发布版本」——发布前置条件分两类：
   • chat / completion 基础应用：保存配置即视为可用，建 Key 后直接调（实测无需显式发布）
   • workflow / advanced-chat 应用：有「草稿 / 发布」两态，Service API 只认发布版——必须 POST /apps/{id}/workflows/publish 后才可调（没发布调用会报 Workflow not found）
3. Hermes 不知道 Dify 应用内部长什么样——它只看到「调工具 → 拿到文本 → 转发」。应用是 workflow 还是对话、绑了几个知识库、用什么模型，Hermes 完全不管。这就是解耦：Dify 管业务质量，Hermes 管接入通道

判断应用有没有发布：调用报错里出现 workflow not published / Workflow not found → 就是没发布，执行发布操作即可。

关键认知：Dify 应用对 Hermes 来说就是一个「工具」

理解了调用链，还要理解 Hermes 的视角——它把 Dify 应用当作工具箱里的一个普通工具来对待：

Hermes 的工具箱（每次决策时看到的清单）：
├─ dify_ask          ← 一个工具（背后是 Dify 知识库应用）
├─ dify_ask_travel   ← 一个工具（背后是 Dify 旅游顾问应用）
├─ write_file        ← 一个工具（写文件）
├─ terminal          ← 一个工具（跑命令）
└─ ...

对 Hermes 来说，每个工具就是「一个名字 + 一段描述 + 一段输入输出约定」。它不知道 dify_ask 背后是 Dify 在跑工作流、查知识库、调 LLM——它只知道：「这个问题匹配这个工具的描述 → 调用它 → 拿到文本 → 转发给用户」。

所以完整认知链是：

1. Dify 应用发布 + 建 Key = 把 Dify 应用变成「一个可调用的 HTTP 接口」（应用即 API）
2. MCP 桥接层包装 = 把这个 HTTP 接口包装成「Hermes 工具箱里的一个工具」
3. Hermes 的决策 = 用户问题匹配工具描述就调，不匹配就不调（直接用自己的知识回答）
4. Hermes 的转发 = 拿到工具返回的文本，原样发给用户

这个认知对实际交付的意义：

• Dify 应用做得再复杂（多库路由、复杂工作流），对 Hermes 来说只是「一个工具」——接入成本恒定。换一个更复杂的应用，Hermes 侧什么都不用改
• 加新应用 = 加一个工具 + 写清描述，Hermes 自动学会用它（这就是第八节「多 Dify 应用」方案的基础）
• 工具化是通用范式：以后接 CRM、ERP、任何自定义 API，只要包装成 MCP 工具，Hermes 一样用——不限于 Dify

这也是「Hermes 管接入通道，Dify 管业务质量」的真正含义——工具化让两边彻底解耦，各干各的。

回答质量是「两层」的：Dify 管内容，Hermes 管行为

想让企业微信端的回答令人满意，Dify 应用和 Hermes 两侧都要调优——但「调优」不是训练模型（那是模型厂商的事），而是配置：

层	谁负责	决定什么	调优手段
内容层	Dify 应用	回答「说什么」——知识库准不准、工作流逻辑、LLM prompt	知识库调优、工作流设计、prompt 优化（Dify 侧）
行为层	Hermes Agent	回答「怎么给」——工具选得对不对、转发原不原样、人设风格、噪音	SOUL.md 规则、工具描述、技能库、记忆（Hermes 侧）

Hermes 侧的实际调优手段（不是训练，是配置，本文全部实测）：

1. SOUL.md（人设/规则）：加「知识库问答规则」→ 回答提速 4 倍（见第七节）；加「原样转发保留引用」→ 回答带 [1] 引用标记
2. 工具描述：dify_ask 描述写清「管什么业务」→ 路由准确；写清「返回即最终答案」→ 不擅自改写
3. 技能库：Hermes 会把新学会的能力沉淀成技能（它曾自动创建 pil-card-design），下次同类任务直接调用
4. 噪音控制：display.memory_notifications: off 隐藏后台维护通知

缺一不可：Dify 应用再好，Hermes 转发时把引用删了、回答改乱了、路由选错了，企微端体验照样差；反过来 Hermes 配得再好，Dify 知识库不准，答案内容也是错的。

所以「企业微信 + AI 助手」交付是系统工程：内容质量靠 Dify 调优，行为质量靠 Hermes 配置，两侧都要做。本文第七节（性能优化）、第八节（多应用路由）都是 Hermes 侧调优的实例。

三、前置：企业微信智能机器人创建（3 个关键点）

先明确形态：企业微信机器人有两条路线，本文用智能机器人（Smart Robot）——WebSocket 长连接、创建即拿凭据、无需公网回调。

对比项	智能机器人（本文方案）	自建应用回调
连接方式	WebSocket 长连接	URL 回调（需要公网 HTTPS）
公网要求	无	需要公网地址 + 域名证书
配置复杂度	创建即拿 Bot ID + Secret	URL 校验 + Token/AESKey 加解密
适用场景	知识库问答、轻量对话	复杂交互（表单、审批流）

入口：企业微信客户端 → 工作台 → 智能机器人 → 创建机器人（管理后台路径：安全与管理 → 管理工具 → 智能机器人）。

三个决定成败的点：

1. 必须选「API 模式创建」——普通模式拿不到 Bot ID，只有 API 模式才会生成可对接的凭据
2. 连接方式选「使用长连接」——注意：长连接模式的 Secret 和 URL 回调模式的 Token/EncodingAESKey 是两套东西，不能混用
3. Secret 只展示一次，立刻复制保存——页面刷新就没了；以后在后台刷新 Secret，旧的立即失效，服务端要同步更新

另外可见范围务必包含你自己的账号，否则发消息机器人收不到。

四、接入步骤

拿到 Bot ID 和 Secret 后，服务端三步：

# 1. 写入环境变量（~/.hermes/.env）
WECOM_BOT_ID=aibPNX-xxx
WECOM_SECRET=qKyRalPR5Bxxx
WECOM_ALLOW_ALL_USERS=true   # 开发期放开；生产改白名单

# 2. 启用 wecom 插件（关键，见坑 1）
hermes plugins enable wecom-platform

# 3. 重启 gateway
hermes gateway restart

五、两个真实踩坑

坑	现象	根因	修复
wecom 插件必须显式启用	gateway 配置里平台 enabled，但就是不连接	插件默认禁用，adapter 未注册到平台注册表，连接循环静默跳过	hermes plugins enable wecom-platform 后重启
平台日志在 agent.log 不在 journalctl	查 systemd 日志以为「没连上」，实际早已连接	gateway 的平台连接日志写 ~/.hermes/logs/agent.log，journalctl 只有 systemd 输出	排查先看 ~/.hermes/logs/agent.log，连接成功有明确标记

连接成功的日志长这样（~/.hermes/logs/agent.log）：

gateway.run: Connecting to wecom...
[Wecom] Connected to wss://openws.work.weixin.qq.com
gateway.run: ✓ wecom connected
gateway.run: Gateway running with 2 platform(s)

六、验证链路（真实日志）

企微发「物流怎么收费？」后，消息完整走通：

[WeCom] Flushing text batch agent:main:wecom:dm:xxx
gateway.run: inbound message: platform=wecom msg='物流怎么收费？'
agent.turn_context: conversation turn: model=deepseek-v4-flash platform=wecom
agent.tool_executor: tool mcp__dify_bridge__dify_ask completed (5.24s, 181 chars)
gateway.run: response ready: platform=wecom time=10.8s response=65 chars
[Wecom] Sending response (65 chars) to xxx

回答内容来自 Dify 知识库（多库路由自动分类：产品问题→产品手册库、商品问题→商品库、技术问题→技术 FAQ 库），正确命中「满 ¥99 包邮，默认顺丰发货」。

七、性能优化：50 秒 → 12 秒

7.1 优化前的问题

接入后发现一个明显问题：第一条消息等了 50 秒才回。查日志发现 Hermes 收到知识库问题后，先调了网络搜索、又开了浏览器，最后才调 dify_ask——白白多绕了几圈。

指标	优化前	优化后
总耗时	50.2s	12.3s
API 调用次数	7 次	1 次
多余工具	搜索×2 + 浏览器×1	无

7.2 SOUL.md 配置

方案：在 Hermes 的身份指令文件（~/.hermes/SOUL.md）追加「知识库问答规则」：

## 知识库问答规则（重要）
- 用户询问产品/业务/知识库相关问题（产品功能、价格、物流、技术问题等），
  必须直接调用 dify_ask 工具查询知识库获取答案。
- 禁止先使用浏览器或网络搜索查这类问题——dify_ask 是权威来源，更快更准。
- 只有 dify_ask 返回失败或明确无结果时，才考虑其他工具。

7.3 优化前后对比

改完重启 gateway，50.2s → 12.3s，4 倍提速，回答质量不变。之后在新机器人（干净会话）上进一步实测到 9.9s。

八、多 Dify 应用：单机器人 + 多应用（实测通过）

接入跑通后，自然会想：一个企微机器人能不能根据问题类型调用不同的 Dify 应用（知识库问答、旅游顾问、客服系统……）？实测结论——可以，而且业务之间零污染。

实现：MCP 桥接层做「应用注册表 + 每应用一个工具」

# /opt/mcp/dify_bridge/server.py（节选）
@mcp.tool()
def dify_ask(query: str) -> str:
    """产品/商品/技术类问题（X-Office 相关），无记忆。"""

@mcp.tool()
def dify_ask_travel(query: str, user_id: str = "") -> str:
    """旅游/出行类问题，带多轮记忆（同一 user_id 记住前文偏好）。"""

• 工具描述就是路由表：每个工具写清「管什么业务、什么问题用它」→ Hermes 自动选对应用
• 每个应用独立 API Key（config.yaml 里各自配置）
• 记忆版应用（如旅游顾问）：Dify chat 应用原生支持——Service API 首次调用返回 conversation_id，后续带上即延续上下文；桥接层维护「用户 → conversation_id」映射

实测链路（企微真实验证）：

用户：我想去成都玩 3 天，预算 3000，一个人
→ tool dify_ask_travel completed (13.4s)
→ 回复：成都 4 天 3 晚行程 + 预算分配（旅游顾问风格）

用户：X-Office 有哪些功能？
→ tool dify_ask completed（知识库，带 [1] 引用）
→ 回复：会议纪要/任务管理/周报生成（知识库风格）

零污染的三层保证：

1. Dify 应用间隔离：每个应用独立 API Key + 独立知识库/工作流（平台保证）
2. 无状态调用：无记忆应用 conversation_id 恒为空，Dify 每次只收到当前问题
3. 工具路由：Hermes 按问题类型选应用，不会把 A 应用的答案带进 B 应用

记忆版设计要点（如果业务需要多轮对话）：

• Dify chat 应用原生记忆（conversation_id），不需要在 DSL 里做任何特殊配置
• 桥接层按用户维护 conversation_id 映射即可——不同用户之间记忆天然隔离
• 业务决定记忆：客服/顾问类要记忆，FAQ 类不要

一个提醒：Hermes 后台会自动维护技能库（自我改进），偶尔会在回复里混入 Self-improvement review: Skill 'xxx' created 这类通知——配置 display.memory_notifications: off（config.yaml）即可隐藏，不影响任何功能。

九、多机器人场景现状（实测更新）

⚠️ 本节基于 Hermes Agent v0.20.0 实测。多机器人会话隔离限制在后续版本可能修复，请以官方更新日志为准。

顺着「多应用」的思路，自然会想更进一步：能不能一个 gateway 挂多个企微机器人，各管各的业务？比如写作机器人、设计机器人、通用问答机器人各一个。实测结论——能连，但会话隔离尚未就绪。

已经支持的部分：

• 开启多 profile 多路复用（gateway.multiplex_profiles: true），每个机器人一个 profile（独立人设 SOUL + 独立记忆/技能）
• 每个 profile 的 .env 配各自的 WECOM_BOT_ID/WECOM_SECRET，三个机器人同时在线，各自响应消息
• 连接日志明确标注归属：✓ wecom connected (profile: writing)
• 人设隔离是生效的——写作机器人按写作人设回答，设计机器人按设计人设回答

尚不支持的部分（v0.20.0 已知限制）：

• 会话（上下文）没有按机器人隔离：同一用户给多个机器人发消息时，消息被路由到同一个会话——各机器人会「看到」彼此的对话历史，且同时发消息时后到的要排队等待
• 这是上游插件的适配缺口，根因是 wecom 适配器在构造消息来源时没有打上 profile 标记。后续可等官方修复，不推荐生产环境多机器人并行

当前可用形态：

• 单机器人 + 多 Dify 应用（第八节方案）：完全稳定，生产可用
• 多机器人（多个企微机器人分角色）：验证功能可行，但上下文会共享——适合演示，不适合正式交付

修复标志：升级后若 sessions 路由表里不同机器人的消息指向不同会话 ID，即代表会话隔离已生效，多机器人即可正式使用。

十、总结与适用边界

这套方案的适合场景：

• 企业内部知识库问答（产品手册、FAQ、制度文档）
• 员工在企微里随手问、要带引用溯源的回答
• 已有 Dify 应用、想把聊天软件作为前端入口

一句话总结：企业微信智能机器人 + Hermes Gateway + Dify 知识库，是一条「无需公网、一次跑通、回答可溯源」的聊天软件接入路径。最大的两个坑——插件显式启用、日志文件看对位置——都在这篇文章里了，照着做能省半天排查时间。

十一、FAQ

Q1：企业微信智能机器人和自建应用（回调模式）有什么区别？
A：智能机器人（Smart Robot）走 WebSocket 长连接，创建即拿凭据、无需公网回调——适合知识库问答等轻量场景；自建应用回调模式需要公网 HTTPS + URL 校验 + AES 加解密，适合需要复杂交互（表单、审批）的场景，配置量多得多。

Q2：为什么 Dify workflow 应用不发布就调不通？
A：workflow/advanced-chat 应用有「草稿/发布」两态，Service API 只认已发布版本——没发布调用报 Workflow not found。而 chat 基础应用保存配置即视为可用，建 Key 后直接调。

Q3：WECOM_ALLOW_ALL_USERS=true 生产环境怎么改？
A：开发期用 true 放开，生产改为用户白名单——把值改成逗号分隔的用户 ID 列表，或按官方文档配置 allowed_users 数组，避免无关人员调用机器人。

Q4：多机器人会话隔离什么时候能修复？
A：这是 Hermes v0.20.0 wecom 插件的上游适配缺口（adapter 构造消息来源时未打 profile 标记），等官方后续版本修复；修复标志 = sessions 路由表里不同机器人的消息指向不同会话 ID。当前生产建议单机器人。

Q5：Dify 知识库和 Hermes 自带能力怎么选？
A：要知识库检索（RAG）+ 引用溯源 + 可视化编排 → 用 Dify（本文方案）；只是简单工具调用/无需知识库 → Hermes 原生能力就够。两者可叠加：Hermes 管调度，Dify 管知识。

十二、参考资料

• Hermes Agent 官方文档：https://hermes-agent.nousresearch.com/docs
• 企业微信智能机器人开发文档：https://developer.work.weixin.qq.com/
• Dify Service API 文档：https://docs.dify.ai/zh-hans/api-reference/application-service-apis
• Dify 应用发布机制说明：https://docs.dify.ai/zh-hans/api-reference/application-service-apis

---

本系列其他篇：

• 系列（零）序言：为什么做、怎么选、三篇地图
• 系列（二）飞书：权限矩阵 + 长连接事件订阅一次跑通
• 系列（三）钉钉：Stream 模式长连接一次跑通

---

本文由 AI 协作完成：接入、排障、优化均为实测过程，数据取自真实运行日志。有问题欢迎评论区交流。