dingtalk-openclaw-connector

# DingTalk OpenClaw Connector Skill > Skill by [ara.so](https://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 ```bash 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: ```bash openclaw gateway restart ``` ### Manual Installation (if auto-auth fails) ```bash npm install -g @dingtalk-real-ai/dingtalk-connector ``` Then follow [manual setup guide](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/blob/main/docs/DINGTALK_MANUAL_SETUP.md) to configure credentials. ## Configuration Plugin config is stored in OpenClaw's channel settings. Key environment variables: ```bash # 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: ```typescript // 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: ```typescript // 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:** ```typescript // Agent action { "action": "sendMessage", "params": { "conversationId": "cid_xxx", "content": "Hello from OpenClaw!" } } ``` **Markdown with @mention:** ```typescript { "action": "sendMessage", "params": { "conversationId": "cid_xxx", "content": "## Report\n@user_123 please review", "format": "markdown", "atUsers": ["user_123"] } } ``` **Image Message:** ```typescript { "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: ```typescript // 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:** ```typescript { "action": "createDocument", "params": { "title": "Meeting Notes", "content": "# Agenda\n- Item 1\n- Item 2", "spaceId": "space_xxx" // optional } } ``` **Append to Document:** ```typescript { "action": "appendDocument", "params": { "documentId": "doc_xxx", "content": "\n## New Section\nAdditional notes..." } } ``` **Search Documents:** ```typescript { "action": "searchDocuments", "params": { "keyword": "meeting", "maxResults": 10 } } ``` ### 5. DING Notifications Send high-priority alerts: ```typescript { "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:** ```typescript { "action": "createTodo", "params": { "subject": "Review PR #123", "description": "Check code quality", "dueTime": "2026-05-20T17:00:00Z", "executorIds": ["user_123"] } } ``` **Query Todos:** ```typescript { "action": "getTodos", "params": { "status": "PENDING", // PENDING|DONE "startDate": "2026-05-01", "endDate": "2026-05-31" } } ``` ### 7. Calendar & Events **Create Calendar Event:** ```typescript { "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:** ```typescript { "action": "searchCalendarEvents", "params": { "calendarId": "cal_xxx", "startTime": "2026-05-20T00:00:00+08:00", "endTime": "2026-05-21T00:00:00+08:00" } } ``` **Check Availability:** ```typescript { "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:** ```typescript { "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:** ```typescript { "action": "insertTableRow", "params": { "tableId": "tbl_xxx", "fields": { "Name": "John Doe", "Email": "john@example.com", "Status": "Active" } } } ``` **Query Rows:** ```typescript { "action": "queryTableRows", "params": { "tableId": "tbl_xxx", "filter": { "Status": "Active" }, "maxResults": 50 } } ``` ### 9. Journal (Reports) **Submit Daily Report:** ```typescript { "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:** ```typescript { "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 ```bash # 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 ```yaml # 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](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/blob/main/docs/MULTI_AGENT_SETUP.md). ## Common Patterns ### Pattern 1: Auto-Reply Bot ```typescript // 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