Skip to Content
📖 教程📱 渠道接入钉钉

接入钉钉

钉钉是阿里巴巴旗下的企业协作平台，在国内企业中使用率极高。OpenClaw 提供了官方钉钉插件，通过钉钉 Stream API（长连接）方式接入，同样不需要公网 IP 和域名，配置简单。

一、钉钉开放平台创建机器人

1.1 进入开放平台

  1. 访问 钉钉开放平台 
  2. 使用你的钉钉账号登录
  3. 进入 应用开发 页面

1.2 创建企业内部应用

  1. 选择 企业内部开发 → 创建应用
  2. 填写应用名称（如 OpenClaw AI）和描述
  3. 选择应用类型为 H5微应用（或直接创建机器人类型）
  4. 创建完成后进入应用管理页面

1.3 添加机器人能力

  1. 在应用管理页面，选择 添加应用能力
  2. 添加 机器人 能力
  3. 在机器人配置中：
    • 设置机器人名称和头像
    • 消息接收模式 选择 Stream 模式（长连接）

⚠️ 重要： 一定要选择 Stream 模式，不要选择 HTTP 模式。Stream 模式（类似 WebSocket）不需要公网回调地址。

1.4 配置权限

在 权限管理 中，根据需要申请以下权限：

  • 消息通知相关：企业内机器人发送消息等
  • 群会话相关：读取群消息、在群中发送消息等

二、获取相关凭证

在钉钉开放平台的应用管理页面中：

  1. 进入 凭证与基础信息 页面
  2. 获取以下信息：
    • Client ID（也叫 AppKey）：格式类似 dinge9fjs5bijaq65z3m
    • Client Secret（也叫 AppSecret）：一串较长的随机字符串

这两个值就是 OpenClaw 连接钉钉所需的凭证。

三、OpenClaw 配置

3.1 编辑配置文件

打开 ~/.openclaw/openclaw.json，在 channels 中添加钉钉配置：

{
  "channels": {
    "dingtalk": {
      "enabled": true,
      "clientId": "dinge9fjs5bijaq65z3m",
      "clientSecret": "your_client_secret_here"
    }
  }
}

和飞书一样，钉钉的最简配置也只需要两个字段：clientId 和 clientSecret。

3.2 重启 Gateway

openclaw gateway restart

启动后，OpenClaw 会自动通过 Stream API 建立与钉钉服务器的长连接。

3.3 使用 onboard 向导（可选）

openclaw onboard

向导会引导你完成钉钉凭证的输入。

四、群聊和单聊

4.1 单聊（私聊）

用户可以在钉钉中搜索你的机器人应用，直接发起对话。单聊中的所有消息都会被 OpenClaw 处理并回复。

4.2 群聊

将机器人添加到钉钉群后，可以在群聊中使用。

添加机器人到群聊：

  1. 打开钉钉群 → 群设置
  2. 点击 智能群助手 → 添加机器人
  3. 搜索并选择你创建的机器人应用
  4. 确认添加

群聊触发规则：

  • 默认需要 @机器人 才会触发 AI 回复
  • 机器人只能看到 @它 的消息和自己发送的消息

4.3 会话隔离

  • 单聊 session：agent:<agentId>:dingtalk:user:<userId>
  • 群聊 session：agent:<agentId>:dingtalk:group:<chatId>

五、Stream 模式说明

钉钉的 Stream API 是一种类似 WebSocket 的长连接协议。OpenClaw 的钉钉插件使用这种模式有以下好处：

  • 无需公网 IP：OpenClaw 主动连接钉钉服务器，不需要你暴露任何端口
  • 无需域名和 SSL：省去了证书配置的麻烦
  • 低延迟：长连接保持，消息到达即时推送
  • 自动重连：连接断开后自动恢复
  • 防火墙友好：只需出站 HTTPS 连接

这意味着你可以在家庭网络、公司内网、甚至是 NAT 后面的机器上运行 OpenClaw 并连接钉钉。

与 Webhook 模式的对比

钉钉也支持传统的 HTTP Webhook 回调模式，但 OpenClaw 推荐使用 Stream 模式：

特性Stream 模式Webhook 模式
公网 IP不需要需要
域名 + SSL不需要需要
配置复杂度低高
消息可靠性高一般
适合场景推荐所有场景已有公网服务器

六、注意事项

6.1 企业管理员权限

钉钉的企业内部应用需要有开发者权限才能创建。如果你的钉钉账号没有开发者权限，需要联系企业管理员添加。

6.2 应用发布

企业内部应用创建后，可能需要管理员审核发布才能被其他成员看到。在测试阶段，你可以将自己设为测试人员。

6.3 消息格式

钉钉机器人发送的消息支持以下格式：

  • 纯文本
  • Markdown（部分支持）
  • 链接消息
  • ActionCard（卡片消息）

OpenClaw 目前主要使用纯文本和 Markdown 格式发送回复。

6.4 消息频率限制

钉钉对机器人消息有频率限制：

  • 单聊：每个用户每分钟最多 20 条
  • 群聊：每个群每分钟最多 20 条

正常使用 AI 对话不会触发这个限制，但如果你配置了频繁的 heartbeat 或批量发送，需要注意。

6.5 安全相关

  • Client Secret 保密：不要将 Client Secret 提交到公开的代码仓库
  • 权限最小化：只申请必要的权限

6.6 调试

查看日志排查问题：

tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep -i dingtalk

常见问题：

  • 连接失败：检查 Client ID 和 Client Secret 是否正确
  • 收不到消息：确认选择了 Stream 模式，并且已添加机器人能力
  • 群聊无反应：确认机器人已添加到群中，并且用户 @了机器人

💬 有问题或建议？ 欢迎在下方评论区留言讨论。

Last updated on
飞书企业微信