钉钉 (DingTalk) - 阿里巴巴企业通讯接入

钉钉（DingTalk）是阿里巴巴集团推出的企业级通讯与智能办公平台，覆盖超过 2300 万家企业组织，是国内制造业、教育、政务等行业中广泛使用的企业 IM 平台。通过本指南，您可以将 OpenClaw 智能助手接入钉钉，让组织成员在日常办公中直接调用 AI 能力。

适用场景

钉钉接入特别适合以下场景：

中大型企业的日常办公 AI 赋能
制造业、零售业的一线员工智能辅助
学校和教育机构的教学辅助
政务单位的智能问答与业务自动化

什么是钉钉 (DingTalk)

钉钉是阿里巴巴面向企业提供的一站式智能办公平台，核心特性包括：

组织管理：完整的组织架构、角色权限、审批流管理
开放平台：丰富的 API 和小程序 (Mini App) 生态
工作通知：强大的工作通知 (Work Notification) 推送能力，消息必达
交互式卡片：支持丰富的 AI Card（交互式卡片）模板

前提条件

条件	说明
OpenClaw 环境	已安装并初始化（参考快速启动）
钉钉开放平台账号	需要组织管理员在钉钉开放平台注册
组织管理员权限	需要拥有目标组织的管理员权限
公网服务器（回调模式）	如使用 HTTP 回调模式，需要有公网可访问的服务器

步骤一：登录钉钉开放平台

打开钉钉开放平台
使用拥有管理员权限的钉钉账号扫码登录
在顶部导航栏选择目标组织（如果有多个组织）

步骤二：创建企业内部应用

在开放平台首页，点击 应用开发 → 企业内部应用
点击 创建应用 → 选择 H5微应用
填写应用基本信息：

字段	说明	示例
应用名称	展示给组织成员的名称	`OpenClaw 智能助手`
应用描述	简要描述应用功能	`AI 智能助手，高效办公`
应用图标	上传应用图标	OpenClaw 品牌图标
开发方式	选择开发方式	企业内部开发

点击 确认创建

应用类型选择

钉钉开放平台支持多种应用类型（H5 微应用、小程序、机器人等）。对于 OpenClaw 接入，推荐创建 H5微应用，它同时支持消息交互和网页交互，功能最完整。

步骤三：获取 AppKey 和 AppSecret

进入应用详情页，点击左侧菜单的 基础信息 → 应用信息
复制 AppKey（格式如 dingxxxxxxxxxxxxxxxxx）
复制 AppSecret

安全提醒

AppSecret 是应用的核心凭证，请勿将其提交到 Git 仓库或通过即时通讯工具传递。建议通过环境变量 (Environment Variable) 方式管理。

获取 RobotCode

在应用详情页，点击左侧菜单 应用功能 → 消息推送
如果尚未启用机器人功能，先点击启用
复制页面中的 RobotCode（即机器人标识码）

步骤四：配置事件订阅

钉钉通过事件订阅 (Event Subscription) 将用户消息推送给 OpenClaw。

方式一：HTTP 推送模式

在应用详情页，点击 事件与回调 → 事件订阅

点击编辑，在 请求网址 中填写：

https://your-domain.com/api/channels/dingtalk/webhook

钉钉会向此地址发送一个验证请求，OpenClaw Gateway 会自动完成验证
在订阅事件中搜索并勾选以下事件：

事件名称	Event Key	说明
机器人被单聊	`chat_send_single_chat_message`	接收用户私聊消息
机器人被群@	`chat_send_group_chat_message`	接收群聊 @机器人消息

点击保存

方式二：Stream 推送模式（推荐）

钉钉也支持类似 WebSocket 的 Stream 推送模式，无需配置公网地址：

在事件订阅页面，选择推送方式为 Stream 模式
勾选上述事件
保存即可，OpenClaw 插件会自动建立 Stream 连接

步骤五：配置应用权限

在应用详情页，点击 权限管理，搜索并开通以下权限：

权限名称	权限标识	说明
企业内机器人	`qyapi_robot_sendmsg`	允许机器人发送消息
通讯录管理（只读）	`contact_user_readonly`	读取用户基本信息
消息通知	`notify_message`	发送工作通知
群会话管理	`chat_manage`	管理群聊（群机器人场景）
个人信息读取	`personal_info`	读取用户个人信息

权限审批

部分高级权限需要组织管理员审批后才能生效。权限申请后请联系组织管理员在 钉钉管理后台 → 工作台 → 应用管理 中进行审批。

步骤六：安装钉钉插件

npm手动下载

bash

openclaw plugins install @openclaw/dingtalk

bash

# 从 GitHub Release 下载插件包
wget https://github.com/openclaw/plugin-dingtalk/releases/latest/download/dingtalk.tar.gz
openclaw plugins install ./dingtalk.tar.gz

