7.4 钉钉接入

---

钉钉是阿里系企业的标配，也是很多中小企业的选择。

把 OpenClaw 接入钉钉，可以让 AI 助手在钉钉群里回答问题、处理任务。

---

前提条件

在开始之前，确保你已经完成：

• 已经创建了钉钉应用和机器人，并发布
• 已经添加了必要的权限点：
  • Card.Streaming.Write（卡片流式写入）
  • Card.Instance.Write（卡片实例写入）
  • qyapi_robot_sendmsg（机器人消息发送）
• 已经获取了钉钉应用的 Client ID 和 Client Secret
• OpenClaw 已安装并正常运行

⚠️ 重要：本地安装 OpenClaw 仅支持 Mac 系统，暂不支持 Windows。如果不想本地安装，可以使用阿里云的 OpenClaw 一键部署。

---

第一步：安装钉钉插件

运行以下命令安装钉钉官方插件：

openclaw plugins install @openclaw/connector-dingtalk

OpenClaw 会自动处理下载、安装依赖和注册。

---

第二步：配置钉钉对接

编辑配置文件：

vim ~/.openclaw/openclaw.json

在配置文件中添加以下三个配置项：

{
  // ... 其他配置项 ...

  "channels": {
    "dingtalk-connector": {
      "enabled": true,
      "clientId": "your_client_id",        // 替换为你的 Client ID
      "clientSecret": "your_client_secret" // 替换为你的 Client Secret
    }
  },

  "gateway": {
    "auth": {
      "token": "your_token_here"  // 自定义一个 token，用于鉴权
    },
    "http": {
      "endpoints": {
        "chatCompletions": true  // 启用 chatCompletions 端点
      }
    }
  }
}

⚠️ 注意：

• clientId 和 clientSecret 在钉钉开放平台的应用详情页可以找到
• token 需要你自己设置一个字符串，后续鉴权会用到

使用 AI 工具辅助配置

如果你觉得手动编辑 JSON 麻烦，可以用本地 AI 工具（如 Qoder IDE）帮忙。

在 AI 工具中输入：

我现在想使用 openclaw 对接钉钉，请按照我下方的 json 配置和注释，在我的 ~/.openclaw/openclaw.json 中添加下方"channels/dingtalk-connector、gateway/auth 和 gateway/http/endpoints"3 个配置属性，不要改动其他属性。并最后帮我展示整个 openclaw.json 文件，让我可以人工修改查验相关内容。

然后把上面的 JSON 配置附上，AI 工具会帮你完成配置。

---

第三步：重启 Gateway

配置完成后，重启 Gateway 使配置生效：

openclaw gateway restart

等待出现 "Restarted LaunchAgent" 提示，说明重启成功。

验证 Gateway 是否正常运行：

curl http://127.0.0.1:18789/health

---

第四步：访问 Web UI 面板

在浏览器打开：

http://127.0.0.1:18789/

首次访问会显示未授权状态。

获取授权链接

回到终端，执行：

openclaw dashboard

会显示一个 Dashboard URL，复制到浏览器打开即可查看聊天记录。

---

常见问题

Q: 出现 405 错误

需要在 ~/.openclaw/openclaw.json 中启用 chatCompletions 端点：

{
  "gateway": {
    "http": {
      "endpoints": {
        "chatCompletions": true
      }
    }
  }
}

修改后执行：

openclaw gateway restart

Q: 出现 401 错误

检查 ~/.openclaw/openclaw.json 中的 gateway.auth 鉴权的 token/password 是否正确。

Q: 钉钉机器人无响应

检查清单：

• [ ] Gateway 正在运行：curl http://127.0.0.1:18789/health
• [ ] 机器人配置为 Stream 模式（非 Webhook）
• [ ] AppKey/AppSecret 正确

Q: AI Card 不显示，只有纯文本

需要开通权限 Card.Streaming.Write 和 Card.Instance.Write，并重新发布应用。

Q: 升级后出现插件加载异常或配置不生效

由于官方两次更名（Clawdbot → Moltbot → OpenClaw），旧版本（0.4.0 以下）的 connector 插件可能与新版本不兼容。

解决步骤：

1. 检查 ~/.openclaw/openclaw.json（或旧版的 ~/.clawdbot/clawdbot.json、~/.moltbot/moltbot.json），删除所有 dingtalk 相关的 JSON 节点
2. 清除旧插件并重新安装：

openclaw plugins uninstall @openclaw/connector-dingtalk
openclaw plugins install @openclaw/connector-dingtalk

Q: 图片不显示

检查清单：

• [ ] enableMediaUpload: true（默认开启）
• [ ] 检查日志中 [DingTalk][Media] 相关输出
• [ ] 确认钉钉应用有图片上传权限

---

实际应用场景

场景一：项目群助手

在项目群接入机器人：

项目经理：@AI助手 今天的任务进度如何？

机器人：【今日任务进度】
已完成：5/8
进行中：2/8
阻塞：1/8

阻塞项：后端 API 接口延迟
负责人：张三

场景二：客服支持

在客服群接入机器人：

客户：@AI助手 怎么申请退款？

机器人：退款申请流程：
1. 进入"我的订单"
2. 找到对应订单
3. 点击"申请退款"
4. 填写退款原因

如需人工协助，请拨打：400-xxx-xxxx

场景三：数据查询

在数据群接入机器人：

运营：@AI助手 查一下昨天的销售数据

机器人：【昨日销售数据】
订单量：156 单
销售额：￥78,500
客单价：￥503
转化率：3.2%

---

钉钉接入的注意事项

事项	说明
Stream 模式	机器人必须配置为 Stream 模式，不是 Webhook
权限配置	需要添加 Card.Streaming.Write 和 Card.Instance.Write 权限
系统支持	本地安装仅支持 Mac，Windows 用户建议用云部署
Node.js 版本	最低要求 v22.22.0

---

这一节，你做了什么

步骤	做了什么
检查前提条件	确认权限、Client ID/Secret 已准备
安装钉钉插件	安装 @openclaw/connector-dingtalk
配置对接信息	在 openclaw.json 中添加 channels 和 gateway 配置
重启 Gateway	使配置生效并验证