@dingtalk-real-ai/dingtalk-connector

v0.7.10

Published

11 hours ago

DingTalk (钉钉) channel connector — Stream mode with AI Card streaming

0High
0Medium
0Low

xiadongxiang

hotspring.myw26

dingtalk channel stream ai-card connector

Offical DingTalk OpenClaw Connector

钉钉官方OpenClaw连接器

以下提供两种方案连接到 OpenClaw Gateway，分别是钉钉机器人和钉钉 DEAP Agent。

📝 版本信息：当前版本 v0.7.10 | 查看变更日志 | 发布说明 | 发布指南

快速导航

| 方案 | 名称 | 详情 | |------|------|------| | 方案一 | 钉钉机器人集成 | 查看详情 | | 方案二 | 钉钉 DEAP Agent 集成 | 查看详情 |

方案一：钉钉机器人集成

将钉钉机器人连接到 OpenClaw Gateway，支持 AI Card 流式响应和会话管理。

特性

✅ AI Card 流式响应 - 打字机效果，实时显示 AI 回复
✅ 会话持久化 - 同一用户的多轮对话共享上下文
✅ 会话与记忆隔离 - 按单聊/群聊/群区分 session，不同场景下的对话上下文互不干扰，可配置跨会话记忆共享
✅ 超时自动新会话 - 默认 30 分钟无活动自动开启新对话
✅ 手动新会话 - 发送 /new 或 新会话 清空对话历史
✅ 图片自动上传 - 本地图片路径自动上传到钉钉
✅ 主动发送消息 - 支持主动给钉钉个人或群发送消息
✅ 富媒体接收 - 支持接收 JPEG/PNG 图片消息，自动下载并传递给视觉模型
✅ 文件附件提取 - 支持解析 .docx、.pdf、纯文本文件（.txt、.md、.json 等）和二进制文件（.xlsx、.pptx、.zip 等）
✅ 音频消息支持 - 支持发送音频消息，支持多种格式（mp3、wav、amr、ogg），自动提取音频时长，支持通过标记或文件附件方式发送
✅ 钉钉文档 API - 支持创建、追加、搜索、列举钉钉文档
✅ 多 Agent 路由 - 支持一个连接器实例连接多个 Agent，多个钉钉机器人可分别绑定到不同 Agent，实现角色分工和专业化服务
✅ Markdown 表格转换 - 自动将 Markdown 表格转换为钉钉支持的文本格式，提升消息可读性
✅ 异步模式 - 立即回执用户消息，后台处理任务，然后主动推送最终结果作为独立消息（可选）

架构

graph LR
    subgraph "钉钉"
        A["用户发消息"] --> B["Stream WebSocket"]
        E["AI 流式卡片"] --> F["用户看到回复"]
    end

    subgraph "Connector"
        B --> C["消息处理器"]
        C -->|"HTTP SSE"| D["Gateway /v1/chat/completions"]
        D -->|"流式 chunk"| C
        C -->|"streaming API"| E
    end

效果

安装

1. 安装插件

# 通过 npm 安装（推荐）
openclaw plugins install @dingtalk-real-ai/dingtalk-connector

# 或通过 Git 安装
openclaw plugins install https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector.git

# 升级插件
openclaw plugins update dingtalk-connector

# 或本地开发模式
git clone https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector.git
cd dingtalk-openclaw-connector
npm install
openclaw plugins install -l .

⚠️ 旧版本升级提示： 如果你之前安装过旧版本的 Clawdbot/Moltbot 或 0.4.0 以下版本的 connector 插件，可能会出现兼容性问题，请参考 Q: 升级后出现插件加载异常或配置不生效。

2. 配置

在 ~/.openclaw/openclaw.json 中添加：

