OpenClaw DingTalk Integration: Complete Setup Guide

DingTalk Integration Overview

OpenClaw connects to DingTalk via community plugins. There are two main options to choose from:

Both plugins use DingTalk's Stream mode (WebSocket long connection), so no public IP or domain is required. It works from home computers, corporate intranets, and behind NATs.

This guide uses the @soimy version as the primary example, which covers 90%+ of use cases.

Before You Start

Make sure you have the following ready:

• OpenClaw installed and running. If not, follow the installation guide
• DingTalk organization admin or developer access — you'll need to create an app on the DingTalk Open Platform
• Confirm that Gateway is running:

openclaw gateway status

Good news: DingTalk Stream mode has OpenClaw connect outbound to DingTalk's servers. No public IP, no domain, no SSL certificate. Works behind NATs and corporate firewalls.

Step 1: Install the DingTalk Plugin

openclaw plugins install @soimy/dingtalk

Verify the installation:

openclaw plugins list
# You should see @soimy/dingtalk

If you need AI Card streaming and multi-agent routing, install this instead: openclaw plugins install @dingtalk-real-ai/dingtalk-connector

Step 2: Create a DingTalk Internal App

1. Log in to the DingTalk Open Platform and open the Developer Console
2. Click Create Application → select Internal Enterprise Development
3. Choose the Bot app type, fill in a name (e.g., "AI Assistant") and description
4. Once created, go to the app details → Credentials & Basic Info
5. Copy the ClientID (also called AppKey, format dingXXX) and ClientSecret (also called AppSecret)

Warning: Your ClientSecret is essentially a password. Never commit it to Git or share it in chat.

Step 3: Configure Stream Mode and Permissions

Enable Stream Mode

Go to your app → Bot Configuration → set the message receiving mode to Stream mode.

This is a critical step. If you select HTTP mode instead, you'll need a public URL. Stream mode uses a WebSocket long connection — no public endpoint required.

Configure Permissions

In Permission Management, add the following permissions:

Step 4: Publish the App

After configuring permissions, you need to publish:

1. Go to Version Management & Release → Create a new version
2. Fill in the version number and release notes → Submit
3. Once your organization admin approves, users can find the bot by searching for its name in DingTalk

If you are the admin, approval is usually instant.

Step 5: OpenClaw DingTalk Channel Configuration

Manual Configuration

Edit ~/.openclaw/openclaw.json:

{
  channels: {
    dingtalk: {
      enabled: true,
      clientId: "dingXXXXXX",       // From the Open Platform
      clientSecret: "your-secret",   // From the Open Platform
      robotCode: "dingXXXXXX",      // Bot identifier
      corpId: "dingXXXXXX",         // Organization CorpId
      agentId: "123456789",         // App AgentId
      dmPolicy: "open",             // DM policy
      groupPolicy: "open",          // Group chat policy
      messageType: "markdown",      // Reply format
      streaming: true               // Streaming output
    }
  }
}

Configuration Reference

Step 6: Start and Test

Launch the Gateway

openclaw gateway restart
openclaw logs --follow     # Watch logs in real time

Test Message Flow

1. In DingTalk, search for your bot by name and start a DM
2. Send a message (anything will do)
3. Confirm the AI responds

Verify the connection:

openclaw gateway status
# You should see DingTalk: connected

At this point, basic messaging is up and running.

DingTalk Group Chat Setup

With the default configuration (groupPolicy: "open"), group chats work out of the box:

1. Add the bot to a group chat
2. @mention the bot's name followed by your question
3. The bot will respond

Conversations are isolated by chat. Each DM and group chat has its own context, which resets automatically after 30 minutes of inactivity.

AI Card Streaming Configuration

DingTalk's AI Card delivers a ChatGPT-like typewriter experience where the response updates progressively inside a card.

How to Enable

{
  channels: {
    dingtalk: {
      messageType: "card",  // Or "markdown" + streaming: true
      streaming: true
    }
  }
}

Prerequisites

• Your DingTalk app must have Card.Instance.Write and Card.Streaming.Write permissions
• Republish the app after changing permissions

Multi-Agent Routing

If you're using the @dingtalk-real-ai plugin, you can set up multi-agent routing:

{
  bindings: [
    { agentId: "main", match: { channel: "dingtalk", peer: { kind: "direct" } } },
    { agentId: "tech-support", match: { channel: "dingtalk", peer: { kind: "group" } } }
  ]
}

This routes DMs to a general-purpose assistant and group messages to a tech support agent, keeping them separate.

DingTalk Command Quick Reference

FAQ

Do I need a public IP?

No. The DingTalk plugin uses Stream mode (WebSocket long connection), where OpenClaw connects outbound to DingTalk's servers. Works from home networks, corporate intranets, and behind NATs.

Which DingTalk plugin should I pick?

For most users, go with @soimy/dingtalk — it has more documentation and active community support. If you need multi-agent routing or async processing, choose the @dingtalk-real-ai version.

Can I use other channels at the same time?

Yes. OpenClaw supports multiple channels running concurrently. DingTalk, Feishu, Telegram, Discord, and more can all share the same AI agent, with each channel configured independently.

Responses are slow — how do I fix that?

Enable streaming output (streaming: true) first — it makes responses feel much faster since users see text appearing in real time. If it's still slow, try switching to a faster model or check whether your AI service has latency issues.

My ClientSecret was compromised — what should I do?

Go to the DingTalk Open Platform immediately and reset the secret. Update your OpenClaw configuration and restart the Gateway. The old secret is invalidated instantly.

DingTalk stopped working after an OpenClaw upgrade?

This is a known compatibility issue. Start by updating the plugin: openclaw plugins update @soimy/dingtalk. If the problem continues, check the plugin's GitHub Issues for version-specific guidance.

The bot doesn't respond at all — how do I debug?

Work through this checklist:

1. Is the app published? (Draft status won't work)
2. Is the message receiving mode set to Stream mode? (Not HTTP mode)
3. Are the ClientID and ClientSecret correct?
4. Is the plugin installed? (openclaw plugins list)
5. Is your AI model's API key configured?
6. Run openclaw doctor for a full diagnostic

The bot doesn't respond when @mentioned in groups?

Confirm the bot has been added to the group and that groupPolicy is not disabled. Check openclaw logs --follow for any error messages.

AI Card streaming isn't working?

Make sure your DingTalk app has Card.Instance.Write and Card.Streaming.Write permissions. After changing permissions, you must republish the app for the changes to take effect.

What's Next After DingTalk Setup

With DingTalk connected, here's what else you can explore:

• Browse all supported channels — 50+ channel integrations
• Skills directory — extend your AI assistant's capabilities
• Troubleshooting guide — general troubleshooting reference
• Feishu integration guide — another enterprise collaboration platform
• Telegram integration guide — a popular international channel
• Complete beginner guide — learn OpenClaw from scratch