OpenClaw 钉钉机器人配置指南

将 AI 能力接入钉钉，打造企业级智能助手

---

前言

OpenClaw 是一款强大的 AI Agent 框架，通过钉钉 Connector 插件，可以轻松将 AI 能力接入钉钉群聊和私聊场景。本文将详细介绍如何配置 OpenClaw 钉钉机器人，让你的团队在钉钉中即可享受 AI 助手服务。

---

核心特性

• AI Card 流式响应 — 打字机效果，实时显示 AI 回复
• 会话持久化 — 同一用户的多轮对话共享上下文
• 会话与记忆隔离 — 单聊、群聊、不同群分别维护独立会话
• 图片自动上传 — 本地图片路径自动上传到钉钉
• 富媒体接收 — 支持 JPEG/PNG 图片消息，自动传递给视觉模型
• 文件附件提取 — 支持 .docx、.pdf、纯文本文件等
• 多 Agent 路由 — 多个钉钉机器人可分别绑定到不同 Agent

---

第一步：安装插件

打开终端，执行以下命令安装钉钉 Connector 插件：

# 通过 npm 安装（推荐）
openclaw plugins install @dingtalk-real-ai/dingtalk-connector
​
# 或通过 Git 安装
openclaw plugins install https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector.git

如需升级插件：

openclaw plugins update dingtalk-connector

---

第二步：创建钉钉机器人

2.1 进入钉钉开放平台

1. 打开 钉钉开放平台
2. 进入 应用开发 → 企业内部开发 → 创建应用

2.2 添加机器人能力

1. 在应用详情页，添加 机器人 能力
2. 消息接收模式选择 Stream 模式（重要！）

2.3 开通必要权限

确保开通以下权限：

权限名称	用途
Card.Streaming.Write	AI Card 流式响应
Card.Instance.Write	AI Card 实例写入
qyapi_robot_sendmsg	主动发送消息

如需使用文档 API 功能，还需开通文档相关权限。

2.4 发布应用并记录凭证

1. 发布应用
2. 记录 AppKey 和 AppSecret（稍后配置需要）

---

第三步：配置 OpenClaw

3.1 编辑配置文件

打开配置文件 ~/.openclaw/openclaw.json，添加以下内容：

{
  "channels": {
    "dingtalk-connector": {
      "enabled": true,
      "clientId": "dingxxxxxxxxx",
      "clientSecret": "your_secret_here",
      "gatewayToken": "gateway.auth.token",
      "sessionTimeout": 1800000,
      "separateSessionByConversation": true,
      "sharedMemoryAcrossConversations": false
    }
  },
  "gateway": {
    "http": {
      "endpoints": {
        "chatCompletions": {
          "enabled": true
        }
      }
    }
  }
}

3.2 配置参数说明

参数	必填	说明
clientId	✅	钉钉 AppKey
clientSecret	✅	钉钉 AppSecret
gatewayToken	可选	Gateway 认证 token
sessionTimeout	可选	会话超时时间，默认 30 分钟
separateSessionByConversation	可选	是否按单聊/群聊区分 session，默认 true
sharedMemoryAcrossConversations	可选	是否跨会话共享记忆，默认 false

3.3 启用 chatCompletions 端点

重要！ 如果不启用此端点，会出现 405 错误。确保在 gateway.http.endpoints 中配置：

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

---

第四步：重启 Gateway

配置完成后，重启 OpenClaw Gateway：

openclaw gateway restart

验证插件是否加载成功：

openclaw plugins list

确认 dingtalk-connector 已出现在列表中。

---

第五步：开始使用

在钉钉中找到你创建的机器人，发送消息即可开始对话！

会话命令

用户可发送以下命令开启新会话：

• /new、/reset、/clear
• 新会话、重新开始、清空对话

---

常见问题

Q: 出现 405 错误？

原因：未启用 chatCompletions 端点

解决：在配置文件中添加：

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

Q: 出现 401 错误？

原因：Gateway 认证信息不正确

解决：检查 gatewayToken 或 gatewayPassword 是否与 Gateway 配置的认证信息一致。

Q: 钉钉机器人无响应？

排查步骤：

1. 确认 Gateway 正在运行：curl http://127.0.0.1:18789/health
2. 确认机器人配置为 Stream 模式（非 Webhook）
3. 确认 AppKey/AppSecret 正确

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

原因：未开通必要权限

解决：开通 Card.Streaming.Write 和 Card.Instance.Write 权限，并重新发布应用。

Q: 图片消息无法识别？

排查步骤：

1. 检查图片是否下载到 ~/.openclaw/workspace/media/inbound/ 目录
2. 确认 Gateway 配置的模型支持视觉能力（vision model）
3. 查看日志中是否有图片下载或处理的错误信息

---

多 Agent 配置（进阶）

如果需要多个钉钉机器人分别连接不同的 Agent（实现角色分工），可配置多账号：

{
  "channels": {
    "dingtalk-connector": {
      "enabled": true,
      "accounts": {
        "bot1": {
          "enabled": true,
          "clientId": "ding_bot1_app_key",
          "clientSecret": "bot1_secret",
          "gatewayToken": "gateway.auth.token"
        },
        "bot2": {
          "enabled": true,
          "clientId": "ding_bot2_app_key",
          "clientSecret": "bot2_secret",
          "gatewayToken": "gateway.auth.token"
        }
      }
    }
  },
  "bindings": [
    {
      "agentId": "agent-assistant",
      "match": {
        "channel": "dingtalk-connector",
        "accountId": "bot1"
      }
    },
    {
      "agentId": "agent-developer",
      "match": {
        "channel": "dingtalk-connector",
        "accountId": "bot2"
      }
    }
  ]
}

---

总结

通过以上步骤，你已成功将 OpenClaw AI 能力接入钉钉。现在你的团队可以在钉钉群聊或私聊中与 AI 助手互动，享受智能问答、文档处理、图片识别等强大功能。

如有更多问题，欢迎访问 OpenClaw 官方文档 或 GitHub 仓库。

---

本文档基于 OpenClaw 钉钉 Connector v0.7.4 编写