{
  "channels": {
    "dingtalk-connector": {
      "enabled": true,
      "gatewayBaseUrl": "http://localhost:18789", // 可选：如果Gateway地址是TLS/HTTPS，see PR #117
      "clientId": "dingxxxxxxxxx",       // 钉钉 AppKey
      "clientSecret": "your_secret_here", // 钉钉 AppSecret
      "gatewayToken": "",                 // 可选：Gateway 认证 token, openclaw.json配置中 gateway.auth.token 的值 
      "gatewayPassword": "",              // 可选：Gateway 认证 password（与 token 二选一）
      "sessionTimeout": 1800000,          // ⚠️ 已废弃，请使用 Gateway 的 session.reset.idleMinutes 配置
      "separateSessionByConversation": true,  // 可选：是否按单聊/群聊/群区分 session（默认：true）
      "groupSessionScope": "group",       // 可选：群聊会话隔离策略，group=群共享，group_sender=群内用户独立（默认：group）
      "sharedMemoryAcrossConversations": false, // 可选：是否在不同会话间共享记忆；false 时群聊与私聊、不同群记忆隔离（默认：false）
      "asyncMode": false,                 // 可选：异步模式，立即回执用户消息，后台处理并推送结果（默认：false）
      "ackText": "🫡 任务已接收"      // 可选：异步模式下的回执消息文本（默认：'🫡 任务已接收，处理中...'）
    }
  }
}

执行配置命令

openclaw config set gateway.http.endpoints.chatCompletions.enabled true

或者在 OpenClaw Dashboard 页面配置：

3. 重启 Gateway

openclaw gateway restart

验证：

openclaw plugins list  # 确认 dingtalk-connector 已加载

创建钉钉机器人

打开钉钉开放平台
进入 应用开发 → 企业内部开发 → 创建openclaw机器人
创建好机器人后，保存一下生成的clientId和clientSecret, 后续配置参数需要
或者在机器人详情中也可以拿到

配置参考

| 配置项 | 环境变量 | 说明 | |--------|----------|------| | clientId | DINGTALK_CLIENT_ID | 上一步创建openclaw机器人给到的 clinetId | | clientSecret | DINGTALK_CLIENT_SECRET | 上一步创建openclaw机器人给到的 clientSecret | | gatewayToken | OPENCLAW_GATEWAY_TOKEN | Gateway 认证 token（可选） | | gatewayPassword | — | Gateway 认证 password（可选，与 token 二选一） | | sessionTimeout | — | ⚠️ 已废弃，请使用 Gateway 的 session.reset.idleMinutes 配置 | | separateSessionByConversation | — | 是否按单聊/群聊/群区分 session（默认：true） | | groupSessionScope | — | 群聊会话隔离策略（仅当 separateSessionByConversation=true 时生效）：group=群共享，group_sender=群内用户独立（默认：group） | | sharedMemoryAcrossConversations | — | 是否在不同会话间共享记忆；false 时群聊与私聊、不同群记忆隔离（默认：false） | | asyncMode | — | 异步模式，立即回执用户消息，后台处理并推送结果（默认：false） | | ackText | — | 异步模式下的回执消息文本（默认：'🫡 任务已接收，处理中...'） |

会话与记忆隔离

连接器支持按单聊、群聊、不同群分别维护独立会话和记忆，确保同一用户在不同场景下的对话上下文互不干扰。

会话隔离（separateSessionByConversation）

默认开启（true）：单聊、群聊、不同群各自拥有独立的 session
关闭（false）：按用户维度维护 session，不区分单聊/群聊（兼容旧行为）

群聊会话隔离（groupSessionScope）

仅当 separateSessionByConversation=true 时生效：

group（默认）：整个群共享一个会话，群内所有用户共用同一个对话上下文
group_sender：群内每个用户独立会话，不同用户的对话上下文互不干扰

记忆隔离（sharedMemoryAcrossConversations）

默认关闭（false）：不同群聊、群聊与私聊之间的记忆隔离，AI 不会混淆不同场景下的对话历史
开启（true）：单 Agent 场景下，同一用户在不同会话间共享记忆

适用场景

✅ 同一机器人在多个群中服务，希望每个群的对话互不干扰
✅ 用户既在私聊也在群聊中使用机器人，希望私聊与群聊上下文分离
✅ 群内所有成员共享对话上下文（默认 groupSessionScope: "group"）
✅ 群内每个用户独立对话（设置 groupSessionScope: "group_sender"）
✅ 需要跨会话共享记忆时，可设置 sharedMemoryAcrossConversations: true

