ARTICLE DETAIL

建站实战干货

来自一线的建站与推广经验沉淀，每一条都经过真实交付验证。

首页 / 资讯中心 / 正文

办公聊天软件接入 Hermes Agent 实录（三）：钉钉 Stream 模式长连接零公网跑通

2026/8/13 9:01:14 拓冰建站 浏览量
办公聊天软件接入 Hermes Agent 实录（三）：钉钉 Stream 模式长连接零公网跑通

办公聊天软件接入 Hermes Agent 实录（三）：钉钉 Stream 模式长连接零公网跑通

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

目标读者：企业 IT 管理员、独立开发者、AI 应用交付工程师。
环境版本：Hermes Agent v0.20.0 + Dify 1.16.1 + 钉钉企业内部应用（Stream 模式）。
前置条件：已有可运行的 Hermes Gateway + Dify 知识库应用（接入方法见系列（一）企业微信篇）。
读完你将获得：① 钉钉 Stream 模式零公网接入完整四步法 ② 懒安装后 pycache 缓存导致raw_process缺失的根因与修复 ③ 钉钉/飞书/企微三平台并存架构 ④ 20.5s 响应带引用回复的验证日志。

一、为什么做这件事

⚠️ 本文基于 Hermes Agentv0.20.0、Dify1.16.1、钉钉 Stream 模式 SDK 实测。钉钉开放平台的界面文案、Hermes 的配置项可能随版本调整，请以官方最新文档为准。

国内企业办公三巨头——飞书、企业微信、钉钉——前两个已经接进 Hermes 了（各自有独立文章），钉钉是最后一块拼图。三款都用同一套方案：聊天软件里问知识库/跑业务流程，机器人秒回带引用。

钉钉有个额外的价值：个人开发者也能接。不需要企业资质，免费创建团队就能走通全流程——这篇文章把「个人怎么接」讲透。

二、钉钉接入的两个认知（先看这个）

2.1 应用必须「挂」在某个组织下

钉钉的应用/机器人属于组织，创建那一刻就绑定，之后挪不走。个人开发者没有企业，就免费建一个「团队」（一个手机号最多建 10 个团队，免费，不需要认证）：

手机钉钉 → 通讯录 → 创建加入企业/组织/团队 → 创建团队 → 起名（如 My Hermes Bot）

然后回到开放平台（open.dingtalk.com）扫码登录，顶部切换到新组织，再创建应用——应用就属于新组织了，和原来的彻底隔离。

2.2 Stream Mode 长连接，零公网依赖

钉钉接入有两种消息接收模式，我们用的是Stream 模式（dingtalk-stream SDK 长连接）：

  • 不需要公网 IP、不需要回调 URL——和飞书/企微长连接同一套逻辑
  • 配置只需 App Key（Client ID）+ App Secret（Client Secret）两个凭证
  • 文本/图片/音频/视频/文件都能收，支持群 @ 门控

架构链路：

Stream Mode 长连接
dingtalk-stream SDK

调 MCP 工具 dify_ask

HTTP POST /v1/chat-messages

返回 answer 带引用

原样转发

回推 + 表情交互

钉钉客户端

Hermes Gateway

Hermes Agent

Dify 知识库应用

三、前置：创建组织 + 应用（人工步骤）

钉钉侧需要人工操作一次（参考官方指引，流程比飞书简单）：

3.1 建团队（组织壳）

手机钉钉 → 通讯录 → 创建团队（1 分钟，免费，一个手机号最多 10 个团队）。

3.2 切组织 + 建应用

  1. open.dingtalk.com 扫码登录 → 顶部「选择组织」→选刚建的新组织（关键！建错地方挪不走）
  2. 应用开发 → 企业内部应用 → 创建应用 → 填名称/描述/图标
  3. 左侧「添加应用能力 → 机器人」→ 开启开关
  4. 消息接收模式选 Stream 模式（零公网，推荐）

3.3 发布与可见范围

  1. 版本管理与发布 → 创建版本 →可用范围选你自己（关键！不选就搜不到）→ 保存并发布
  2. 凭证与基础信息 → 复制 Client ID + Client Secret

⚠️ 最容易漏的一步：必须走完「发布」流程——开发后台写好了不等于上线，不发布聊天框里搜不到机器人。发布后回到钉钉主界面直接搜应用名即可私聊。

四、Hermes 侧接入

# ~/.hermes/.env DINGTALK_CLIENT_ID=dingxxx DINGTALK_CLIENT_SECRET=xxx DINGTALK_ALLOWED_USERS=* # 白名单；* = 任何人（仅限开发测试！）
# 启用插件 + 重启hermes pluginsenabledingtalk-platform hermes gateway restart

连接成功的标志（agent.log）：

gateway.run: Connecting to dingtalk... [Dingtalk] Robot SDK initialized (media download) [Dingtalk] Connected via Stream Mode gateway.run: ✓ dingtalk connected

一个小细节：gateway 检测到 dingtalk-stream SDK 缺失时会自动安装（Lazy-installing dingtalk-stream==0.24.3），不需要手动 pip。

⚠️DINGTALK_ALLOWED_USERS=*仅限开发测试。生产环境必须填具体钉钉 User ID——从 gateway 日志的sender_id字段获取（收到第一条消息后复制）。否则任何知道机器人入口的人都能触发你的 Hermes Agent 调用 Dify，产生费用和安全风险。

4.1 健康状态对照（配置完后自检）

