dingtalk-openclaw-connector

DingTalk OpenClaw Connector Skill

Skill by ara.so — Hermes Skills collection.

Official DingTalk channel plugin for OpenClaw, enabling AI agents to receive/send messages, manage documents, calendars, todos, and more within DingTalk enterprise workspace.

What It Does

This TypeScript connector bridges OpenClaw agents with DingTalk's ecosystem:

Messaging: Receive/send private/group messages, @mentions, rich media (text/Markdown/images)
Documents: Create, append, search, list DingTalk documents
DING Notifications: Send priority alerts to users/groups
Todos: Create personal todos, check status, set deadlines
AI Tables: Create tables, read/write rows, query data
Calendar: Manage calendars, events (CRUD + search), attendees, availability
Journal: Submit daily/weekly reports, query history
AI Cards: Streaming responses with typewriter effect, interactive buttons
Multi-Agent Routing: Connect multiple bots to different OpenClaw agents
Access Control: Flexible permission policies for private/group chats

Prerequisites

OpenClaw ≥ 2026.4.9 (check: openclaw -v, upgrade: npm install -g openclaw)
Node.js (for installation)
DingTalk App (mobile, for QR authorization)

Installation

Quick Install with Auto-Authorization

npx -y @dingtalk-real-ai/dingtalk-connector install

Scan the QR code displayed in terminal with DingTalk mobile app. After seeing "Success! Bot configured.", restart gateway:

openclaw gateway restart

Manual Installation (if auto-auth fails)

npm install -g @dingtalk-real-ai/dingtalk-connector

Then follow manual setup guide to configure credentials.

Configuration

Plugin config is stored in OpenClaw's channel settings. Key environment variables:

# DingTalk bot credentials (obtained during authorization)
DINGTALK_CLIENT_ID=your_client_id
DINGTALK_CLIENT_SECRET=your_client_secret
DINGTALK_ROBOT_CODE=your_robot_code

# Optional: Multi-agent routing
DINGTALK_AGENT_MAPPING='{"bot_code_1":"agent_1","bot_code_2":"agent_2"}'

# Optional: Access control
DINGTALK_PRIVATE_CHAT_POLICY=whitelist  # whitelist|blacklist|all
DINGTALK_GROUP_CHAT_POLICY=all          # whitelist|blacklist|all
DINGTALK_WHITELIST=user_id_1,user_id_2

Access Control Policies

Configure who can interact with your bot:

// In OpenClaw channel config
{
  "privateChatPolicy": "whitelist",  // Only whitelisted users
  "groupChatPolicy": "all",          // All groups
  "whitelist": ["user_123", "user_456"],
  "blacklist": []
}

Options: all, whitelist, blacklist

Key Capabilities

1. Message Handling

The connector automatically receives and routes DingTalk messages to your OpenClaw agent:

// Agent receives message context
interface MessageContext {
  conversationId: string;
  senderId: string;
  senderName: string;
  content: {
    text?: string;
    images?: Array<{ downloadCode: string; url: string }>;
    files?: Array<{ fileName: string; downloadCode: string }>;
  };
  isGroupChat: boolean;
  atUsers?: string[];
}

2. Sending Messages

Text Message:

// Agent action
{
  "action": "sendMessage",
  "params": {
    "conversationId": "cid_xxx",
    "content": "Hello from OpenClaw!"
  }
}

Markdown with @mention:

{
  "action": "sendMessage",
  "params": {
    "conversationId": "cid_xxx",
    "content": "## Report\n@user_123 please review",
    "format": "markdown",
    "atUsers": ["user_123"]
  }
}

Image Message:

{
  "action": "sendMessage",
  "params": {
    "conversationId": "cid_xxx",
    "imageUrl": "https://example.com/image.png"
    // Or local path: "imagePath": "/path/to/image.png"
  }
}

3. AI Card Streaming

Show real-time thinking/generation progress:

// Enable in channel config
{
  "enableAICard": true,
  "streamingMode": "typewriter"  // typewriter effect
}

The connector automatically wraps agent responses in interactive cards with states:

🤔 Thinking...
✍️ Generating...
✅ Complete

4. Document Operations

Create Document:

{
  "action": "createDocument",
  "params": {
    "title": "Meeting Notes",
    "content": "# Agenda\n- Item 1\n- Item 2",
    "spaceId": "space_xxx"  // optional
  }
}

Append to Document:

{
  "action": "appendDocument",
  "params": {
    "documentId": "doc_xxx",
    "content": "\n## New Section\nAdditional notes..."
  }
}

Search Documents:

{
  "action": "searchDocuments",
  "params": {
    "keyword": "meeting",
    "maxResults": 10
  }
}

5. DING Notifications

Send high-priority alerts:

{
  "action": "sendDing",
  "params": {
    "receiverUserIds": ["user_123", "user_456"],
    "content": "Urgent: Server down!",
    "remindType": "DING_SMS"  // DING_NOTICE or DING_SMS
  }
}