异步模式

异步模式允许连接器立即回执用户消息，然后在后台处理任务，最后主动推送最终结果作为独立消息。这种模式特别适合处理耗时较长的任务，可以给用户更好的交互体验。

启用异步模式

在配置中设置 asyncMode: true：

{
  "channels": {
    "dingtalk-connector": {
      "enabled": true,
      "clientId": "dingxxxxxxxxx",
      "clientSecret": "your_secret_here",
      "asyncMode": true,              // 启用异步模式
      "ackText": "🫡 任务已接收"  // 可选：自定义回执消息
    }
  }
}

工作流程

立即回执 - 用户发送消息后，连接器立即发送回执消息（默认：🫡 任务已接收，处理中...）
后台处理 - 连接器在后台调用 Gateway 处理任务，支持文件附件和图片
推送结果 - 处理完成后，连接器主动推送最终结果作为独立消息

适用场景

✅ 处理耗时较长的任务（如文档分析、代码生成等）
✅ 需要给用户即时反馈的场景
✅ 希望将处理过程和结果分离的场景

注意事项

异步模式下不支持 AI Card 流式响应（因为结果通过主动推送发送）
异步模式支持文件附件和图片处理
错误信息也会通过主动推送发送给用户

多 Agent 配置

钉钉 Connector 支持多 Agent 模式，可以配置多个钉钉机器人连接到不同的 Agent，实现角色分工和专业化服务。

核心配置

在 ~/.openclaw/openclaw.json 中配置多个钉钉账号和 Agent 绑定：

{
  "channels": {
    "dingtalk-connector": {
      "enabled": true,
      "accounts": {
        "bot1": {
          "enabled": true,
          "clientId": "ding_bot1_app_key",
          "clientSecret": "bot1_secret"
        },
        "bot2": {
          "enabled": true,
          "clientId": "ding_bot2_app_key",
          "clientSecret": "bot2_secret"
        }
      }
    }
  },
  "bindings": [
    {
      "agentId": "ding-bot1",
      "match": {
        "channel": "dingtalk-connector",
        "accountId": "bot1"
      }
    },
    {
      "agentId": "ding-bot2",
      "match": {
        "channel": "dingtalk-connector",
        "accountId": "bot2"
      }
    }
  ]
}

基于单聊/群聊的路由（peer.kind）

连接器支持根据会话类型（单聊/群聊）将消息路由到不同的 Agent。这对于以下场景非常有用：

安全隔离：群聊使用受限功能的 Agent，单聊使用完整功能的 Agent
多角色支持：不同用户或会话类型分配不同的 Agent
成本优化：普通用户路由到低成本模型，VIP 用户使用高端模型

配置示例

{
  "bindings": [
    // 场景1：特定用户的单聊 → main agent（完整功能）
    {
      "agentId": "main",
      "match": {
        "channel": "dingtalk-connector",
        "peer": {
          "kind": "direct",
          "id": "YOUR_VIP_USER_ID"
        }
      }
    },
    // 场景2：所有群聊 → guest agent（受限功能）
    {
      "agentId": "guest",
      "match": {
        "channel": "dingtalk-connector",
        "peer": {
          "kind": "group",
          "id": "*"
        }
      }
    },
    // 场景3：其他单聊 → guest agent（受限功能）
    {
      "agentId": "guest",
      "match": {
        "channel": "dingtalk-connector",
        "peer": {
          "kind": "direct",
          "id": "*"
        }
      }
    }
  ]
}

peer.kind 配置说明

| 字段 | 类型 | 说明 | |------|------|------| | peer.kind | 'direct' | 'group' | 会话类型：direct 表示单聊，group 表示群聊 | | peer.id | string | 发送者 ID（单聊）或 * 通配符匹配所有 |

匹配优先级

bindings 按以下优先级匹配（从高到低）：

peer.kind + peer.id 精确匹配：指定会话类型和具体用户 ID
peer.kind + peer.id='*' 通配匹配：指定会话类型，匹配所有用户
仅 peer.kind 匹配：只指定会话类型（无 peer.id）
accountId 匹配：按钉钉账号路由
channel 匹配：仅指定 channel
默认 fallback：使用 main agent

