Skip to main content

DingTalk

本指南将指导您如何将 Hermes Agent 集成为钉钉（DingTalk）聊天机器人，实现与团队的实时交互。

1. 创建钉钉机器人​

步骤 1：进入钉钉群聊​

  • 打开钉钉应用
  • 进入您希望添加机器人的群组
  • 点击右上角的「...」菜单

步骤 2：添加机器人​

  • 选择「群机器人」
  • 点击「添加机器人」
  • 选择「自定义」类型

步骤 3：配置机器人​

  • 输入机器人名称（例如：Hermes Agent）
  • 选择「安全设置」
  • 勾选「加签」并复制生成的密钥（用于验证请求）

⚠️ 请妥善保管密钥，不要泄露给他人。

2. 配置 Hermes Agent​

安装依赖​

pip install hermes-agent dingtalk-sdk

创建配置文件 config.yaml​

dingtalk:
  webhook_url: "https://oapi.dingtalk.com/robot/send?access_token=your_access_token_here"
  secret: "your-secret-key-here"
  
hermes:
  model: "gpt-4"
  max_tokens: 2048
  temperature: 0.7

将示例中的 your_access_token_here 替换为您的钉钉机器人 access_token

启动机器人服务​

# bot.py
from hermes_agent import HermesAgent
from dingtalk_sdk import DingTalkBot

# 初始化组件
hermes = HermesAgent(config_path="config.yaml")
dingtalk_bot = DingTalkBot(config_path="config.yaml")

# 处理消息回调
def handle_message(message):
    response = hermes.generate_response(message)
    dingtalk_bot.send_text(message=response, receiver="all")

# 启动钉钉监听
dingtalk_bot.start_webhook_server(port=8080, callback=handle_message)

3. 部署到生产环境​

使用 Docker 部署​

# Dockerfile
FROM python:3.9-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

CMD ["python", "bot.py"]
# docker-compose.yml
version: '3.8'
services:
  hermes-dingtalk-bot:
    build: .
    ports:
      - "8080:8080"
    environment:
      - DINGTALK_WEBHOOK_URL=https://oapi.dingtalk.com/robot/send?access_token=your_access_token_here
      - DINGTALK_SECRET=your-secret-key-here
    restart: unless-stopped

4. 测试与验证​

发送测试消息​

在钉钉群中发送：

@Hermes Agent 你好，请帮我总结一下今天的会议要点

查看日志输出​

确认以下内容正常显示：

  • 接收到消息
  • 调用模型生成响应
  • 成功发送回复

5. 高级功能配置​

消息过滤规则​

filter_rules:
  - keyword: "紧急"
    priority: high
    action: "notify_admin"
  - keyword: "@Hermes Agent"
    enabled: true

多轮对话管理​

# 在 bot.py 中添加会话管理
from collections import defaultdict

user_sessions = defaultdict(list)

def handle_message(message, sender_id):
    # 保持上下文
    user_sessions[sender_id].append(message)
    
    # 生成带上下文的响应
    context = "\n".join(user_sessions[sender_id][-3:])
    full_prompt = f"根据之前的对话：{context}\n\n新问题：{message}"
    
    response = hermes.generate_response(full_prompt)
    dingtalk_bot.send_text(message=response, receiver=sender_id)

6. 安全注意事项​

  • ✅ 使用 HTTPS 端点接收钉钉回调
  • ✅ 定期轮换密钥
  • ✅ 限制机器人权限范围
  • ✅ 监控异常请求行为

7. 故障排除​

问题解决方案
无法接收消息检查 webhook URL 和密钥是否正确
响应延迟优化模型参数或升级服务器配置
消息丢失启用消息确认机制，检查网络连接

通过以上步骤，您已成功将 Hermes Agent 集成至钉钉平台，实现智能对话能力。如需更多功能扩展，可参考 Hermes Agent 官方文档。"

钉钉设置

Hermes Agent 与钉钉（DingTalk）集成，作为聊天机器人，让您通过私聊或群组聊天与您的 AI 助手进行交流。该机器人通过钉钉的流模式（Stream Mode）连接——一种长期保持的 WebSocket 连接，无需公网 URL 或 Webhook 服务器——并使用 Markdown 格式的消息，通过钉钉的会话 Webhook API 进行回复。

在开始设置前，这里是最常被问到的问题：一旦 Hermes 被部署到您的钉钉工作区后，它将如何表现？

Hermes 的行为表现​

场景表现
私聊（1:1 聊天）Hermes 对每条消息都会响应。无需提及 @mention。每个私聊拥有独立的会话。
群组聊天只有当您 @mention 时，Hermes 才会回应。未被提及的消息，Hermes 将忽略。
多人共享的群组默认情况下，Hermes 在群组内为每位用户保留独立的会话历史。两人在同一群组中对话时，不会共享同一段聊天记录，除非您明确关闭此功能。

钉钉中的会话模型​

默认设置下：

  • 每个私聊拥有独立会话
  • 群组中每位用户拥有独立的会话

这由 config.yaml 控制：

group_sessions_per_user: true

仅当您明确希望整个群组共享一个统一对话时，才将其设为 false：

group_sessions_per_user: false

本指南将引导您完成从创建钉钉机器人到发送第一条消息的完整设置流程。

前提条件​

安装所需的 Python 包：

pip install dingtalk-stream httpx
  • dingtalk-stream — 钉钉官方提供的 Stream Mode SDK（基于 WebSocket 的实时通信）
  • httpx — 用于通过会话 Webhook 发送回复的异步 HTTP 客户端