安装完成后验证：

bash

openclaw plugins list
# 输出应包含: @openclaw/dingtalk (v1.x.x) - active

步骤七：配置 OpenClaw

编辑 OpenClaw 配置文件 openclaw.config.json5：

配置文件方式环境变量方式

json5

{
  channels: {
    dingtalk: {
      enabled: true,
      // 从应用基础信息获取
      appKey: "dingxxxxxxxxxxxxxxxxx",
      appSecret: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      // 机器人标识码，从应用功能→消息推送获取
      robotCode: "dingxxxxxxxxxxxxxxxxx",
      // 私聊策略: 组织内部应用建议使用 "open"
      dmPolicy: "open",
      // 推送模式: "stream" (推荐) 或 "http"
      pushMode: "stream"
    }
  }
}

bash

export DINGTALK_APP_KEY="dingxxxxxxxxxxxxxxxxx"
export DINGTALK_APP_SECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export DINGTALK_ROBOT_CODE="dingxxxxxxxxxxxxxxxxx"
export DINGTALK_DM_POLICY="open"
export DINGTALK_PUSH_MODE="stream"

步骤八：启动 Gateway 并验证

bash

openclaw gateway

启动成功日志：

[INFO] DingTalk channel initialized (stream mode)
[INFO] DingTalk stream connection established
[INFO] Gateway listening on :3000
[INFO] Bot ready: OpenClaw 智能助手

步骤九：发布应用

回到钉钉开放平台 → 应用详情页
点击左侧菜单 版本管理与发布
点击 创建新版本，填写版本号和更新说明
点击发布，等待组织管理员审批（自建应用通常自动通过）

发布成功后，组织成员可在钉钉的工作台中看到该应用，也可以直接搜索机器人名称发起对话。

群聊机器人配置

添加机器人到群聊

在钉钉客户端中打开目标群聊
点击右上角 群设置 → 智能群助手 → 添加机器人
选择您创建的 OpenClaw 应用

群聊行为配置

json5

{
  channels: {
    dingtalk: {
      // ... 基础配置 ...
      group: {
        enabled: true,
        // 是否只响应 @机器人 的消息（推荐开启）
        mentionOnly: true,
        // 回复是否引用原消息
        quoteReply: true,
        // 群聊中保持的上下文轮数
        contextRounds: 5
      }
    }
  }
}

@提及说明

在钉钉群聊中，用户必须先 @机器人再输入消息内容，机器人才会接收并响应。这是钉钉平台的机制设计，OpenClaw 默认遵循此规则。

钉钉特色功能

工作通知 (Work Notification)

工作通知是钉钉最强大的消息推送通道，具有消息必达特性（消息会在通知栏弹出、语音播报）。OpenClaw 可以利用此能力主动向员工推送 AI 处理结果和提醒：

json5

{
  channels: {
    dingtalk: {
      // ... 基础配置 ...
      workNotification: {
        enabled: true,
        // 推送目标: "all" 全员 或指定 userId 列表
        target: "all",
        // 每日推送上限（钉钉限制每个应用每天最多推送 500 万条）
        dailyLimit: 100
      }
    }
  }
}

工作通知频率限制

钉钉对工作通知有严格的频率限制：

同一应用对同一用户每天最多 30 条
同一应用每天最多 500 万条（企业级别）
超限后当天不再接收该应用的工作通知

交互式卡片 (AI Card)

钉钉支持功能强大的交互式卡片模板，OpenClaw 可以将 AI 回复以卡片形式展示：

json5

{
  channels: {
    dingtalk: {
      // ... 基础配置 ...
      card: {
        enabled: true,
        // 使用 AI 卡片模板
        useAICard: true,
        // 卡片底部操作按钮
        actions: [
          { label: "继续追问", action: "followup" },
          { label: "复制回答", action: "copy" },
          { label: "标记有用", action: "thumbup" }
        ],
        // 流式输出到卡片（打字机效果）
        streaming: true
      }
    }
  }
}

AI Card 流式输出

钉钉 AI Card 支持流式更新 (Streaming Update)，OpenClaw 在生成回复时可以实时更新卡片内容，呈现类似 ChatGPT 的打字机效果，显著提升用户体验。

酷应用 (Cool App)

钉钉酷应用可以将 OpenClaw 的功能直接嵌入群聊的侧边栏：

在开放平台 → 应用功能 → 酷应用 中启用
配置酷应用页面地址为 OpenClaw Web 界面
成员可在群聊侧边栏直接使用 AI 能力

环境变量参考

