DingTalk Setup

Hermes Agent integrates with DingTalk (钉钉) as a chatbot, letting you chat with your AI assistant through direct messages or group chats. The bot connects via DingTalk’s Stream Mode — a long-lived WebSocket connection that requires no public URL or webhook server — and replies using markdown-formatted messages through DingTalk’s session webhook API.

Before setup, here’s the part most people want to know: how Hermes behaves once it’s in your DingTalk workspace.

How Hermes Behaves​

Context Behavior
DMs (1:1 chat) Hermes responds to every message. No@mentionneeded. Each DM has its own session.
Group chats Hermes responds when you@mentionit. Without a mention, Hermes ignores the message.
Shared groups with multiple users By default, Hermes isolates session history per user inside the group. Two people talking in the same group do not share one transcript unless you explicitly disable that.

@mention @mention

Session Model in DingTalk​

By default:

This is controlled byconfig.yaml:

config.yaml

group_sessions_per_user: true

Set it tofalseonly if you explicitly want one shared conversation for the entire group:

false

group_sessions_per_user: false

This guide walks you through the full setup process — from creating your DingTalk bot to sending your first message.

Prerequisites​

Install the required Python packages:

cd ~/.hermes/hermes-agent && uv pip install -e ".[dingtalk]"

Or individually:

pip install dingtalk-stream httpx alibabacloud-dingtalk

dingtalk-stream httpx alibabacloud-dingtalk

Step 1: Create a DingTalk App​

  1. Go to theDingTalk Developer Console.
  2. Log in with your DingTalk admin account.
  3. ClickApplication Development→Custom Apps→Create App via H5 Micro-App(orRobotdepending on your console version).
  4. Fill in:App Name: e.g.,Hermes AgentDescription: optional
  5. After creating, navigate toCredentials & Basic Infoto find yourClient ID(AppKey) andClient Secret(AppSecret). Copy both.

Hermes Agent

The Client Secret is only displayed once when you create the app. If you lose it, you’ll need to regenerate it. Never share these credentials publicly or commit them to Git.

Step 2: Enable the Robot Capability​

  1. In your app’s settings page, go toAdd Capability→Robot.
  2. Enable the robot capability.
  3. UnderMessage Reception Mode, selectStream Mode(recommended — no public URL needed).

Stream Mode is the recommended setup. It uses a long-lived WebSocket connection initiated from your machine, so you don’t need a public IP, domain name, or webhook endpoint. This works behind NAT, firewalls, and on local machines.

Step 3: Find Your DingTalk User ID​

Hermes Agent uses your DingTalk User ID to control who can interact with the bot. DingTalk User IDs are alphanumeric strings set by your organization’s admin.

To find yours:

  1. Ask your DingTalk organization admin — User IDs are configured in the DingTalk admin console underContacts→Members.
  2. Alternatively, the bot logs thesender_idfor each incoming message. Start the gateway, send the bot a message, then check the logs for your ID.

sender_id

Step 4: Configure Hermes Agent​

Run the guided setup command:

hermes gateway setup

SelectDingTalkwhen prompted. The setup wizard can authorize via one of two paths:

~/.hermes/.env

Because DingTalk’sverification_uri_completeis hardcoded to the openClaw identity at the API layer, the QR currently authorizes under anopenClawsource string until Alibaba / DingTalk-Real-AI registers a Hermes-specific template server-side. This is purely how DingTalk presents the consent screen — the bot you create is fully yours and private to your tenant.

verification_uri_complete openClaw

Option B: Manual Configuration​

Add the following to your~/.hermes/.envfile:

~/.hermes/.env

# RequiredDINGTALK_CLIENT_ID=your-app-keyDINGTALK_CLIENT_SECRET=your-app-secret# Security: restrict who can interact with the botDINGTALK_ALLOWED_USERS=user-id-1# Multiple allowed users (comma-separated)# DINGTALK_ALLOWED_USERS=user-id-1,user-id-2# Optional: group-chat gating (mirrors Slack/Telegram/Discord/WhatsApp)# DINGTALK_REQUIRE_MENTION=true# DINGTALK_FREE_RESPONSE_CHATS=cidABC==,cidDEF==# DINGTALK_MENTION_PATTERNS=^小马# DINGTALK_HOME_CHANNEL=cidXXXX==# DINGTALK_ALLOW_ALL_USERS=true

Optional behavior settings in~/.hermes/config.yaml:

~/.hermes/config.yaml

