钉钉 OpenClaw 官方连接器

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

English • 更新日志

---

📋 目录

• 前置要求
• 快速开始
• 功能特性
• 配置说明
• 常见问题
• 进阶主题
• 钉钉 DEAP Agent 集成
• 许可证

---

前置要求

开始之前，请确保你已经：

本插件作为 OpenClaw Gateway 插件使用，一般无需你单独安装或管理 Node.js 运行时。

1. OpenClaw Gateway

• 官方网站：https://openclaw.ai/
• 安装说明：按照官方指南安装 OpenClaw
• 验证安装：

  openclaw gateway status
  

  预期输出：✓ Gateway is running on http://127.0.0.1:18789

⚠️ 版本兼容性要求

重要：dingtalk-connector v0.8.4+ 需要 OpenClaw SDK v2026.3.22 或更高版本。

dingtalk-connector 版本	最低 OpenClaw SDK 版本	说明
v0.8.4+	v2026.3.22+	使用新版 SDK API，支持更完善的路由和会话管理
v0.8.3 及以下	v2026.3.x	兼容旧版 SDK

如何检查版本：

# 检查 OpenClaw 版本
openclaw --version

# 检查插件版本
openclaw plugins list

如何升级：

# 升级 OpenClaw 到最新版本
npm install -g openclaw@latest

# 或使用 yarn
yarn global add openclaw@latest

版本不兼容时的表现：

• 插件加载时会显示详细的错误提示
• 提示信息会包含升级命令和降级方案
• 插件会自动停止加载，不影响其他插件

2. 钉钉企业账号

• 你需要一个钉钉企业账号来创建企业内部应用
• 官方网站：https://www.dingtalk.com/

---

快速开始

💡 目标：5 分钟内让你的钉钉机器人运行起来

操作系统支持

• macOS / Linux：使用默认的 Shell 终端（zsh、bash 等）。
• Windows：
  • 推荐使用 PowerShell 或 Windows Terminal。
  • OpenClaw 配置文件路径默认为：C:\Users\\.openclaw\openclaw.json。

下文中出现的 ~/.openclaw/openclaw.json，在 Windows 上等价于以上路径。

步骤 1：安装插件

方法 A：通过 npm 包安装（推荐）

openclaw plugins install @dingtalk-real-ai/dingtalk-connector

方法 B：通过本地源码安装

如果你想对插件进行二次开发，可以先克隆仓库：

# 1. 克隆插件仓库
git clone https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector.git
cd dingtalk-openclaw-connector

# 2. 安装依赖（必需）
npm install

# 3. 以链接模式安装（方便修改代码后实时生效）
openclaw plugins install -l .

方法 C：手动安装

1. 将本仓库下载或复制到 ~/.openclaw/extensions/dingtalk-connector。
2. 确保包含 index.ts、openclaw.plugin.json 和 package.json。
3. 在该目录下运行 npm install 安装依赖。

方法 D：国内网络环境安装（npm 镜像源）

如果你在国内网络环境下执行 openclaw plugins install 时卡在 Installing plugin dependencies... 或出现 npm install failed，可临时为该次安装指定镜像源：

NPM_CONFIG_REGISTRY=https://registry.npmmirror.com openclaw plugins install @dingtalk-real-ai/dingtalk-connector

如果插件已处于半安装状态（例如扩展目录存在但依赖未装全），可进入插件目录手动补装依赖：

cd ~/.openclaw/extensions/dingtalk-connector
rm -rf node_modules package-lock.json
NPM_CONFIG_REGISTRY=https://registry.npmmirror.com npm install

如果希望长期生效，可设置 npm 默认镜像：

npm config set registry https://registry.npmmirror.com

或写入 ~/.npmrc：

registry=https://registry.npmmirror.com

验证安装：

openclaw plugins list

你应该看到 ✓ DingTalk Channel (v0.8.6) - loaded

---

步骤 2：创建钉钉机器人

3.1 创建应用

1. 访问 钉钉开放平台
2. 点击 "应用开发"

3.2 添加机器人能力

1. 在应用详情页，点击 一键创建OpenClaw机器人应用

3.3 获取凭证

1. 完成创建并获取 "凭证与基础信息"
2. 复制你的 AppKey（Client ID）
3. 复制你的 AppSecret（Client Secret）

⚠️ 重要：Client ID和 Client Secret是机器人的唯一凭证。请合理保存。

---

步骤 3：配置 OpenClaw

你有三种方式配置连接器：

方式 A：配置向导（推荐新手使用）

你可以直接复制粘贴下面的命令，在终端中运行配置向导。

openclaw channels add

选择 "DingTalk (钉钉)"，然后按提示输入：

• clientId（AppKey）
• clientSecret（AppSecret）

方式 B：编辑配置文件

编辑配置文件：

• macOS / Linux：~/.openclaw/openclaw.json
• Windows：C:\Users\\.openclaw\openclaw.json

{
  "channels": {
    "dingtalk-connector": {
      "enabled": true,
      "clientId": "dingxxxxxxxxx",
      "clientSecret": "your_app_secret"
    }
  }
}

💡 提示：如果文件已有内容，在 channels 节点下添加 dingtalk-connector 部分即可。

---

步骤 4：重启并测试

# 重启 OpenClaw Gateway
openclaw gateway restart

# 实时查看日志
openclaw logs --follow

测试你的机器人：

1. 打开钉钉 App
2. 在联系人列表中找到你的机器人
3. 发送消息：你好
4. 你应该在 10 秒内收到回复

---

功能特性

✅ 核心功能

• AI Card 流式响应 - 打字机效果，实时流式显示回复
• 会话管理 - 多轮对话，保持上下文
• 会话隔离 - 私聊、群聊、不同群之间会话独立
• 自动会话重置 - 30 分钟无活动后自动开启新会话
• 手动会话重置 - 发送 /new 或 新会话 清空对话历史
• 图片自动上传 - 本地图片路径自动上传到钉钉
• 主动发送消息 - 程序化地向用户或群发送消息
• 富媒体接收 - 接收并处理 JPEG/PNG 图片，传递给视觉模型
• 文件附件提取 - 解析 .docx、.pdf、文本文件和二进制文件
• 音频消息支持 - 发送多种格式的音频消息（mp3、wav、amr、ogg）
• 钉钉文档 API - 创建、追加、搜索和列举钉钉文档
• 多 Agent 路由 - 将多个机器人连接到不同的 Agent，实现专业化服务
• Markdown 表格转换 - 自动将 Markdown 表格转换为钉钉兼容格式