@adongguo/openclaw-dingtalk

v0.1.1

Published

20 days ago

OpenClaw DingTalk channel plugin

0High
0Medium
0Low

adongguo

openclaw dingtalk 钉钉 chatbot ai claude

openclaw-dingtalk

DingTalk (钉钉) channel plugin for OpenClaw.

English | 中文

English

Installation

openclaw plugins install @adongguo/openclaw-dingtalk

Or install via npm:

npm install @adongguo/openclaw-dingtalk

Configuration

Create an enterprise internal application on DingTalk Open Platform
Get your AppKey (ClientID) and AppSecret (ClientSecret) from the Credentials page
Enable Robot capability and select Stream mode
Configure event subscriptions (see below)
Configure the plugin:

Required Steps

Create Application: Go to DingTalk Developer Console → Application Development → Enterprise Internal Development → Create Application
Enable Robot: In your application, go to Application Capabilities → Robot → Enable Robot Configuration → Select Stream mode
Get Credentials: Go to Basic Information → Application Information to get AppKey and AppSecret
Publish Application: Publish the app (at least to test version) to make the bot available

openclaw config set channels.dingtalk.appKey "dingXXXXXXXX"
openclaw config set channels.dingtalk.appSecret "your_app_secret"
openclaw config set channels.dingtalk.enabled true

Configuration Options

channels:
  dingtalk:
    enabled: true
    appKey: "dingXXXXXXXX"
    appSecret: "secret"
    # Robot code (optional, for media download)
    robotCode: "dingXXXXXXXX"
    # Connection mode: "stream" (recommended) or "webhook"
    connectionMode: "stream"
    # DM policy: "pairing" | "open" | "allowlist"
    dmPolicy: "pairing"
    # Group policy: "open" | "allowlist" | "disabled"
    groupPolicy: "allowlist"
    # Require @mention in groups
    requireMention: true
    # Max media size in MB (default: 30)
    mediaMaxMb: 30
    # Render mode for bot replies: "auto" | "raw" | "card"
    renderMode: "auto"

Render Mode

| Mode | Description | |------|-------------| | auto | (Default) Automatically detect: use ActionCard for messages with code blocks or tables, plain text otherwise. | | raw | Always send replies as plain text. Markdown tables are converted to ASCII. | | card | Always send replies as ActionCard with full markdown rendering. |

Features

Stream mode connection (WebSocket-based)
Direct messages and group chats
Message replies
Image and file support (via OpenAPI)
Pairing flow for DM approval
User and group directory lookup (config-based)
ActionCard render mode for markdown rendering

Limitations

No message editing: DingTalk doesn't support editing messages via sessionWebhook
No reactions: Bot API doesn't support message reactions
sessionWebhook expiration: Reply URLs are temporary and expire

FAQ

Bot cannot receive messages

Check the following:

Is Robot capability enabled in your application?
Is Stream mode selected (not HTTP mode)?
Is the application published?
Are the appKey and appSecret correct?

Failed to send messages

Check if sessionWebhook has expired
Verify message format is correct
Ensure bot has necessary permissions

How to clear history / start new conversation

Send /new command in the chat.

Why is the output not streaming

DingTalk API has rate limits. Streaming updates can easily trigger throttling. We use complete-then-send approach for stability.

Cannot find the bot in DingTalk

Ensure the app is published (at least to test version)
Search for the bot name in DingTalk search box
Check if your account is in the app's availability scope

中文

安装

openclaw plugins install @adongguo/openclaw-dingtalk

或通过 npm 安装：

npm install @adongguo/openclaw-dingtalk

配置

在钉钉开放平台创建企业内部应用
在凭证页面获取 AppKey (ClientID) 和 AppSecret (ClientSecret)
开启机器人能力并选择 Stream 模式
配置事件订阅（见下方）
配置插件：

必需步骤

创建应用：进入钉钉开发者后台 → 应用开发 → 企业内部开发 → 创建应用
开启机器人：在应用页面，进入应用功能 → 机器人 → 开启机器人配置 → 选择 Stream 模式
获取凭证：进入基础信息 → 应用信息，获取 AppKey 和 AppSecret
发布应用：发布应用（至少发布到测试版本）使机器人可用

openclaw config set channels.dingtalk.appKey "dingXXXXXXXX"
openclaw config set channels.dingtalk.appSecret "your_app_secret"
openclaw config set channels.dingtalk.enabled true

配置选项

channels:
  dingtalk:
    enabled: true
    appKey: "dingXXXXXXXX"
    appSecret: "secret"
    # 机器人 code（可选，用于媒体下载）
    robotCode: "dingXXXXXXXX"
    # 连接模式: "stream" (推荐) 或 "webhook"
    connectionMode: "stream"
    # 私聊策略: "pairing" | "open" | "allowlist"
    dmPolicy: "pairing"
    # 群聊策略: "open" | "allowlist" | "disabled"
    groupPolicy: "allowlist"
    # 群聊是否需要 @机器人
    requireMention: true
    # 媒体文件最大大小 (MB, 默认 30)
    mediaMaxMb: 30
    # 回复渲染模式: "auto" | "raw" | "card"
    renderMode: "auto"

渲染模式

| 模式 | 说明 | |------|------| | auto | （默认）自动检测：有代码块或表格时用 ActionCard，否则纯文本 | | raw | 始终纯文本，表格转为 ASCII | | card | 始终使用 ActionCard，支持完整 Markdown 渲染 |

功能

Stream 模式连接（基于 WebSocket）
私聊和群聊
消息回复
图片和文件支持（通过 OpenAPI）
私聊配对审批流程
用户和群组目录查询（基于配置）
ActionCard 渲染模式支持 Markdown 渲染

限制

不支持消息编辑：钉钉不支持通过 sessionWebhook 编辑消息
不支持表情回复：机器人 API 不支持消息表情回复
sessionWebhook 过期：回复 URL 是临时的，会过期

常见问题

机器人收不到消息

检查以下配置：

是否在应用中开启了机器人能力？
是否选择了 Stream 模式（而非 HTTP 模式）？
应用是否已发布？
appKey 和 appSecret 是否正确？

发送消息失败

检查 sessionWebhook 是否已过期
验证消息格式是否正确
确保机器人有必要的权限

如何清理历史会话 / 开启新对话

在聊天中发送 /new 命令即可开启新对话。

消息为什么不是流式输出

钉钉 API 有请求频率限制，流式更新消息很容易触发限流。当前采用完整回复后一次性发送的方式，以保证稳定性。

在钉钉里找不到机器人

确保应用已发布（至少发布到测试版本）
在钉钉搜索框中搜索机器人名称
检查应用可用范围是否包含你的账号

License

MIT