group_sessions_per_user: truegateway:  platforms:    dingtalk:      extra:        # Require @mention in groups before the bot replies (parity with Slack/Telegram/Discord).        # DMs ignore this — the bot always replies in 1:1 chats.        require_mention: true        # Per-platform allowlist. When set, only these DingTalk user IDs can interact with the bot        # (same semantics as DINGTALK_ALLOWED_USERS, but scoped here instead of in .env).        allowed_users:          - user-id-1          - user-id-2

group_sessions_per_user: true require_mention: true allowed_users dingtalk.extra DINGTALK_ALLOWED_USERS

Start the Gateway​

Once configured, start the DingTalk gateway:

hermes gateway

The bot should connect to DingTalk’s Stream Mode within a few seconds. Send it a message — either a DM or in a group where it’s been added — to test.

You can runhermes gatewayin the background or as a systemd service for persistent operation. See the deployment docs for details.

hermes gateway

Features​

AI Cards​

Hermes can reply using DingTalk AI Cards instead of plain markdown messages. Cards provide a richer, more structured display and support streaming updates as the agent generates its response.

To enable AI Cards, configure a card template ID inconfig.yaml:

config.yaml

platforms:  dingtalk:    enabled: true    extra:      card_template_id: "your-card-template-id"

You can find your card template ID in the DingTalk Developer Console under your app’s AI Card settings. When AI Cards are enabled, all replies are sent as cards with streaming text updates.

Emoji Reactions​

Hermes automatically adds emoji reactions to your messages to show processing status:

These reactions work in both DMs and group chats.

Display Settings​

You can customize DingTalk’s display behavior independently from other platforms:

display:  platforms:    dingtalk:      show_reasoning: false   # Show model reasoning/thinking in replies      streaming: true         # Enable streaming responses (works with AI Cards)      tool_progress: all      # Show tool execution progress (all/new/off)      interim_assistant_messages: true  # Show intermediate commentary messages

To disable tool progress and intermediate messages for a cleaner experience:

display:  platforms:    dingtalk:      tool_progress: off      interim_assistant_messages: false

Troubleshooting​

Bot is not responding to messages​

Cause: The robot capability isn’t enabled, orDINGTALK_ALLOWED_USERSdoesn’t include your User ID.

DINGTALK_ALLOWED_USERS

Fix: Verify the robot capability is enabled in your app settings and that Stream Mode is selected. Check that your User ID is inDINGTALK_ALLOWED_USERS. Restart the gateway.

DINGTALK_ALLOWED_USERS

“dingtalk-stream not installed” error​

Cause: Thedingtalk-streamPython package is not installed.

dingtalk-stream

Fix: Install it:

pip install dingtalk-stream httpx

“DINGTALK_CLIENT_ID and DINGTALK_CLIENT_SECRET required”​

Cause: The credentials aren’t set in your environment or.envfile.

.env

Fix: VerifyDINGTALK_CLIENT_IDandDINGTALK_CLIENT_SECRETare set correctly in~/.hermes/.env. The Client ID is your AppKey, and the Client Secret is your AppSecret from the DingTalk Developer Console.

DINGTALK_CLIENT_ID DINGTALK_CLIENT_SECRET ~/.hermes/.env

Stream disconnects / reconnection loops​

Cause: Network instability, DingTalk platform maintenance, or credential issues.

Fix: The adapter automatically reconnects with exponential backoff (2s → 5s → 10s → 30s → 60s). Check that your credentials are valid and your app hasn’t been deactivated. Verify your network allows outbound WebSocket connections.

Bot is offline​

Cause: The Hermes gateway isn’t running, or it failed to connect.

Fix: Check thathermes gatewayis running. Look at the terminal output for error messages. Common issues: wrong credentials, app deactivated,dingtalk-streamorhttpxnot installed.

hermes gateway dingtalk-stream httpx

“No session_webhook available”​

Cause: The bot tried to reply but doesn’t have a session webhook URL. This typically happens if the webhook expired or the bot was restarted between receiving the message and sending the reply.

Fix: Send a new message to the bot — each incoming message provides a fresh session webhook for replies. This is a normal DingTalk limitation; the bot can only reply to messages it has received recently.

Security​

Always setDINGTALK_ALLOWED_USERSto restrict who can interact with the bot. Without it, the gateway denies all users by default as a safety measure. Only add User IDs of people you trust — authorized users have full access to the agent’s capabilities, including tool use and system access.

DINGTALK_ALLOWED_USERS

For more information on securing your Hermes Agent deployment, see theSecurity Guide.

Notes​

card_template_id