- Create an Enterprise Internal Bot — not a Custom Robot — to get full bidirectional messaging capability in DingTalk
- You need three credentials: App Key, App Secret, and Agent ID — all found in the DingTalk Developer Console
- DingTalk's message encryption is optional but strongly recommended for production; OpenClaw handles decryption automatically
- Set mention_only: true in group chats to prevent the agent responding to every message in every channel it joins
- The Agent ID is numeric and separate from the App ID — missing it is the most common configuration error
DingTalk is Alibaba's answer to Slack, Teams, and WeChat Work combined. It dominates enterprise communication in China and is expanding rapidly across Southeast Asia. If your team runs on DingTalk, an OpenClaw agent inside it means AI assistance exactly where work already happens — no browser tab switching, no copy-pasting into a separate tool.
Understanding DingTalk Bot Types Before You Build
DingTalk has two bot categories. Pick the wrong one and you'll waste an hour before realizing why it doesn't work.
Custom Robot — a simple one-way webhook that posts messages into a group chat. No message receiving. No user interaction. Not what you want for OpenClaw. Teams use these for CI/CD notifications and monitoring alerts.
Enterprise Internal Bot — a full application with bidirectional messaging, user authentication, group chat participation, and event subscription. This is what OpenClaw connects to.
The mistake most people make is starting with a Custom Robot because it's the first option on the page and setup looks simpler. Then they wonder why OpenClaw never receives messages. Enterprise Internal Bot is the only viable option for an interactive AI agent.
Creating an Enterprise Internal Bot requires an enterprise DingTalk account linked to an Alibaba Cloud organization. If you're on a personal DingTalk account, you can create test apps but cannot deploy them to your organization. Coordinate with your IT admin to get the right account type before starting.
Create the Enterprise Internal Bot
Go to the DingTalk Developer Console at open.dingtalk.com and sign in with your enterprise account. Navigate to Application Development → Enterprise Internal Development → Create Application.
- Select Enterprise Internal Bot as the app type.
- Fill in the bot name, description, and icon. These appear to users in DingTalk.
- On the Credentials page, copy the App Key and App Secret.
- Navigate to Bot Configuration → Message Receive Mode and select HTTP Mode. Paste your OpenClaw gateway webhook URL:
https://your-domain.com/webhooks/dingtalk. - Under Permissions, enable:
qyapi_robot_sendmsg(send messages) andContact.User.Read(read user info). - Go to Version Management & Release → Create Version, fill in version details, and submit for review. For internal enterprise apps, review is typically instant.
- After release, navigate to Bot Configuration and find the Agent ID — it's a numeric string like
12345678. Copy it now.
We'll get to the exact config in a moment — but first you need to understand why the Agent ID matters separately from the App Key.
The App Key identifies your application. The Agent ID identifies the specific bot instance deployed to your organization. One application can have multiple bot instances for different departments. OpenClaw needs the Agent ID to route messages to the correct bot persona — without it, your messages send but responses route nowhere.
Configure OpenClaw for DingTalk
Add the DingTalk channel block to channels.yaml:
channels:
- type: dingtalk
name: dingtalk-main
app_key: "dingxxxxxxxxxxxxxxxx"
app_secret: "your_app_secret_here"
agent_id: "12345678"
token: "your_webhook_token" # from HTTP Mode config
aes_key: "your_aes_key_here" # optional, enable for encryption
group_enabled: true
mention_only: true
agent: your-agent-name
memory_scope: userThe token comes from the HTTP Mode configuration page — it's a short string DingTalk uses to sign event payloads. The aes_key is optional; enabling it tells DingTalk to encrypt event payloads using AES-256-CBC. OpenClaw decrypts automatically if you provide the key.
Restart OpenClaw and check logs for successful registration:
[INFO] Channel registered: dingtalk-main (type=dingtalk, agent=your-agent-name)
[INFO] DingTalk webhook active on /webhooks/dingtalk
[INFO] Agent ID: 12345678 — message routing confirmedTest the connection by opening DingTalk and sending a direct message to your bot. The bot should appear in your DingTalk contact list under Enterprise Contacts after the app is deployed to your organization.
The webhook token validates that events come from DingTalk. The AES key decrypts the event body. Both are optional but both should be enabled in production. Configuring one without the other causes silent failures — DingTalk sends encrypted events, OpenClaw can't verify them, and messages disappear without error logs.
Advanced Use Cases for DingTalk + OpenClaw
Approval Workflow Automation
DingTalk's Workflow (审批) system can trigger OpenClaw agents via event subscription. When an employee submits a leave request or expense report, the event fires and your agent can check policy compliance, query HR systems, and post a summary to the approver — all before the approver opens the app.
Subscribe to bpms.instance.change events in the Developer Console and configure a routing rule in OpenClaw to send these to your workflow agent rather than your general assistant.
DingTalk Action Card Responses
DingTalk's Action Card message type lets your agent send interactive buttons. Configure it in the response handler:
response_format:
type: dingtalk_action_card
btn_orientation: "0" # 0 = vertical, 1 = horizontal
buttons:
- title: "Approve"
action_url: "dingtalk://dingtalkclient/action/approve"
- title: "Reject"
action_url: "dingtalk://dingtalkclient/action/reject"Multi-Department Routing
Route messages from different DingTalk departments to specialized agents using department ID matching:
routing:
- dept_id: "101" # engineering
agent: code-assistant
- dept_id: "102" # finance
agent: finance-bot
default_agent: general-assistant| Capability | Custom Robot | Enterprise Internal Bot |
|---|---|---|
| Receive messages | ✗ | ✓ |
| Send messages | ✓ | ✓ |
| Group chat support | ✗ | ✓ |
| User identity access | ✗ | ✓ |
| Interactive cards | ✗ | ✓ |
Common Mistakes with OpenClaw DingTalk Integration
- Using Custom Robot instead of Enterprise Internal Bot — Custom Robots cannot receive messages. If users message your bot and nothing happens, check which bot type you created. Start over with Enterprise Internal Bot.
- Missing the Agent ID — The App Key and Agent ID are both required. The Agent ID is numeric, found under Bot Configuration after you deploy a version. Without it, outgoing messages fail silently.
- HTTP Mode URL not saved — DingTalk requires you to explicitly save the HTTP mode URL. Navigating away before clicking Save discards the webhook URL, and events never reach OpenClaw.
- Not deploying the app to the organization — A created app is not automatically available to your organization. Go to Version Management, create a version, and release it. Only then does the bot appear in DingTalk contacts.
- Mismatched token and AES key — If you enable encryption in DingTalk but don't add the AES key to channels.yaml (or vice versa), event verification fails and all messages are dropped. Keep both settings in sync.
Frequently Asked Questions
Does OpenClaw have a DingTalk channel adapter?
OpenClaw includes a DingTalk adapter from v0.9. Add a dingtalk channel block to channels.yaml with your App Key, App Secret, and Agent ID. The adapter handles OAuth 2.0 token management, message encryption, and event routing automatically without extra dependencies.
What type of DingTalk bot should I create for OpenClaw?
Create an Enterprise Internal Bot — not a Custom Robot. The Enterprise Internal Bot gets full API access including bidirectional messaging and group chat participation. Custom Robots only support one-way webhook posting and cannot receive messages, making them useless for interactive AI agents.
How do I get the DingTalk Agent ID for my OpenClaw config?
After creating your bot in the DingTalk Developer Console, navigate to Application Info. The Agent ID appears in the Basic Info section as a numeric string. It's separate from the App ID — you need both. The Agent ID identifies the specific bot instance within your organization.
Can OpenClaw respond to DingTalk group chat messages?
Yes. Enable group chat in the Developer Console under Message Receive Mode and set group_enabled: true in channels.yaml. The agent responds when @mentioned in group chats. DingTalk delivers a conversation_id with each message so the agent replies in the correct thread.
Does DingTalk require message encryption for bots?
DingTalk supports but does not require message encryption. For production deployments, enable it in the Developer Console and add your aes_key to channels.yaml. OpenClaw decrypts incoming payloads transparently. For internal bots handling non-sensitive data, unencrypted is acceptable.
What is the DingTalk bot message rate limit?
DingTalk enforces 20 messages per minute per bot for standard enterprise apps. OpenClaw's outgoing message queue respects this automatically. If your agent generates high-volume responses, configure batch_responses: true to consolidate multiple short replies into one message.
J. Donovan has documented enterprise bot integrations across DingTalk, WeChat Work, and Teams for organizations operating in China and the Asia-Pacific region. Has personally debugged the Agent ID misconfiguration on three separate client deployments.