OpenClaw-Channel-DingTalk终极指南：打造高效钉钉机器人通道的完整攻略

【免费下载链接】openclaw-channel-dingtalk A dingtalk bot channel plugin for clawdbot 项目地址: https://gitcode.com/gh_mirrors/op/openclaw-channel-dingtalk

OpenClaw-Channel-DingTalk是一款专为Clawdbot打造的钉钉企业内部机器人通道插件，采用Stream模式实现通信，无需公网IP即可轻松部署。本指南将带您从安装到高级配置，全方位掌握这款强大工具的使用方法，让您的钉钉机器人通道高效稳定运行。

快速了解OpenClaw-Channel-DingTalk的核心优势

OpenClaw-Channel-DingTalk作为一款专业的钉钉机器人通道插件，具备多项强大功能特性，使其在众多同类工具中脱颖而出：

• ✅ Stream模式：采用WebSocket长连接技术，无需公网IP或Webhook即可实现通信
• ✅ 全场景支持：完美支持私聊直接对话和群聊@机器人两种交互方式
• ✅ 丰富消息类型：支持文本、图片、语音（自带识别）、视频、文件、钉钉文档/钉盘文件卡片等多种格式
• ✅ 智能引用功能：支持恢复大多数引用场景，包括文字、图片、图文、文件、视频、语音和AI卡片
• ✅ 富文本回复：支持Markdown格式回复，并自动将Markdown表格转换为钉钉更稳定的可读文本
• ✅ 互动卡片：支持流式更新，特别适用于AI实时输出场景
• ✅ 完整AI对话：无缝接入Clawdbot消息处理管道，实现智能化交互

超简单安装步骤：4种方法任你选

方法A：通过npm包安装（推荐）

这是最简便的安装方式，只需一行命令即可完成：

openclaw plugins install @soimy/dingtalk

方法B：通过本地源码安装

如果您需要进行二次开发，推荐使用源码安装方式：

# 克隆仓库
git clone https://gitcode.com/gh_mirrors/op/openclaw-channel-dingtalk
cd openclaw-channel-dingtalk

# 安装依赖
npm install

# 以链接模式安装
openclaw plugins install -l .

方法C：手动安装

适合有特殊需求的用户：

1. 将项目目录下载或复制到 ~/.openclaw/extensions/dingtalk
2. 确保包含 index.ts, openclaw.plugin.json 和 package.json
3. 运行 openclaw plugins list 确认 dingtalk 已显示在列表中

方法D：国内网络环境安装（npm镜像源）

针对国内用户，可使用国内镜像源加速安装：

NPM_CONFIG_REGISTRY=https://registry.npmmirror.com openclaw plugins install @soimy/dingtalk

安装后必做：配置插件信任白名单

从OpenClaw新版本开始，需要显式配置信任的插件：

1. 确认插件id为：dingtalk（定义于 openclaw.plugin.json）

2. 在 ~/.openclaw/openclaw.json 添加：

{
  "plugins": {
    "enabled": true,
    "allow": ["dingtalk"]
  }
}

3. 重启Gateway：

openclaw gateway restart

轻松配置：交互式与手动配置全指南

方法1：交互式配置（推荐）

OpenClaw提供了友好的命令行向导配置：

# 方式A：使用onboard命令
openclaw onboard

# 方式B：直接配置channels部分
openclaw configure --section channels

交互式配置流程：

1. 选择插件 — 在插件列表中选择 dingtalk 或 DingTalk (钉钉)
2. Client ID — 输入钉钉应用的AppKey
3. Client Secret — 输入钉钉应用的AppSecret
4. 完整配置 — 可选配置Robot Code、Corp ID、Agent ID（推荐）
5. 卡片模式 — 可选启用AI互动卡片模式
6. 私聊策略 — 选择 open（开放）或 allowlist（白名单）
7. 群聊策略 — 选择 open（开放）或 allowlist（白名单）

方法2：手动配置文件

在 ~/.openclaw/openclaw.json 中添加配置（示例）：

{
  "plugins": {
    "enabled": true,
    "allow": ["dingtalk"]
  },
  "channels": {
    "dingtalk": {
      "enabled": true,
      "clientId": "dingxxxxxx",
      "clientSecret": "your-app-secret",
      "robotCode": "dingxxxxxx",
      "corpId": "dingxxxxxx",
      "agentId": "123456789",
      "dmPolicy": "open",
      "groupPolicy": "open",
      "journalTTLDays": 7,
      "showThinking": true,
      "thinkingMessage": "🤔 思考中，请稍候...",
      "asyncMode": false,
      "messageType": "markdown",
      "cardTemplateId": "你复制的模板ID",
      "cardTemplateKey": "你模板的内容变量"
    }
  }
}

配置完成后重启Gateway：

openclaw gateway restart

钉钉开发者平台配置详解

创建钉钉应用

1. 访问 钉钉开发者后台
2. 创建企业内部应用
3. 添加「机器人」能力
4. 配置消息接收模式为 Stream模式
5. 发布应用

配置权限管理

需要开启以下权限：

• Card.Instance.Write — 创建和投放卡片实例
• Card.Streaming.Write — 对卡片进行流式更新
• 机器人消息发送相关权限 — 允许机器人向单聊/群聊发送消息
• 媒体文件上传相关权限 — 允许调用媒体上传接口

引用消息中的群文件下载还需开通：

• ConvFile.Space.Read — 群文件空间读权限
• Storage.File.Read — 企业存储文件读权限
• Storage.DownloadInfo.Read — 企业存储文件下载信息读权限
• Contact.User.Read — 通讯录用户信息读权限

建立卡片模板(可选)

