Hermes Agent + DingTalk Integration: Enterprise Chat Gateway Setup Guide

hermes gateway setup

# Exact command depends on your deployment; common options:
systemctl restart hermes-gateway
# or
hermes gateway restart

Safe Setup Pattern: Private First, Group Later

The official documentation repeatedly stresses a cautious rollout strategy. The safe setup pattern is:

1. Configure credentials and store them in the active Hermes profile environment.
2. Run hermes gateway setup and enable only the platform you are testing.
3. Allowlist one private user or test room before adding team-wide rooms.
4. Send a harmless prompt such as "reply with the active profile and enabled platform name."
5. After the smoke test, decide whether the channel can use tools, cron reports, file access, or project-specific skills.

This pattern prevents accidental exposure of sensitive tools or actions to a broad audience before behavior is verified.

Features of the DingTalk Integration

The integration provides several key features, all of which must be understood for proper configuration:

• DingTalk gateway access for chat-based Hermes requests. This is the core feature: users can send prompts to the DingTalk bot and receive responses.
• Allowlisted users, rooms, groups, or contacts before broader rollout. You can restrict the bot to respond only to specific individuals or channels.
• Tool-backed answers using the same Hermes skills and MCP servers available from the CLI. The chat gateway uses the same tool set as the CLI, but scope access carefully because chat channels often have different trust levels than your terminal.
• Delivery target for cron reports, incident summaries, approval prompts, and project updates. DingTalk can be a destination for automated messages generated by Hermes' cron jobs or other triggers.
• Profile and credential boundaries so each channel can be scoped to the right trust level. Different DingTalk channels can use different Hermes profiles, each with its own set of allowed tools and credentials.
• Private smoke-test flow before enabling production rooms or free-response behavior. The built-in test flow ensures the integration works before exposing it to a wider audience.

Common Workflows

Once the gateway is stable, DingTalk becomes a convenient control surface for Hermes workflows. The documentation identifies four common workflow categories:

Incident Triage

From a DingTalk message, Hermes can:

1. Summarize an incoming alert.
2. Inspect logs or dashboards using MCP servers or tools.
3. Post recommended next actions back to the chat.

This keeps the incident response loop entirely within the chat platform your team already monitors.

Project Updates

Users can ask Hermes what changed in GitHub, Linear, or Notion and receive a concise report. For example:

User: What issues were closed in the frontend repo this week?
Hermes: [Summarizes closed issues with links and assignees]

Approvals

Let Hermes draft an action and ask for confirmation before executing. For example:

1. User requests a deployment.
2. Hermes drafts the deployment plan and posts it to DingTalk.
3. Hermes asks: "Approve this deployment? Reply 'yes' to proceed."
4. User replies "yes."
5. Hermes executes the deployment.

This pattern keeps a human in the loop for sensitive operations.

Knowledge Capture

Turn a chat thread into a task, document, issue, or reusable skill. For example, after solving a problem in chat, a user can ask Hermes to create a knowledge base article or a Jira ticket documenting the solution.

Common Setup Issues and Troubleshooting

The documentation lists several common issues and their likely causes:

No Response in DingTalk

If the bot does not respond to messages, check the following:

• Confirm the gateway is running. Use systemctl status hermes-gateway or equivalent.
• Confirm the DingTalk platform adapter is enabled. Run hermes gateway setup and verify the platform is listed as active.
• Confirm the chat or contact is allowlisted. If you are not on the allowlist, the bot will silently ignore your messages.

Bot Replies in DM but Not in a Group

If the bot works in private messages but not in a group chat, check:

• Group permissions: Ensure the bot has been added to the group and has permission to read and send messages.
• Mention/free-response settings: Some groups require the bot to be @mentioned before it responds. Check your Hermes configuration for group response behavior.
• Whether the gateway received the group update: After adding the bot to a group, the gateway may need a restart to recognize the new channel.

Wrong Profile or Tools Are Active

If the bot responds but uses the wrong tools or profile, verify:

• The Hermes profile running the gateway is the one you intend to use.
• Project-specific secrets are stored in the correct profile, not a shared or default profile.

Messages Are Too Long or Poorly Formatted

DingTalk has message length limits. If responses are truncated or poorly formatted:

• Use concise prompts.
• Route long reports to email, docs, or a file instead of the chat message.

Advanced Configuration Details

Profile and Credential Boundaries

Each DingTalk channel can be scoped to a different Hermes profile. This allows you to have, for example:

• A "production" profile that has read-only access to logs and dashboards, used in a team-wide operations channel.
• A "admin" profile that has write access to deploy and configure systems, used only in a private chat with the platform operator.

To set this up, configure the DingTalk bot to use a specific Hermes profile by setting the HERMES_PROFILE environment variable or using the profile selection mechanism in your gateway configuration.

Using DingTalk as a Delivery Target for Cron Reports

Hermes' cron jobs can send reports directly to DingTalk. To set this up:

1. Configure a cron job in Hermes that generates a report (e.g., daily deployment summary).
2. Set the delivery target to the DingTalk channel (using the channel ID or webhook URL).
3. Ensure the DingTalk gateway is running and the channel is allowlisted for incoming messages.

Webhooks: Triggering Agent Runs from External Systems

Beyond human chat messages, DingTalk can receive webhooks from external systems. This allows, for example, a monitoring system to send an alert to DingTalk, which then triggers a Hermes agent run to investigate. The documentation mentions webhooks as a related feature: "Trigger agent runs from external systems instead of a human chat message."

Frequently Asked Questions

Can Hermes run from DingTalk?

Yes. DingTalk can be used as a Hermes messaging gateway when the platform adapter is configured and the gateway is running.

Should I enable this in a group immediately?

No. Start with a private or allowlisted test, verify behavior, then add group access only when permissions and response rules are clear.

Can the chat gateway use the same tools as the CLI?

It can use enabled Hermes tools, skills, and MCP servers for that profile. Scope tool access carefully because chat channels often have different trust levels than your terminal.

What is the safest first test?

Ask for a harmless status reply that confirms the active profile and platform. Do not start with file edits, deploys, purchases, or external sends.

Going Further

After successfully setting up the DingTalk gateway, explore these related areas from the official documentation:

• Messaging setup overview: Set up Hermes gateway platforms and verify message delivery safely.
• Pricing and managed cloud: Use managed hosting when uptime and mobile access matter more than maintaining a gateway server.
• Webhooks: Trigger agent runs from external systems instead of a human chat message.
• Other integrations: The documentation lists related setup guides for WeCom, Feishu, Slack, Telegram, Discord, WhatsApp, and Signal. Each platform has its own adapter and configuration steps.