检查点健康表现异常表现 → 处理
SDK 依赖自动懒安装dingtalk-stream==0.24.3懒安装后 pycache 缓存 →raw_process缺失（见第五节）
连接日志✓ dingtalk connected+Connected via Stream Mode无此行 → Client ID/Secret 错
消息接收inbound message: platform=dingtalk连接正常但无此行 → User ID 不在白名单
Dify 调用mcp__dify_bridge__dify_ask completed无此行 → Dify 服务/MCP 桥接异常
回复response ready+ 钉钉收到带 [1] 引用回复超时 → Dify 应用未发布或 LLM 慢

五、一个致命坑：懒安装后的 pycache 缓存

5.1 现象

连接成功（Connected via Stream Mode），但发消息后 SDK 层报错：

ERROR dingtalk_stream.client: error processing message: '_IncomingHandler' object has no attribute 'raw_process'

5.2 根因

gateway 自动装 SDK 是「懒安装」——插件代码在 SDK 安装前就被编译缓存了（__pycache__/*.pyc）。编译时 SDK 还没装，适配器的消息处理类继承的是空基类（而非 SDK 的 ChatbotHandler），导致运行时缺raw_process方法。新进程加载的是旧缓存，继承链断裂。

5.3 修复

清掉插件缓存，强制重新编译，重启：

rm-rf~/.hermes/hermes-agent/plugins/platforms/dingtalk/__pycache__ hermes gateway restart

重启后Connected via Stream Mode+ 消息正常处理。判断线索：pyc 文件时间戳早于 SDK 安装时间 = 缓存的是旧版。

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

6.1 真实日志

钉钉发「x-office有哪些功能」后，消息完整走通：

[Dingtalk] _send_emotion: reply 🤔Thinking ← 钉钉表情：思考中 gateway.run: inbound message: platform=dingtalk user=周贵鲁 msg='x-office有哪些功能' agent.turn_context: conversation turn: platform=dingtalk agent.tool_executor: tool mcp__dify_bridge__dify_ask completed gateway.run: response ready: time=20.5s response=55 chars [Dingtalk] Sending response (55 chars) [Dingtalk] _send_emotion: recall 🤔Thinking + reply 🥳Done ← 表情：完成

钉钉收到回答：「根据知识库内容，X-Office 提供会议纪要、任务管理、周报生成三大核心能力 [1]。」——干净、带引用。

6.2 钉钉表情交互（加分项）

钉钉适配器原生带表情交互（🤔Thinking → 🥳Done），收到消息自动显示「思考中」表情、完成时回收换「完成」表情——比飞书/企微多了实时反馈，体验更好。

七、三平台并存

飞书、企业微信、钉钉可以同时在线（一个 Hermes 大脑、三个聊天软件入口）：

gateway.run: Gateway running with 3 platform(s)

会话按平台天然隔离（agent:main:dingtalk:.../agent:main:feishu:.../agent:main:wecom:...），互不干扰——员工用哪款办公软件，都能在聊天窗口里问知识库。

国内办公三巨头全覆盖：企业客户问「支持钉钉/飞书/企微吗」，答案都是「接」。

八、总结

钉钉接入一句话：免费建团队（组织壳）→ 建企业内部应用 + 机器人（Stream 模式）→ 发布 + 可见范围 → Hermes 配两个凭证，链路就通了。唯一坑是懒安装后的 pycache 缓存（清缓存 + 重启即修复）。

方案边界：Stream 模式虽零公网，但属于企业内部应用形态（个人免费「团队」也在此范畴，可正常使用）。如果未来需要回调公网 HTTPS 端点的高级场景（如接收钉钉卡片回调），则需改用 HTTP 模式并准备公网域名 + TLS 证书。三平台（钉钉/飞书/企微）可同时接入且互不干扰；同平台多机器人在 v0.20.0 有会话隔离限制（详见系列（一）企业微信篇第九节），生产环境建议单机器人。

这套方案适合：用钉钉办公、想把知识库变成「聊天窗口里随叫随到的 AI 助手」的企业；以及想用个人账号自建 AI 助手的开发者——零企业资质、零公网、免费跑通。

九、常见问题 FAQ

Q1：一定要建团队（组织）吗？个人账号不能直接建应用？
A：钉钉应用必须归属于某个组织。个人开发者没有企业资质时，免费建「团队」即可，一个手机号最多建 10 个团队，无需认证。

Q2：为什么连接成功但发消息报raw_process缺失？
A：懒安装后的 pycache 缓存问题。清掉plugins/platforms/dingtalk/__pycache__/后重启 gateway 即可。

Q3：DINGTALK_ALLOWED_USERS=*生产能用吗？
A：不能。生产必须填具体钉钉 User ID（从 gateway 日志的 sender_id 字段获取），否则任何知道机器人入口的人都能触发你的 Hermes Agent，产生费用和安全风险。

Q4：钉钉/飞书/企微能同时在线吗？
A：能。Hermes 单实例多平台（实测三平台在线），会话按平台天然隔离（agent:main:dingtalk/feishu/wecom），互不干扰。

十、参考资料

  • 钉钉服务端 Stream 模式官方文档：https://open.dingtalk.com/document/resourcedownload/Introduction-to-stream-mode
  • 钉钉机器人接收消息官方文档：https://open.dingtalk.com/document/dingstart/robot-receive-message
  • 钉钉 Stream 模式概述：https://opensource.dingtalk.com/developerpedia/docs/learn/stream/overview
  • Hermes Agent 钉钉接入文档：https://hermes-agent.nousresearch.com/docs/zh-Hans/user-guide/messaging/dingtalk
  • Dify Service API 文档：https://docs.dify.ai/zh-hans/api-reference/application-service-apis

本系列其他篇：

  • 系列（零）序言：为什么做、怎么选、三篇地图
  • 系列（一）企业微信：极简路线 + 多 Dify 应用
  • 系列（二）飞书：权限矩阵 + 长连接事件订阅一次跑通

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