官方文档

详细的配置指南和架构说明，请参考 OpenClaw 官方文档：

OpenClaw 多 Agent 架构配置指南

会话命令

用户可以发送以下命令开启新会话（清空对话历史）：

/new、/reset、/clear
新会话、重新开始、清空对话

富媒体接收

图片消息支持

连接器支持接收和处理钉钉中的图片消息：

JPEG 图片 - 直接发送的 JPEG 图片会自动下载到 ~/.openclaw/workspace/media/inbound/ 目录
PNG 图片 - 富文本消息中包含的 PNG 图片会自动提取 URL 和 downloadCode 并下载
视觉模型集成 - 下载的图片会自动传递给视觉模型，AI 可以识别和分析图片内容

媒体文件存储

所有接收的媒体文件会保存在：

~/.openclaw/workspace/media/inbound/

文件命名格式：openclaw-media-{timestamp}.{ext}

查看媒体目录：

ls -la ~/.openclaw/workspace/media/inbound/

文件附件提取

连接器支持自动提取和处理钉钉消息中的文件附件：

支持的文件类型

| 文件类型 | 处理方式 | 说明 | |---------|---------|------| | .docx | 通过 mammoth 解析 | 提取 Word 文档中的文本内容，注入到 AI 上下文 | | .pdf | 通过 pdf-parse 解析 | 提取 PDF 文档中的文本内容，注入到 AI 上下文 | | .txt、.md、.json 等 | 直接读取 | 纯文本文件内容直接读取并注入到消息中 | | .xlsx、.pptx、.zip 等 | 保存到磁盘 | 二进制文件保存到磁盘，文件路径和名称会在消息中报告 |

使用方式

直接在钉钉中发送文件附件，连接器会自动：

下载文件到本地
根据文件类型进行解析或保存
将文本内容注入到 AI 对话上下文中

钉钉文档 API

连接器提供了丰富的钉钉文档操作能力，可在 OpenClaw Agent 中调用：

创建文档

dingtalk-connector.docs.create({
  spaceId: "your-space-id",
  title: "测试文档",
  content: "# 测试内容"
})

追加内容

dingtalk-connector.docs.append({
  docId: "your-doc-id",
  markdownContent: "\n## 追加的内容"
})

搜索文档

dingtalk-connector.docs.search({
  keyword: "搜索关键词"
})

列举文档

dingtalk-connector.docs.list({
  spaceId: "your-space-id"
})

多 Agent 路由支持

连接器支持同时连接多个 Agent，实现多 Agent 会话隔离：

独立会话空间 - 每个 Agent 拥有独立的会话上下文，互不干扰
灵活路由 - 可根据不同场景将请求路由到不同的 Agent
向后兼容 - 单 Agent 场景下功能完全兼容，无需额外配置

项目结构

dingtalk-openclaw-connector/
├── plugin.ts              # 插件入口
├── openclaw.plugin.json   # 插件清单
├── package.json           # npm 依赖
└── LICENSE

常见问题

Q: 出现 405 错误

需要在 ~/.openclaw/openclaw.json 中启用 chatCompletions 端点：

{
  "gateway": { // gateway通常是已有的节点，配置时注意把http部分追加到已有节点下
    "http": {
      "endpoints": {
        "chatCompletions": {
          "enabled": true
        }
      }
    }
  }
}

Q: 出现 401 错误

检查 ~/.openclaw/openclaw.json 中的gateway.auth鉴权的 token/password 是否正确：

Q: 钉钉机器人无响应

确认 Gateway 正在运行：curl http://127.0.0.1:18789/health
确认机器人配置为 Stream 模式（非 Webhook）
确认 AppKey/AppSecret 正确

Q: AI Card 不显示，只有纯文本

需要开通权限 Card.Streaming.Write 和 Card.Instance.Write，并重新发布应用。

Q: 升级后出现插件加载异常或配置不生效

由于官方两次更名（Clawdbot → Moltbot → OpenClaw），旧版本（0.4.0 以下）的 connector 插件可能与新版本不兼容。建议按以下步骤处理：

