OpenClaw 钉钉（DingTalk）渠道
企业平台
中等
通过社区插件将 OpenClaw 连接到钉钉（DingTalk）。此集成使用钉钉 Stream 模式（WebSocket 长连接），无需公网 IP 或域名。支持私聊、群聊、文本/图片/语音/视频/文件等消息类型，以及 AI Card 流式回复。安装插件、创建钉钉企业内部应用、填入凭证即可启动。
快速信息
难度中等
分类企业平台
支持功能数4 / 6
DingTalk 支持的功能
文本消息
支持
媒体与文件
支持
消息反应
不支持
消息线程
不支持
语音消息
支持
群聊
支持
DingTalk 前置条件
- 拥有钉钉组织管理员权限或应用开发权限
- 已安装钉钉插件：openclaw plugins install @soimy/dingtalk
- OpenClaw Gateway 已运行并配置
- 服务器已安装 Node.js 18+
DingTalk 快速设置
1
安装钉钉插件
在终端中运行 'openclaw plugins install @soimy/dingtalk' 安装社区钉钉插件。如需流式 AI Card 回复，也可选择 '@dingtalk-real-ai/dingtalk-connector' 插件。
2
创建钉钉企业内部应用
登录钉钉开放平台（open-dev.dingtalk.com），创建企业内部应用。在应用凭证页面获取 ClientID（AppKey）和 ClientSecret（AppSecret）。在应用能力中添加「机器人」能力，消息接收模式选择 Stream 模式。
3
配置权限并发布
在权限管理中授予所需权限：Card.Instance.Write、Card.Streaming.Write、机器人消息发送、媒体文件上传等。完成后发布应用，等待审批通过。
4
配置 OpenClaw 并测试
在 ~/.openclaw/openclaw.json 中添加钉钉渠道配置，填入 clientId 和 clientSecret。运行 'openclaw gateway restart' 重启 Gateway，在钉钉中向机器人发送消息测试。
DingTalk 配置示例
config.json
{
"channels": {
"dingtalk": {
"enabled": true,
"clientId": "dingXXXXXX",
"clientSecret": "your-app-secret",
"robotCode": "dingXXXXXX",
"corpId": "dingXXXXXX",
"dmPolicy": "open",
"groupPolicy": "open",
"messageType": "markdown"
}
}
}DingTalk 集成详解
架构概述
OpenClaw 通过钉钉开放平台的 Stream 模式（WebSocket 长连接）连接钉钉。与传统 Webhook 不同，Stream 模式由 Gateway 主动向钉钉服务器发起 WebSocket 连接，实时接收事件推送，无需公网 IP 或域名。
消息流程：用户在钉钉中发送消息 → 钉钉开放平台 → Stream 推送至 Gateway → OpenClaw 使用 AI 处理 → 通过钉钉 Bot API 回复 → 消息在钉钉中送达。
此架构适合在 NAT 或企业防火墙后的自托管部署，Gateway 自动维护连接并处理断线重连（指数退避策略）。
Stream 模式无需公网 IP、无需 SSL 证书，可在企业内网和家庭网络中正常工作。
钉钉插件为社区维护，与 OpenClaw 核心分离安装，保持 Gateway 轻量。
插件选择
钉钉接入有两个主流社区插件可选：
• @soimy/dingtalk — 最流行的插件，社区活跃维护。支持 Markdown 和 AI Card 两种回复格式，功能全面稳定。
• @dingtalk-real-ai/dingtalk-connector — 钉钉官方关联项目，专注 AI Card 流式回复，支持多 Agent 路由和异步模式，要求 OpenClaw v0.7.7+。
两个插件都使用 Stream 模式连接，核心体验一致。选择建议：新手用 @soimy 版本（资料更多），需要多 Agent 或异步处理的用 @dingtalk-real-ai 版本。
terminal
# 安装 @soimy 版本（推荐）
openclaw plugins install @soimy/dingtalk
# 或安装 @dingtalk-real-ai 版本
openclaw plugins install @dingtalk-real-ai/dingtalk-connector钉钉应用创建与凭证获取
设置钉钉集成需要在钉钉开放平台创建应用：
1. 登录钉钉开放平台 open-dev.dingtalk.com，进入开发者后台。
2. 点击「创建应用」，选择「企业内部开发」→「机器人」类型。
3. 填写应用名称和描述，创建完成后在「凭证与基本信息」页面复制 ClientID（即 AppKey，格式 dingXXX）和 ClientSecret（即 AppSecret）。
4. 在「机器人配置」中，消息接收模式选择 **Stream 模式**（非 HTTP 模式）。
5. 在权限管理中添加所需权限，关键权限包括：
- qyapi_robot_sendmsg（机器人发送消息）
- Card.Instance.Write（卡片实例写入）
- Card.Streaming.Write（流式卡片写入）
- mediaId.download 和 mediaId.upload（媒体文件上传下载）
6. 发布应用，等待组织管理员审批通过。
terminal
# 通过环境变量
export DINGTALK_CLIENT_ID="dingXXXXXX"
export DINGTALK_CLIENT_SECRET="your_app_secret"
# 或通过 CLI
openclaw channels add请妥善保管 ClientSecret。切勿将其提交到版本控制系统。生产环境请使用环境变量。如果泄露，请立即在钉钉开放平台控制台重置。
私聊与群聊策略
钉钉插件支持灵活的消息策略配置：
**私聊策略（dmPolicy）**：
• open — 任何人私聊机器人都能获得回复
• disabled — 关闭私聊功能
**群聊策略（groupPolicy）**：
• open — 群内任何成员 @机器人即可触发回复
• disabled — 完全忽略群聊消息
群聊中默认需要 @机器人才触发回复，避免在活跃群聊中回复每条消息。
openclaw.json
{
"channels": {
"dingtalk": {
"dmPolicy": "open",
"groupPolicy": "open"
}
}
}群聊中 @机器人名称即可触发，无需额外配置。
会话隔离按对话维度，不同聊天有独立的上下文。30 分钟不活跃自动重置会话。
回复格式与 AI Card 流式输出
钉钉插件支持多种回复格式：
• **文本（text）** — 最基础的纯文本回复
• **Markdown** — 支持标题、列表、链接等格式化内容，默认推荐
• **AI Card（流式）** — 类似 ChatGPT 的打字机效果，消息在卡片中逐步更新
AI Card 流式输出提供最佳用户体验，消息原地更新不会产生多条消息。需要在钉钉应用中授予 Card 相关权限。
openclaw.json
{
"channels": {
"dingtalk": {
"messageType": "markdown",
"streaming": true
}
}
}AI Card 流式输出需要授予 Card.Instance.Write 和 Card.Streaming.Write 权限。
如果不需要流式效果，可将 messageType 设为 markdown 并关闭 streaming。
消息类型与媒体支持
OpenClaw 钉钉插件处理多种消息类型：
**接收支持**：文本、图片、语音（自动语音识别）、视频、文件
**文件解析**：.docx、.pdf、.txt、.md、.json、.xlsx、.pptx、.zip 等格式可被 AI 读取和分析
**发送支持**：文本、Markdown、AI Card、图片、文件
语音消息会自动转为文字后传给 AI 处理，无需额外配置。
发送大文件前确保钉钉应用已授予媒体上传权限。
语音消息自动识别为文字，支持中英文。
多 Agent 路由
使用 @dingtalk-real-ai 版本的插件可以配置多 Agent 路由，让不同的 AI Agent 处理不同类型的对话。例如，私聊走通用助手，特定群聊走专业领域 Agent。
通过 OpenClaw 的 bindings 配置，可以精细控制每个对话的 Agent 分配。
openclaw.json
{
"bindings": [
{ "agentId": "main", "match": { "channel": "dingtalk", "peer": { "kind": "direct" } } },
{ "agentId": "tech-support", "match": { "channel": "dingtalk", "peer": { "kind": "group" } } }
]
}多 Agent 路由仅 @dingtalk-real-ai 版本支持，@soimy 版本暂不支持。
常用命令
OpenClaw 提供多个命令来管理钉钉机器人：
• openclaw gateway status — 检查 Gateway 连接状态
• openclaw gateway restart — 重启 Gateway 服务
• openclaw logs --follow — 查看实时日志
• openclaw channels add — 交互式添加渠道
• openclaw plugins list — 查看已安装插件
• openclaw plugins update @soimy/dingtalk — 更新钉钉插件
• openclaw doctor — 综合诊断
DingTalk 配置参考
| Key | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | true | 启用或禁用钉钉渠道 |
| clientId | string | "" | 钉钉应用的 ClientID（AppKey），格式 dingXXX，从钉钉开放平台获取 |
| clientSecret | string | "" | 钉钉应用的 ClientSecret（AppSecret），从钉钉开放平台获取 |
| robotCode | string | "" | 机器人的唯一标识码，从钉钉开放平台的机器人配置页获取 |
| corpId | string | "" | 企业的 CorpId，格式 dingXXX，从钉钉管理后台获取 |
| agentId | string | "" | 应用的 AgentId，从钉钉开放平台获取 |
| dmPolicy | string | "open" | 私聊策略。选项：open（开放）、disabled（禁用） |
| groupPolicy | string | "open" | 群聊策略。选项：open（开放）、disabled（禁用） |
| messageType | string | "markdown" | 回复消息格式。选项：text（纯文本）、markdown、card（AI Card） |
| streaming | boolean | true | 启用 AI Card 流式回复（打字机效果） |
| debug | boolean | false | 开启调试模式，输出详细的连接和消息日志 |
enabled
Type: booleanDefault: true
启用或禁用钉钉渠道
clientId
Type: stringDefault: ""
钉钉应用的 ClientID（AppKey），格式 dingXXX，从钉钉开放平台获取
clientSecret
Type: stringDefault: ""
钉钉应用的 ClientSecret（AppSecret），从钉钉开放平台获取
robotCode
Type: stringDefault: ""
机器人的唯一标识码，从钉钉开放平台的机器人配置页获取
corpId
Type: stringDefault: ""
企业的 CorpId，格式 dingXXX，从钉钉管理后台获取
agentId
Type: stringDefault: ""
应用的 AgentId，从钉钉开放平台获取
dmPolicy
Type: stringDefault: "open"
私聊策略。选项：open（开放）、disabled（禁用）
groupPolicy
Type: stringDefault: "open"
群聊策略。选项：open（开放）、disabled（禁用）
messageType
Type: stringDefault: "markdown"
回复消息格式。选项：text（纯文本）、markdown、card（AI Card）
streaming
Type: booleanDefault: true
启用 AI Card 流式回复（打字机效果）
debug
Type: booleanDefault: false
开启调试模式，输出详细的连接和消息日志
DingTalk 常见问题
DingTalk 故障排查
机器人完全不回复
应用可能未发布、Stream 模式未启用、ClientID 或 ClientSecret 错误、或插件未正确安装。
逐步排查：1) 确认应用已发布并审批通过；2) 确认消息接收模式为 Stream 模式；3) 核对 ClientID 和 ClientSecret；4) 运行 openclaw plugins list 确认插件已安装；5) 运行 openclaw gateway status 检查连接状态。
能收到消息但 AI 不回复
OpenClaw 版本升级后可能出现的兼容性问题，或 AI 模型 API Key 未配置。
检查 AI 模型的 API Key 是否正确配置。尝试更新钉钉插件：openclaw plugins update @soimy/dingtalk。查看 openclaw logs --follow 获取详细错误信息。参考
Stream 连接频繁断开
网络不稳定或钉钉 Stream 模式已知的消息丢失问题。
Gateway 会自动处理断线重连（指数退避策略）。如果频繁断连，检查服务器网络稳定性，确保防火墙允许出站 WebSocket 连接。开启 debug 模式查看详细连接日志。
群文件或钉盘文件无法访问
群文件和钉盘 API 可能需要企业认证，未认证的组织可能无法使用这些功能。
检查组织是否已完成企业认证。如果未认证，某些高级文件 API 将不可用。可以通过直接发送文件（而非钉盘分享）来规避此限制。
AI Card 流式输出不工作
缺少 Card 相关权限，或 messageType 配置不正确。
确认已在钉钉开放平台授予 Card.Instance.Write 和 Card.Streaming.Write 权限。检查配置中 streaming 是否为 true。权限变更后需要重新发布应用。