办公聊天软件接入 Hermes Agent 实录一企业微信 WebSocket 长连接 Dify 知识库问答v0.20.0 实测基于 Hermes Agentv0.20.0 Dify1.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 校验、加解密策略长连接自动接收消息最终选了它一次跑通。我们当时也对比过「自建应用回调」路线——多一套 URL 校验 AES 加解密换来的是更复杂的交互能力——知识库问答根本用不上那些复杂度长连接是这条路的正确选择。二、架构总览WebSocket 长连接wss://openws.work.weixin.qq.com调用 dify_ask 工具MCP 桥接HTTP POST /v1/chat-messages分类→检索→LLM 生成带引用原样转发回推企业微信客户端Hermes Gateway云服务器 systemd 托管Hermes Agent模型编排Dify 知识库应用多库路由一句话Hermes 管「连接与编排」Dify 管「知识库与回答」。gateway 负责消息进出知识库问答全部由 Dify 完成保证质量和可溯源。关键机制Hermes 调的是 Dify 的「已发布 API」整条链路里最容易忽略的一个前置条件Dify 应用必须「已发布」 有「API Key」Hermes 才能调用。完整调用链是这样的WebSocket 长连接调 MCP 工具 dify_askHTTP POST /v1/chat-messagesBearer API Key跑工作流/知识库检索/LLM 生成原样转发企业微信用户发消息Hermes Gateway 收消息Hermes Agent 判断问题类型Dify 应用 已发布版本返回 answer要点Hermes 调的是 Dify 的 Service API/v1/chat-messages认证用 API Key——这就是「应用即 API」发布 建 Key 两步应用就变成了一个可调用的接口API 背后跑的是「已发布版本」——发布前置条件分两类chat / completion 基础应用保存配置即视为可用建 Key 后直接调实测无需显式发布workflow / advanced-chat 应用有「草稿 / 发布」两态Service API 只认发布版——必须POST /apps/{id}/workflows/publish后才可调没发布调用会报Workflow not foundHermes 不知道 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——它只知道「这个问题匹配这个工具的描述 → 调用它 → 拿到文本 → 转发给用户」。所以完整认知链是Dify 应用发布 建 Key 把 Dify 应用变成「一个可调用的 HTTP 接口」应用即 APIMCP 桥接层包装 把这个 HTTP 接口包装成「Hermes 工具箱里的一个工具」Hermes 的决策 用户问题匹配工具描述就调不匹配就不调直接用自己的知识回答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 侧的实际调优手段不是训练是配置本文全部实测SOUL.md人设/规则加「知识库问答规则」→ 回答提速 4 倍见第七节加「原样转发保留引用」→ 回答带 [1] 引用标记工具描述dify_ask 描述写清「管什么业务」→ 路由准确写清「返回即最终答案」→ 不擅自改写技能库Hermes 会把新学会的能力沉淀成技能它曾自动创建pil-card-design下次同类任务直接调用噪音控制display.memory_notifications: off隐藏后台维护通知缺一不可Dify 应用再好Hermes 转发时把引用删了、回答改乱了、路由选错了企微端体验照样差反过来 Hermes 配得再好Dify 知识库不准答案内容也是错的。所以「企业微信 AI 助手」交付是系统工程内容质量靠 Dify 调优行为质量靠 Hermes 配置两侧都要做。本文第七节性能优化、第八节多应用路由都是 Hermes 侧调优的实例。三、前置企业微信智能机器人创建3 个关键点先明确形态企业微信机器人有两条路线本文用智能机器人Smart Robot——WebSocket 长连接、创建即拿凭据、无需公网回调。对比项智能机器人本文方案自建应用回调连接方式WebSocket 长连接URL 回调需要公网 HTTPS公网要求无需要公网地址 域名证书配置复杂度创建即拿 Bot ID SecretURL 校验 Token/AESKey 加解密适用场景知识库问答、轻量对话复杂交互表单、审批流入口企业微信客户端 → 工作台 → 智能机器人 → 创建机器人管理后台路径安全与管理 → 管理工具 → 智能机器人。三个决定成败的点必须选「API 模式创建」——普通模式拿不到 Bot ID只有 API 模式才会生成可对接的凭据连接方式选「使用长连接」——注意长连接模式的 Secret 和 URL 回调模式的 Token/EncodingAESKey 是两套东西不能混用Secret 只展示一次立刻复制保存——页面刷新就没了以后在后台刷新 Secret旧的立即失效服务端要同步更新另外可见范围务必包含你自己的账号否则发消息机器人收不到。四、接入步骤拿到 Bot ID 和 Secret 后服务端三步# 1. 写入环境变量~/.hermes/.envWECOM_BOT_IDaibPNX-xxxWECOM_SECRETqKyRalPR5BxxxWECOM_ALLOW_ALL_USERStrue# 开发期放开生产改白名单# 2. 启用 wecom 插件关键见坑 1hermes pluginsenablewecom-platform# 3. 重启 gatewayhermes gateway restart五、两个真实踩坑坑现象根因修复wecom 插件必须显式启用gateway 配置里平台 enabled但就是不连接插件默认禁用adapter 未注册到平台注册表连接循环静默跳过hermes plugins enable wecom-platform后重启平台日志在 agent.log 不在 journalctl查 systemd 日志以为「没连上」实际早已连接gateway 的平台连接日志写~/.hermes/logs/agent.logjournalctl 只有 systemd 输出排查先看~/.hermes/logs/agent.log连接成功有明确标记连接成功的日志长这样~/.hermes/logs/agent.loggateway.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: platformwecom msg物流怎么收费 agent.turn_context: conversation turn: modeldeepseek-v4-flash platformwecom agent.tool_executor: tool mcp__dify_bridge__dify_ask completed (5.24s, 181 chars) gateway.run: response ready: platformwecom time10.8s response65 chars [Wecom] Sending response (65 chars) to xxx回答内容来自 Dify 知识库多库路由自动分类产品问题→产品手册库、商品问题→商品库、技术问题→技术 FAQ 库正确命中「满 ¥99 包邮默认顺丰发货」。七、性能优化50 秒 → 12 秒7.1 优化前的问题接入后发现一个明显问题第一条消息等了 50 秒才回。查日志发现 Hermes 收到知识库问题后先调了网络搜索、又开了浏览器最后才调 dify_ask——白白多绕了几圈。我们当时的判断是「模型太慢」排查日志才发现根本不是——是它绕路了。指标优化前优化后总耗时50.2s12.3sAPI 调用次数7 次1 次多余工具搜索×2 浏览器×1无7.2 SOUL.md 配置方案在 Hermes 的身份指令文件~/.hermes/SOUL.md追加「知识库问答规则」## 知识库问答规则重要 - 用户询问产品/业务/知识库相关问题产品功能、价格、物流、技术问题等 必须直接调用 dify_ask 工具查询知识库获取答案。 - 禁止先使用浏览器或网络搜索查这类问题——dify_ask 是权威来源更快更准。 - 只有 dify_ask 返回失败或明确无结果时才考虑其他工具。7.3 优化前后对比改完重启 gateway50.2s → 12.3s4 倍提速回答质量不变。之后在新机器人干净会话上进一步实测到9.9s。八、多 Dify 应用单机器人 多应用实测通过接入跑通后自然会想一个企微机器人能不能根据问题类型调用不同的 Dify 应用知识库问答、旅游顾问、客服系统……实测结论——可以而且业务之间零污染。实现MCP 桥接层做「应用注册表 每应用一个工具」# /opt/mcp/dify_bridge/server.py节选mcp.tool()defdify_ask(query:str)-str:产品/商品/技术类问题X-Office 相关无记忆。mcp.tool()defdify_ask_travel(query:str,user_id:str)-str:旅游/出行类问题带多轮记忆同一 user_id 记住前文偏好。工具描述就是路由表每个工具写清「管什么业务、什么问题用它」→ Hermes 自动选对应用每个应用独立 API Keyconfig.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] 引用 → 回复会议纪要/任务管理/周报生成知识库风格零污染的三层保证Dify 应用间隔离每个应用独立 API Key 独立知识库/工作流平台保证无状态调用无记忆应用conversation_id恒为空Dify 每次只收到当前问题工具路由Hermes 按问题类型选应用不会把 A 应用的答案带进 B 应用记忆版设计要点如果业务需要多轮对话Dify chat 应用原生记忆conversation_id不需要在 DSL 里做任何特殊配置桥接层按用户维护 conversation_id 映射即可——不同用户之间记忆天然隔离业务决定记忆客服/顾问类要记忆FAQ 类不要一个提醒Hermes 后台会自动维护技能库自我改进偶尔会在回复里混入Self-improvement review: Skill xxx created这类通知——配置display.memory_notifications: offconfig.yaml即可隐藏不影响任何功能。九、多机器人场景现状实测更新⚠️ 本节基于 Hermes Agentv0.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 知识库是一条「无需公网、一次跑通、回答可溯源」的聊天软件接入路径。最大的两个坑——插件显式启用、日志文件看对位置——都在这篇文章里了照着做能省半天排查时间。十一、FAQQ1企业微信智能机器人和自建应用回调模式有什么区别A智能机器人Smart Robot走 WebSocket 长连接创建即拿凭据、无需公网回调——适合知识库问答等轻量场景自建应用回调模式需要公网 HTTPS URL 校验 AES 加解密适合需要复杂交互表单、审批的场景配置量多得多。Q2为什么 Dify workflow 应用不发布就调不通Aworkflow/advanced-chat 应用有「草稿/发布」两态Service API 只认已发布版本——没发布调用报Workflow not found。而 chat 基础应用保存配置即视为可用建 Key 后直接调。Q3WECOM_ALLOW_ALL_USERStrue生产环境怎么改A开发期用 true 放开生产改为用户白名单——把值改成逗号分隔的用户 ID 列表或按官方文档配置 allowed_users 数组避免无关人员调用机器人。Q4多机器人会话隔离什么时候能修复A这是 Hermes v0.20.0 wecom 插件的上游适配缺口adapter 构造消息来源时未打 profile 标记等官方后续版本修复修复标志 sessions 路由表里不同机器人的消息指向不同会话 ID。当前生产建议单机器人。Q5Dify 知识库和 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-apisDify 应用发布机制说明https://docs.dify.ai/zh-hans/api-reference/application-service-apis本系列其他篇系列零序言为什么做、怎么选、三篇地图系列二飞书权限矩阵 长连接事件订阅一次跑通系列三钉钉Stream 模式长连接一次跑通个人开发者也能接本文由 AI 协作完成接入、排障、优化均为实测过程数据取自真实运行日志。有问题欢迎评论区交流。