先检查 ~/.openclaw/openclaw.json（或旧版的 ~/.clawdbot/clawdbot.json、~/.moltbot/moltbot.json），如果其中存在 dingtalk 相关的 JSON 节点（如 channels.dingtalk、plugins.entries.dingtalk 等），请将这些节点全部删除。
然后清除旧插件并重新安装：

rm -rf ~/.clawdbot/extensions/dingtalk-connector
rm -rf ~/.moltbot/extensions/dingtalk-connector
rm -rf ~/.openclaw/extensions/dingtalk-connector
openclaw plugins install @dingtalk-real-ai/dingtalk-connector

Q: 图片不显示

确认 enableMediaUpload: true（默认开启）
检查日志 [DingTalk][Media] 相关输出
确认钉钉应用有图片上传权限

Q: 图片消息无法识别

检查图片是否成功下载到 ~/.openclaw/workspace/media/inbound/ 目录
确认 Gateway 配置的模型支持视觉能力（vision model）
查看日志中是否有图片下载或处理的错误信息

Q: 文件附件无法解析

Word 文档（.docx）：确认已安装 mammoth 依赖包
PDF 文档：确认已安装 pdf-parse 依赖包
检查文件是否成功下载，查看日志中的文件处理信息
对于不支持的二进制文件，会保存到磁盘并在消息中报告文件路径

Q: 钉钉文档 API 调用失败

确认钉钉应用已开通文档相关权限
检查 spaceId、docId 等参数是否正确
确认 API 调用时的认证信息（AppKey/AppSecret）有效
注意：读取文档功能需要 MCP 提供相应的 tool，当前版本暂不支持

Q: 多 Agent 路由如何配置

多 Agent 路由功能会自动处理，无需额外配置。连接器会根据配置自动管理多个 Agent 的会话隔离。如需自定义路由逻辑，请参考插件源码中的路由实现。

依赖

| 包 | 用途 | |----|------| | dingtalk-stream | 钉钉 Stream 协议客户端 | | axios | HTTP 客户端 | | mammoth | Word 文档（.docx）解析 | | pdf-parse | PDF 文档解析 |

Q: Stream 客户端连接 400 错误

日志中出现 channel exited: Request failed with status code 400，表示钉钉 Stream 连接失败。

常见原因：

| 原因 | 排查方法 | |------|----------| | 应用未发布 | 钉钉开放平台 → 应用 → 版本管理 → 确认已发布 | | 凭证错误 | 检查 clientId/clientSecret 是否有空格或换行 | | 非 Stream 模式 | 确认机器人消息接收模式为 Stream 模式 | | IP 白名单限制 | 检查应用是否设置了 IP 白名单 |

排查步骤：

验证凭证有效性

curl -X POST "https://api.dingtalk.com/v1.0/oauth2/accessToken" \
  -H "Content-Type: application/json" \
  -d '{"appKey": "你的clientId", "appSecret": "你的clientSecret"}'

返回 accessToken → 凭证正确
返回 400/invalid → 凭证错误或应用未发布

检查应用状态
- 登录钉钉开放平台
- 确认应用已发布（版本管理 → 发布）
- 确认机器人已启用且为 Stream 模式
重新发布应用
- 修改任何配置后，必须点击保存 → 发布

方案二：钉钉 DEAP Agent 集成

通过将钉钉 DEAP Agent 与 OpenClaw Gateway 连接，实现自然语言驱动的本地设备操作能力。

核心功能

✅ 自然语言交互 - 用户在钉钉对话框中输入自然语言指令（如"帮我查找桌面上的 PDF 文件"），Agent 将自动解析并执行相应操作
✅ 内网穿透机制 - 专为本地设备无公网 IP 场景设计，通过 Connector 客户端建立稳定的内外网通信隧道
✅ 跨平台兼容 - 提供 Windows、macOS 和 Linux 系统的原生二进制执行文件，确保各平台下的顺畅运行

系统架构

该方案采用分层架构模式，包含三个核心组件：

