接入钉钉

钉钉是阿里巴巴旗下的企业协作平台，在国内企业中使用率极高。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 模式：

六、注意事项

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 模式，并且已添加机器人能力
• 群聊无反应：确认机器人已添加到群中，并且用户 @了机器人