环境变量	对应配置项	说明
`DINGTALK_APP_KEY`	`dingtalk.appKey`	应用 AppKey
`DINGTALK_APP_SECRET`	`dingtalk.appSecret`	应用 AppSecret
`DINGTALK_ROBOT_CODE`	`dingtalk.robotCode`	机器人标识码
`DINGTALK_DM_POLICY`	`dingtalk.dmPolicy`	私聊策略：`pairing` 或 `open`
`DINGTALK_PUSH_MODE`	`dingtalk.pushMode`	推送模式：`stream` 或 `http`

常见问题排查

回调地址验证失败（HTTP 模式）

现象：配置事件订阅的请求网址后，提示验证失败

排查步骤：

确认 OpenClaw Gateway 已启动且对公网可访问
确认 URL 使用 HTTPS 协议（钉钉不支持 HTTP）

手动测试回调地址：

bash

curl -X POST https://your-domain.com/api/channels/dingtalk/webhook \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

检查服务器防火墙和安全组是否放通 443 端口

签名验证失败

现象：日志中出现 DingTalk signature verification failed

常见原因：

appSecret 配置不正确
服务器时间与标准时间偏差超过 1 小时
同步服务器时间：
bash
```
ntpdate ntp.aliyun.com
```
1

回调超时

现象：日志中出现 DingTalk callback timeout 警告

钉钉要求回调必须在 3 秒内返回 HTTP 200 响应。如果 AI 模型响应较慢，OpenClaw 会先返回"处理中"的即时回复，待 AI 回复生成后再通过 API 发送完整回复。

json5

{
  channels: {
    dingtalk: {
      // ... 基础配置 ...
      // 回调超时策略
      callbackTimeout: 2500, // 毫秒，预留 500ms 网络延迟
      // 超时时发送的占位消息
      pendingMessage: "🤔 正在思考中，请稍候..."
    }
  }
}

机器人消息发送失败

bash

# 查看详细日志
openclaw gateway --log-level debug

常见错误码：

错误码	说明	解决方案
310000	无效的 AppKey	检查 AppKey 配置
400013	无权限	确认已开通对应权限
430101	发送频率超限	等待限流恢复或降低发送频率
900001	加密/签名错误	检查 AppSecret 配置

钉钉 API 频率限制

API 类型	频率限制	说明
发送普通消息	20 次/秒 (每个机器人)	超限返回 430101 错误码
发送工作通知	每日每用户 30 条上限	按自然日重置
通讯录查询	1500 次/分钟	用于查询用户信息
AccessToken 获取	有效期 7200 秒	OpenClaw 自动管理刷新

重要提醒

钉钉的机器人消息发送频率限制相对严格（20 次/秒），在大规模部署时请确保 OpenClaw 的限流配置正确生效。如需提升配额，可以在钉钉开放平台提交工单申请。

下一步

企业微信接入 - 接入腾讯企业微信
飞书接入 - 接入字节跳动飞书
微信公众号/小程序 - 接入微信生态
多模型调度 - 配置智能模型切换

钉钉 (DingTalk) - 阿里巴巴企业通讯接入 ​

什么是钉钉 (DingTalk) ​

前提条件 ​

步骤一：登录钉钉开放平台 ​

步骤二：创建企业内部应用 ​

步骤三：获取 AppKey 和 AppSecret ​

获取 RobotCode ​

步骤四：配置事件订阅 ​

方式一：HTTP 推送模式 ​

方式二：Stream 推送模式（推荐） ​

步骤五：配置应用权限 ​

步骤六：安装钉钉插件 ​

步骤七：配置 OpenClaw ​

步骤八：启动 Gateway 并验证 ​

步骤九：发布应用 ​

群聊机器人配置 ​

添加机器人到群聊 ​

群聊行为配置 ​

钉钉特色功能 ​

工作通知 (Work Notification) ​

交互式卡片 (AI Card) ​

酷应用 (Cool App) ​

环境变量参考 ​

常见问题排查 ​

回调地址验证失败（HTTP 模式） ​

签名验证失败 ​

回调超时 ​

机器人消息发送失败 ​

钉钉 API 频率限制 ​

下一步 ​

钉钉 (DingTalk) - 阿里巴巴企业通讯接入

什么是钉钉 (DingTalk)

前提条件

步骤一：登录钉钉开放平台

步骤二：创建企业内部应用

步骤三：获取 AppKey 和 AppSecret

获取 RobotCode

步骤四：配置事件订阅

方式一：HTTP 推送模式

方式二：Stream 推送模式（推荐）

步骤五：配置应用权限

步骤六：安装钉钉插件

步骤七：配置 OpenClaw

步骤八：启动 Gateway 并验证

步骤九：发布应用

群聊机器人配置

添加机器人到群聊

群聊行为配置

钉钉特色功能

工作通知 (Work Notification)

交互式卡片 (AI Card)

酷应用 (Cool App)

环境变量参考

常见问题排查

回调地址验证失败（HTTP 模式）

签名验证失败

回调超时

机器人消息发送失败

钉钉 API 频率限制

下一步