OpenClaw Gateway - 部署于本地设备，提供标准化 HTTP 接口，负责接收并处理来自云端的操作指令，调动 OpenClaw 引擎执行具体任务
DingTalk OpenClaw Connector - 运行于本地环境，构建本地与云端的通信隧道，解决内网设备无公网 IP 的问题
DingTalk DEAP MCP - 作为 DEAP Agent 的扩展能力模块，负责将用户自然语言请求经由云端隧道转发至 OpenClaw Gateway

graph LR
    subgraph "钉钉 App"
        A["用户与 Agent 对话"] --> B["DEAP Agent"]
    end
    
    subgraph "本地环境"
        D["DingTalk OpenClaw Connector"] --> C["OpenClaw Gateway"]
        C --> E["PC 操作执行"]
    end
    
    B -.-> D

实施指南

第一步：部署本地环境

确认本地设备已成功安装并启动 OpenClaw Gateway，默认监听地址为 127.0.0.1:18789：

openclaw gateway start

配置 Gateway 参数

访问配置页面
在 Auth 标签页 中设置 Gateway Token 并妥善保存：
切换至 Http 标签页，启用 OpenAI Chat Completions Endpoint 功能：
点击右上角 Save 按钮完成配置保存

第二步：获取必要参数

获取 corpId

登录钉钉开发者平台查看企业 CorpId：

获取 apiKey

登录钉钉 DEAP 平台，在 安全与权限 → API-Key 管理 页面创建新的 API Key：

第三步：启动 Connector 客户端

从 Releases 页面下载适配您操作系统的安装包

解压并运行 Connector（以 macOS 为例）：

unzip connector-mac.zip
./connector-darwin -deapCorpId YOUR_CORP_ID -deapApiKey YOUR_API_KEY

第四步：配置 DEAP Agent

登录钉钉 DEAP 平台，创建新的智能体：
在技能管理页面，搜索并集成 OpenClaw 技能：
配置技能参数：
| 参数 | 来源 | 说明 | |------|------|------| | apikey | 第二步获取 | DEAP 平台 API Key | | apihost | 默认值 | 通常为 127.0.0.1:18789，在Windows环境下可能需要配置为 localhost:18789 才能正常工作 | | gatewayToken | 第一步获取 | Gateway 配置的认证令牌 |

注意 OpenClaw 属于一个MCP，还需要配置他的触发规则，满足规则的情况下才会使用这个MCP:

发布 Agent：

第五步：开始使用

在钉钉 App 中搜索并找到您创建的 Agent：
开始自然语言对话体验：

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Offical DingTalk OpenClaw Connector

钉钉官方OpenClaw连接器

快速导航

方案一：钉钉机器人集成

特性

架构

效果

安装

1. 安装插件

2. 配置

3. 重启 Gateway

创建钉钉机器人

配置参考

会话与记忆隔离

会话隔离（separateSessionByConversation）

群聊会话隔离（groupSessionScope）

记忆隔离（sharedMemoryAcrossConversations）

适用场景

异步模式

启用异步模式

工作流程

适用场景

注意事项

多 Agent 配置

核心配置

基于单聊/群聊的路由（peer.kind）

配置示例

peer.kind 配置说明

匹配优先级

官方文档

会话命令

富媒体接收

图片消息支持

媒体文件存储

文件附件提取

支持的文件类型

使用方式

钉钉文档 API

创建文档

追加内容

搜索文档

列举文档

多 Agent 路由支持

项目结构

常见问题

Q: 出现 405 错误

Q: 出现 401 错误

Q: 钉钉机器人无响应

Q: AI Card 不显示，只有纯文本

Q: 升级后出现插件加载异常或配置不生效

Q: 图片不显示

Q: 图片消息无法识别

Q: 文件附件无法解析

Q: 钉钉文档 API 调用失败

Q: 多 Agent 路由如何配置

依赖

Q: Stream 客户端连接 400 错误

方案二：钉钉 DEAP Agent 集成

核心功能

系统架构

实施指南

第一步：部署本地环境

配置 Gateway 参数

第二步：获取必要参数

获取 corpId

获取 apiKey

第三步：启动 Connector 客户端

第四步：配置 DEAP Agent

第五步：开始使用

License