1. 访问 钉钉卡片平台
2. 进入「我的模板」
3. 点击「创建模板」
4. 卡片模板场景选择 「AI卡片」
5. 设计卡片排版并保存发布
6. 复制模板ID和内容字段名称
7. 配置到 openclaw.json 中

消息类型全解析：接收与发送能力

接收消息类型支持

OpenClaw-Channel-DingTalk支持多种消息类型的接收：

类型	支持	说明
文本	✅	完整支持
富文本	✅	提取文本内容
图片	✅	下载并传递给AI
语音	✅	使用钉钉语音识别结果
视频	✅	下载并传递给AI
文件	✅	下载并传递给AI
钉钉文档/钉盘文件卡片	✅	解析链接提取文件信息
引用消息	✅	支持文字、图片、文件等多种引用场景

发送消息类型支持

类型	支持	说明
文本	✅	完整支持
Markdown	✅	自动检测或手动指定
互动卡片	✅	支持流式更新，适用于AI实时输出
图片	✅	先上传媒体再发送
语音	✅	先上传媒体再发送
视频	✅	先上传媒体再发送
文件	✅	先上传媒体再发送

高级功能：反馈学习与共享知识

OpenClaw-Channel-DingTalk支持本地反馈学习闭环，将用户反馈沉淀为可审计的会话笔记和共享规则。

学习命令与作用域

常用命令：

• 查自己是谁：私聊或群聊发 我是谁 或 /learn whoami
• 查当前会话：发送 这里是谁 或 /learn whereami
• 注入当前会话：/learn here #@# <规则>
• 注入指定目标：/learn target <conversationId> #@# <规则>
• 注入全局规则：/learn global <规则>
• 查看规则：/learn list
• 停用规则：/learn disable <ruleId>
• 删除规则：/learn delete <ruleId>

会话共享命令

控制多个会话共用同一条会话记忆：

• 查看当前会话alias：/session-alias show
• 绑定当前会话：/session-alias set <alias>
• 清除绑定：/session-alias clear
• 远程绑定：/session-alias bind direct <senderId> <alias>

多机器人与多Agent配置指南

OpenClaw支持同时接入多个钉钉机器人，并将不同机器人的消息路由到不同的Agent处理：

{
  "agents": {
    "list": [
      {
        "id": "main"
      },
      {
        "id": "growth-agent",
        "name": "growth-agent",
        "workspace": "/path/to/growth-agent/workspace",
        "agentDir": "/path/to/growth-agent/agent",
        "model": "codex/gpt-5.3-codex"
      }
    ]
  },
  "bindings": [
    {
      "type": "route",
      "agentId": "main",
      "match": {
        "channel": "dingtalk",
        "accountId": "bot_1"
      }
    },
    {
      "type": "route",
      "agentId": "growth-agent",
      "match": {
        "channel": "dingtalk",
        "accountId": "bot_2"
      }
    }
  ],
  "channels": {
    "dingtalk": {
      "enabled": true,
      "accounts": {
        "bot_1": {
          "clientId": "your-client-id-1",
          "clientSecret": "your-client-secret-1",
          "robotCode": "your-robot-code-1",
          "corpId": "your-corp-id",
          "agentId": "your-dingtalk-agent-id-1",
          "messageType": "card"
        },
        "bot_2": {
          "clientId": "your-client-id-2",
          "clientSecret": "your-client-secret-2",
          "robotCode": "your-robot-code-2",
          "corpId": "your-corp-id",
          "agentId": "your-dingtalk-agent-id-2",
          "messageType": "markdown"
        }
      }
    }
  }
}

故障排除：常见问题与解决方法

收不到消息

1. 确认应用已发布
2. 确认消息接收模式是Stream
3. 检查Gateway日志：openclaw logs | grep dingtalk

连接失败

运行连接检查脚本：

# macOS/Linux
bash scripts/dingtalk-connection-check.sh --config ~/.openclaw/openclaw.json

# Windows PowerShell
pwsh -File scripts/dingtalk-connection-check.ps1 -Config ~/.openclaw/openclaw.json

关键设置检查清单：

• 应用为企业内部应用/机器人，且已"发布"版本
• 可见范围需为"全员员工"
• 已开启"机器人能力"，消息接收方式为"Stream模式"

错误payload日志查看

openclaw logs | grep "\[ErrorPayload\]"

开发与测试：扩展与定制

项目结构

src/
  channel.ts           - 插件定义和辅助函数
  runtime.ts           - 运行时管理
  types.ts             - 类型定义
index.ts              - 插件注册
utils.ts              - 工具函数
openclaw.plugin.json  - 插件配置
package.json          - 项目配置

运行测试

# 安装依赖
pnpm install

# 运行全部测试
pnpm test

# 生成覆盖率报告
pnpm test:coverage

安全策略：保护你的机器人通道

私聊策略 (dmPolicy)

• open — 任何人都可以私聊机器人
• pairing — 新用户需要通过配对码验证
• allowlist — 只有allowFrom列表中的用户可以使用

群聊策略 (groupPolicy)

• open — 任何群都可以@机器人
• allowlist — 只有配置的群可以使用

通过本指南，您已经掌握了OpenClaw-Channel-DingTalk的安装、配置和高级使用技巧。这款强大的钉钉机器人通道插件将帮助您构建高效、稳定的企业内部通信解决方案，提升工作效率和智能化水平。无论您是普通用户还是开发人员，都能从中找到适合自己的使用方法，开启智能钉钉机器人之旅。

【免费下载链接】openclaw-channel-dingtalk A dingtalk bot channel plugin for clawdbot 项目地址: https://gitcode.com/gh_mirrors/op/openclaw-channel-dingtalk