OpenClaw 钉钉接入全流程：从创建应用到消息收发的完整指南

钉钉接入方式概览

OpenClaw 通过社区插件接入钉钉，目前有两个主流插件可选：

两个插件都用钉钉 Stream 模式（WebSocket 长连接），不需要公网 IP 或域名，家里电脑、公司内网都能用。

本文以 @soimy 版本为主线讲解，覆盖 90% 以上的使用场景。

接入前的准备工作

开始之前确认以下几项：

• OpenClaw 已安装运行。没装的先去 安装教程
• 钉钉组织管理员或开发者权限：需要在钉钉开放平台创建应用
• 确认 Gateway 正常运行：

openclaw gateway status

好消息：钉钉 Stream 模式是 OpenClaw 主动连接钉钉服务器，不需要公网 IP、不需要域名、不需要 SSL 证书。NAT 后面、企业防火墙后面都能用。

第一步：安装钉钉插件

openclaw plugins install @soimy/dingtalk

安装完后确认一下：

openclaw plugins list
# 应该看到 @soimy/dingtalk

如果需要 AI Card 流式回复和多 Agent 路由，改用：openclaw plugins install @dingtalk-real-ai/dingtalk-connector

第二步：创建钉钉企业内部应用

1. 登录 钉钉开放平台 → 进入开发者后台
2. 点击「创建应用」→ 选择「企业内部开发」
3. 应用类型选「机器人」，填写名称（比如"AI 助手"）和描述
4. 创建完成后，进入应用详情 → 凭证与基本信息
5. 复制 ClientID（也叫 AppKey，格式 dingXXX）和 ClientSecret（也叫 AppSecret）

⚠️ ClientSecret 相当于密码，不要提交到 Git，不要发到群里。

第三步：配置 Stream 模式和权限

启用 Stream 模式

进入应用 → 机器人配置 → 消息接收模式选择 Stream 模式。

这一步很关键。如果选了 HTTP 模式，就需要公网地址了。Stream 模式通过 WebSocket 长连接，无需公网。

配置权限

进入 权限管理，添加以下权限：

第四步：发布应用

配置好权限后，需要发布应用：

1. 进入 版本管理与发布 → 创建版本
2. 填写版本号和更新说明 → 提交
3. 组织管理员审批通过后，在钉钉中搜索应用名称就能找到机器人

如果你就是管理员，一般秒过。

第五步：OpenClaw 钉钉渠道配置

手动配置

编辑 ~/.openclaw/openclaw.json：

{
  channels: {
    dingtalk: {
      enabled: true,
      clientId: "dingXXXXXX",       // 从开放平台获取
      clientSecret: "your-secret",   // 从开放平台获取
      robotCode: "dingXXXXXX",      // 机器人唯一标识
      corpId: "dingXXXXXX",         // 企业 CorpId
      agentId: "123456789",         // 应用 AgentId
      dmPolicy: "open",             // 私聊策略
      groupPolicy: "open",          // 群聊策略
      messageType: "markdown",      // 回复格式
      streaming: true               // 流式输出
    }
  }
}

配置项说明

第六步：启动并测试

启动 Gateway

openclaw gateway restart
openclaw logs --follow     # 实时查看日志

测试消息收发

1. 在钉钉中搜索你的机器人名称，开始私聊
2. 发一条消息（随便说句话）
3. 确认 AI 正常回复

验证连接状态：

openclaw gateway status
# 应该看到 DingTalk: connected

到这一步，基础的消息收发就跑通了。

钉钉群聊机器人配置

默认配置下群聊已经可用（groupPolicy: "open"）：

1. 把机器人添加到群聊中
2. 在群里 @机器人名称 + 你的问题
3. 机器人会回复

会话按对话维度隔离，私聊和群聊各自有独立的上下文。30 分钟不活跃自动重置会话。

AI Card 流式回复配置

钉钉的 AI Card 回复效果类似 ChatGPT 的打字机效果，消息在卡片中逐步更新，体验很好。

开启方式

{
  channels: {
    dingtalk: {
      messageType: "card",  // 或 "markdown" + streaming: true
      streaming: true
    }
  }
}

前提条件

• 钉钉应用已授予 Card.Instance.Write 和 Card.Streaming.Write 权限
• 权限变更后需要重新发布应用

多 Agent 路由配置

如果你用的是 @dingtalk-real-ai 版本的插件，可以配置多 Agent 路由：

{
  bindings: [
    { agentId: "main", match: { channel: "dingtalk", peer: { kind: "direct" } } },
    { agentId: "tech-support", match: { channel: "dingtalk", peer: { kind: "group" } } }
  ]
}

这样私聊走通用助手，群聊走技术支持 Agent，互不干扰。

钉钉常用命令速查

常见问题

需要公网 IP 吗？

不需要。钉钉插件用 Stream 模式（WebSocket 长连接），OpenClaw 主动连接钉钉服务器。家里的电脑、公司内网都能用。

两个钉钉插件怎么选？

新手选 @soimy/dingtalk，资料多、社区活跃。需要多 Agent 或异步处理的高级用户选 @dingtalk-real-ai 版本。

能同时接入其他渠道吗？

能。OpenClaw 支持多渠道同时运行，钉钉、飞书、Telegram、Discord 可以共享同一个 AI Agent，各渠道独立配置互不影响。

回复很慢怎么办？

先开启流式输出（streaming: true），体感会快很多。如果还是慢，考虑换一个响应更快的模型，或者检查你的 AI 服务是否有延迟。

ClientSecret 泄露了怎么办？

立刻去钉钉开放平台重置 Secret，然后更新 OpenClaw 配置文件并重启 Gateway。旧 Secret 会立即失效。

升级 OpenClaw 后钉钉不工作了？

这是已知的兼容性问题。先更新插件：openclaw plugins update @soimy/dingtalk。如果仍有问题，查看插件 GitHub Issues。

机器人完全不回复怎么办？

一步步排查：

1. 应用是否已发布（草稿状态不生效）
2. 消息接收模式是否为 Stream 模式（不是 HTTP 模式）
3. ClientID 和 ClientSecret 是否填对了
4. 插件是否已安装（openclaw plugins list）
5. AI 模型的 API Key 配了没
6. 用 openclaw doctor 综合诊断

群聊中 @机器人没反应？

确认机器人已添加到群里、groupPolicy 不是 disabled。查看 openclaw logs --follow 是否有错误日志。

AI Card 流式输出不工作？

确认钉钉应用已授予 Card.Instance.Write 和 Card.Streaming.Write 权限，权限变更后需要重新发布应用。

钉钉接入完成，下一步做什么

钉钉搞定了，可以继续探索：

• 查看所有支持的渠道 — 50+ 渠道集成
• Skills 技能目录 — 给 AI 装上更多能力
• 问题排查指南 — 通用问题排查
• 飞书接入指南 — 另一个企业协作平台
• Telegram 接入指南 — 海外热门渠道
• OpenClaw 完整入门指南 — 从零开始的完整教程