6. Todo Management

Create Todo:

{
  "action": "createTodo",
  "params": {
    "subject": "Review PR #123",
    "description": "Check code quality",
    "dueTime": "2026-05-20T17:00:00Z",
    "executorIds": ["user_123"]
  }
}

Query Todos:

{
  "action": "getTodos",
  "params": {
    "status": "PENDING",  // PENDING|DONE
    "startDate": "2026-05-01",
    "endDate": "2026-05-31"
  }
}

7. Calendar & Events

Create Calendar Event:

{
  "action": "createCalendarEvent",
  "params": {
    "calendarId": "cal_xxx",
    "summary": "Team Sync",
    "startTime": "2026-05-20T14:00:00+08:00",
    "endTime": "2026-05-20T15:00:00+08:00",
    "location": "Conference Room A",
    "attendees": [
      { "userId": "user_123" },
      { "userId": "user_456" }
    ]
  }
}

Query Events:

{
  "action": "searchCalendarEvents",
  "params": {
    "calendarId": "cal_xxx",
    "startTime": "2026-05-20T00:00:00+08:00",
    "endTime": "2026-05-21T00:00:00+08:00"
  }
}

Check Availability:

{
  "action": "checkAvailability",
  "params": {
    "userIds": ["user_123", "user_456"],
    "startTime": "2026-05-20T14:00:00+08:00",
    "endTime": "2026-05-20T15:00:00+08:00"
  }
}

8. AI Tables

Create Table:

{
  "action": "createAITable",
  "params": {
    "name": "Customer Database",
    "fields": [
      { "name": "Name", "type": "TEXT" },
      { "name": "Email", "type": "TEXT" },
      { "name": "Status", "type": "SINGLE_SELECT", "options": ["Active", "Inactive"] }
    ]
  }
}

Insert Row:

{
  "action": "insertTableRow",
  "params": {
    "tableId": "tbl_xxx",
    "fields": {
      "Name": "John Doe",
      "Email": "john@example.com",
      "Status": "Active"
    }
  }
}

Query Rows:

{
  "action": "queryTableRows",
  "params": {
    "tableId": "tbl_xxx",
    "filter": {
      "Status": "Active"
    },
    "maxResults": 50
  }
}

9. Journal (Reports)

Submit Daily Report:

{
  "action": "submitJournal",
  "params": {
    "type": "daily",
    "date": "2026-05-20",
    "content": "## Completed\n- Feature A\n- Bug fix B\n\n## Tomorrow\n- Feature C"
  }
}

Query Reports:

{
  "action": "getJournals",
  "params": {
    "type": "weekly",
    "startDate": "2026-05-01",
    "endDate": "2026-05-15"
  }
}

Multi-Agent Routing

Connect multiple DingTalk bots to different OpenClaw agents for specialized tasks:

Configuration

# In .env or OpenClaw config
DINGTALK_AGENT_MAPPING='{
  "robot_code_hr": "hr_agent",
  "robot_code_it": "it_support_agent",
  "robot_code_sales": "sales_agent"
}'

Agent Definitions

# openclaw.config.yaml
agents:
  hr_agent:
    name: HR Assistant
    model: gpt-4
    systemPrompt: You are an HR assistant handling employee queries
    
  it_support_agent:
    name: IT Support
    model: gpt-4
    systemPrompt: You provide IT technical support
    
  sales_agent:
    name: Sales Helper
    model: gpt-4
    systemPrompt: You assist with sales inquiries and CRM

Each bot routes to its designated agent automatically. See Multi-Agent Setup Guide.

Common Patterns

Pattern 1: Auto-Reply Bot

// Agent receives all group messages where bot is @mentioned
// Auto-respond with context-aware answers
async function handleMessage(context: MessageContext) {
  const { content, isGroupChat, atUsers } = context;
  
  if (isGroupChat && !atUsers?.includes(botUserId)) {
    return; // Ignore if not @mentioned
  }
  
  const response = await generateResponse(content.text);
  
  return {
    action: "sendMessage",
    params: {
      conversationId: context.conversationId,
      content: response
    }
  };
}

Pattern 2: Document Search Assistant

// Search docs and create summary
async function searchAndSummarize(query: string) {
  // 1. Search documents
  const docs = await executeAction({
    action: "searchDocuments",
    params: { keyword: query, maxResults: 5 }
  });
  
  // 2. Generate summary
  const summary = await summarize(docs);
  
  // 3. Create new doc with results
  return executeAction({
    action: "createDocument",
    params: {
      title: `Search Results: ${query}`,
      content: summary
    }
  });
}

Pattern 3: Meeting Scheduler