步骤 1：创建钉钉应用​

  1. 访问 钉钉开发者控制台。
  2. 使用您的钉钉管理员账号登录。
  3. 点击 应用开发 → 自建应用 → 通过 H5 微应用创建（或根据控制台版本选择 机器人）。
  4. 填写以下信息：
    • 应用名称：例如 Hermes Agent
    • 描述：可选
  5. 创建完成后，进入 凭证与基本信息 页面，获取您的 Client ID（AppKey）和 Client Secret（AppSecret）。请复制保存这两项信息。
凭证仅显示一次

Client Secret 仅在创建应用时显示一次。若丢失，需重新生成。切勿公开分享这些凭证，也禁止提交至 Git。

步骤 2：启用机器人功能​

  1. 在应用设置页面，点击 添加能力 → 机器人。
  2. 启用机器人功能。
  3. 在 消息接收模式 中，选择 流模式（推荐——无需公网地址）。
tip

流模式是推荐配置。它通过从您的设备发起的长连接 WebSocket 实现，因此无需公网 IP、域名或 Webhook 端点。即使在 NAT、防火墙后或本地机器上也能正常运行。

步骤 3：获取您的钉钉用户 ID​

Hermes Agent 使用您的钉钉用户 ID 来控制谁可以与机器人互动。钉钉用户 ID 是由组织管理员设定的字母数字字符串。

要查找您的用户 ID：

  1. 请联系您的钉钉组织管理员——用户 ID 在钉钉管理后台的 通讯录 → 成员管理 中配置。
  2. 或者，机器人会在日志中记录每条消息的 sender_id。启动网关后，向机器人发送一条消息，然后查看日志以确认您的用户 ID。

步骤 4：配置 Hermes Agent​

方式 A：交互式设置（推荐）​

运行引导式设置命令：

hermes gateway setup

提示时选择 钉钉，然后粘贴您的 Client ID、Client Secret 和允许的用户 ID。

方式 B：手动配置​

将以下内容添加到您的 ~/.hermes/.env 文件中：

# Required
DINGTALK_CLIENT_ID=your-app-key
DINGTALK_CLIENT_SECRET=your-app-secret

# Security: restrict who can interact with the bot
DINGTALK_ALLOWED_USERS=user-id-1

# Multiple allowed users (comma-separated)
# DINGTALK_ALLOWED_USERS=user-id-1,user-id-2

可选的行为设置（在 ~/.hermes/config.yaml 中）：

group_sessions_per_user: true
  • group_sessions_per_user: true 可确保在共享群组聊天中，每位参与者的上下文相互隔离

启动网关​

配置完成后，启动钉钉网关：

hermes gateway

机器人应在几秒内连接至钉钉的流模式。向其发送一条消息——无论是私聊还是已加入的群组——以测试功能。

tip

您可以将 hermes gateway 在后台运行，或作为 systemd 服务持久化运行。详细信息请参见部署文档。

故障排除​

机器人不响应消息​

原因：机器人功能未启用，或 DINGTALK_ALLOWED_USERS 中未包含您的用户 ID。

解决方法：检查应用设置中是否已启用机器人功能，并确认选择了“流模式”。检查 DINGTALK_ALLOWED_USERS 是否包含您的用户 ID。重启网关。

“dingtalk-stream not installed” 错误​

原因：Python 包 dingtalk-stream 未安装。

解决方法：安装该包：

pip install dingtalk-stream httpx

“DINGTALK_CLIENT_ID and DINGTALK_CLIENT_SECRET required”​

原因：环境变量或 .env 文件中未设置凭据。

解决方法：确认 DINGTALK_CLIENT_ID 和 DINGTALK_CLIENT_SECRET 在 ~/.hermes/.env 中正确设置。Client ID 即 AppKey，Client Secret 即 AppSecret，均来自钉钉开发者控制台。

流连接中断 / 重连循环​

原因：网络不稳定、钉钉平台维护或凭据问题。

解决方法：适配器会自动以指数退避方式重连（2秒 → 5秒 → 10秒 → 30秒 → 60秒）。请确认凭据有效，且应用未被停用。检查网络是否允许出站 WebSocket 连接。

机器人离线​

原因：Hermes 网关未运行，或连接失败。

解决方法：检查 hermes gateway 是否正在运行。查看终端输出中的错误信息。常见问题包括：凭据错误、应用被停用、dingtalk-stream 或 httpx 未安装。

“No session_webhook available”​

原因：机器人尝试回复但没有可用的会话 Webhook URL。通常发生在 Webhook 过期，或机器人在收到消息与发送回复之间重启。

解决方法：向机器人发送新消息——每条新消息都会提供一个新的会话 Webhook 用于回复。这是钉钉平台的正常限制；机器人只能回复最近收到的消息。

安全性​

warning

始终设置 DINGTALK_ALLOWED_USERS 以限制可与机器人交互的用户。若未设置，网关默认拒绝所有用户，这是一种安全措施。仅添加您信任的用户 ID——授权用户将获得对代理全部功能的访问权限，包括工具调用和系统访问。

有关保护 Hermes Agent 部署的更多信息，请参阅 安全指南。

注意事项​

  • 流模式：无需公网 URL、域名或 Webhook 服务器。连接由您的机器主动发起，通过 WebSocket 实现，因此可在 NAT、防火墙后以及本地环境中正常工作。
  • Markdown 回复：回复内容采用钉钉支持的 Markdown 格式，实现富文本展示效果。
  • 消息去重：适配器在 5 分钟窗口期内去重消息，防止重复处理同一消息。
  • 自动重连：若流连接中断，适配器会自动以指数退避方式重连。
  • 消息长度限制：单条回复最多 20,000 个字符，超出部分将被截断。