// Find available slot and create event
async function scheduleMeeting(attendeeIds: string[], duration: number) {
  const now = new Date();
  const nextWeek = new Date(now.getTime() + 7 * 24 * 60 * 60 * 1000);
  
  // 1. Check availability
  const availability = await executeAction({
    action: "checkAvailability",
    params: {
      userIds: attendeeIds,
      startTime: now.toISOString(),
      endTime: nextWeek.toISOString()
    }
  });
  
  // 2. Find first free slot
  const freeSlot = findFreeSlot(availability, duration);
  
  // 3. Create event
  return executeAction({
    action: "createCalendarEvent",
    params: {
      summary: "Team Meeting",
      startTime: freeSlot.start,
      endTime: freeSlot.end,
      attendees: attendeeIds.map(id => ({ userId: id }))
    }
  });
}

Pattern 4: Task Tracker Bot

// Create todo from message command
async function createTaskFromMessage(message: string, conversationId: string) {
  // Parse: "todo: Review PR #123 by Friday"
  const match = message.match(/todo:\s*(.+?)\s+by\s+(.+)/i);
  if (!match) return;
  
  const [, task, deadline] = match;
  
  // Create todo
  const todo = await executeAction({
    action: "createTodo",
    params: {
      subject: task,
      dueTime: parseDeadline(deadline)
    }
  });
  
  // Confirm in chat
  return executeAction({
    action: "sendMessage",
    params: {
      conversationId,
      content: `✅ Task created: ${task}\n📅 Due: ${deadline}`
    }
  });
}

Troubleshooting

Bot Not Responding

Check gateway status:
```
openclaw gateway status
```
Restart gateway:
```
openclaw gateway restart
```

Verify credentials:

# Check if config exists
openclaw config list

Check logs:
```
openclaw gateway logs
```

Authorization Failed

Ensure you're using DingTalk mobile app (not desktop) to scan QR
Check if QR code expired (timeout ~5 min), restart installation
Verify network access to DingTalk API endpoints

Message Not Received

Confirm bot is in the conversation (group chat: must add bot; private: user initiated)
Check access control policies (whitelist/blacklist)
Verify bot has required permissions in DingTalk admin console

Streaming AI Card Not Working

// Ensure enabled in config
{
  "enableAICard": true,
  "streamingMode": "typewriter"
}

Feature requires OpenClaw ≥ 2026.4.9
Check browser console for WebSocket errors

Multi-Agent Routing Issues

Verify DINGTALK_AGENT_MAPPING JSON syntax
Ensure agent names match those in openclaw.config.yaml
Check robot codes are correct (not client IDs)

Image Upload Fails

Ensure image file exists and is readable
Check file size (DingTalk limit: 20MB for images)
Verify image format (JPEG, PNG, GIF supported)
For URLs, ensure publicly accessible

Calendar Events Not Creating

Verify user has calendar permissions in DingTalk
Check time format (ISO 8601 with timezone)
Ensure calendarId is valid (create calendar first if needed)

Common Error Codes

40014: Invalid access token → Re-authorize bot
60020: Permission denied → Check DingTalk app permissions
90002: Message frequency limit → Rate limiting, slow down
71006: Robot not in conversation → Add bot to group/chat

Testing

Quick test after installation:

# Send test message to bot in DingTalk
# Expected: Bot responds with AI-generated reply in card format

Verify specific features:

// Test document creation
// In DingTalk: @bot create a document titled "Test"

// Test todo
// In DingTalk: @bot remind me to review code tomorrow

// Test search
// In DingTalk: @bot search for meeting notes from last week

Security Notes

Model Risks: AI may hallucinate or execute unintended actions
Authorization Scope: Bot operates with user permissions granted during setup
Data Privacy: Follow company security policies if using corporate account
Default Protections: Do NOT disable default security configs without understanding risks
Recommended Use: Personal assistant, not production enterprise deployment

Additional Resources

Manual Setup Guide
DEAP Agent Integration (local device operations)
Multi-Agent Routing Examples
Troubleshooting Guide
GitHub Issues
CHANGELOG

About this skill

What It Does

Prerequisites

Installation

Quick Install with Auto-Authorization

Manual Installation (if auto-auth fails)

Configuration

Access Control Policies

Key Capabilities

1. Message Handling

2. Sending Messages

3. AI Card Streaming

4. Document Operations

5. DING Notifications

6. Todo Management

7. Calendar & Events

8. AI Tables

9. Journal (Reports)

Multi-Agent Routing

Configuration

Agent Definitions

Common Patterns

Pattern 1: Auto-Reply Bot

Pattern 2: Document Search Assistant

Pattern 3: Meeting Scheduler

Pattern 4: Task Tracker Bot

Troubleshooting

Bot Not Responding

Authorization Failed

Message Not Received

Streaming AI Card Not Working

Multi-Agent Routing Issues

Image Upload Fails

Calendar Events Not Creating

Common Error Codes

Testing

Security Notes

Additional Resources