DingTalk-Real-AI / dingtalk-openclaw-connector

钉钉 OpenClaw 官方连接器 将钉钉机器人连接到 OpenClaw Gateway，支持 AI Card 流式响应和会话管理 English • 更新日志 --- 📋 目录 • 前置要求 • 快速开始 • 功能特性 • 配置说明 • 常见问题 • 进阶主题 • 许可证 --- 前置要求 开始之前，请确保你已经： > 本插件作为 OpenClaw Gateway 插件使用，一般无需你单独安装或管理 Node.js 运行时。 • OpenClaw Gateway • **官方网站**：https://openclaw.ai/ • **安装说明**：按照官方指南安装 OpenClaw • **验证安装**： 预期输出： • 钉钉企业账号 • 你需要一个钉钉企业账号来创建企业内部应用 • 官方网站：https://www.dingtalk.com/ --- 快速开始 > 💡 **目标**：5 分钟内让你的钉钉机器人运行起来 操作系统支持 • macOS / Linux：使用默认的 Shell 终端（zsh、bash 等）。 • Windows： • 推荐使用 **PowerShell** 或 **Windows Terminal**。 • OpenClaw 配置文件路径默认为： 。 下文中出现的 ，在 Windows 上等价于以上路径。 步骤 1：安装插件 **验证安装**： 你应该看到 --- 步骤 2：创建钉钉机器人 3.1 创建应用 • 访问 钉钉开放平台 • 点击 **"应用开发"** 3.2 添加机器人能力 • 在应用详情页，点击 一键创建OpenClaw机器人应用 3.3 获取凭证 • 完成创建并获取 **"凭证与基础信息"** • 复制你的 **AppKey**（Client ID） • 复制你的 **AppSecret**（Client Secret） > ⚠️ **重要**：Client ID和 Client Secret是机器人的唯一凭证。请合理保存。 --- 步骤 3：配置 OpenClaw 你有三种方式配置连接器： 方式 A：配置向导（推荐新手使用） > 你可以直接复制粘贴下面的命令，在终端中运行配置向导。 选择 **"DingTalk (钉钉)"**，然后按提示输入： • （AppKey） • （AppSecret） 方式 B：编辑配置文件 编辑配置文件： • macOS / Linux： • Windows： > 💡 **提示**：如果文件已有内容，在 节点下添加 部分即可。 --- 步骤 4：重启并测试 **测试你的机器人**： • 打开钉钉 App • 在联系人列表中找到你的机器人 • 发送消息： • 你应该在 10 秒内收到回复 --- 功能特性 ✅ 核心功能 • **AI Card 流式响应** - 打字机效果，实时流式显示回复 • **会话管理** - 多轮对话，保持上下文 • **会话隔离** - 私聊、群聊、不同群之间会话独立 • **自动会话重置** - 30 分钟无活动后自动开启新会话 • **手动会话重置** - 发送 或 清空对话历史 • **图片自动上传** - 本地图片路径自动上传到钉钉 • **主动发送消息** - 程序化地向用户或群发送消息 • **富媒体接收** - 接收并处理 JPEG/PNG 图片，传递给视觉模型 • **文件附件提取** - 解析 .docx、.pdf、文本文件和二进制文件 • **音频消息支持** - 发送多种格式的音频消息（mp3、wav、amr、ogg） • **钉钉文档 API** - 创建、追加、搜索和列举钉钉文档 • **多 Agent 路由** - 将多个机器人连接到不同的 Agent，实现专业化服务 • **Markdown 表格转换** - 自动将 Markdown 表格转换为钉钉兼容格式 • **异步模式** - 立即确认消息，后台处理（可选） --- 配置说明 基础配置 | 选项 | 环境变量 | 说明 | |------|---------|------| | | — | 钉钉 AppKey | | | — | 钉钉 AppSecret | 会话管理 | 选项 | 默认值 | 说明 | |------|--------|------| | | | 私聊/群聊分别维护会话 | | | | 群聊会话范围： （共享）或 （每人独立） | | | | 是否在不同会话间共享记忆 | 会话路由策略（ / ） 当前版本已支持会话路由/消息策略相关配置（包含 、 ），**无需删除**。如你在历史配置中已经设置了这些字段，可以继续保留并按需调整。 > 说明：不同版本/上游可能对字段命名有差异；本连接器侧同时支持并会按策略生效（如 / 的默认值为 ）。 异步模式 | 选项 | 默认值 | 说明 | |------|--------|------| | | | 启用异步模式处理长时间任务 | | | | 确认消息文本 | --- 常见问题 机器人不回复 **症状**：机器人不回复消息 **解决方案**： • 检查插件状态： • 检查网关状态： • 查看日志： • 确认应用已在钉钉开放平台发布 --- HTTP 401 错误 **症状**：错误信息显示 "401 Unauthorized" **原因**：Gateway 认证失败 **解决方案**： 升级到最新版本 --- Stream 连接 400 错误 **症状**：日志显示 "Request failed with status code 400" **常见原因**： | 原因 | 解决方案 | |------|----------| | 应用未发布 | 前往钉钉开放平台 → 版本管理 → 发布 | | 凭证错误 | 检查 / 是否有拼写错误或多余空格 | | 非 Stream 模式 | 确认机器人配置为 Stream 模式（不是 Webhook） | | IP 白名单限制 | 检查应用是否设置了 IP 白名单 | **验证步骤**： • **检查应用状态**： • 登录 钉钉开放平台 • 确认应用已发布 • 确认机器人已启用且为 Stream 模式 • **重新发布应用**： • 修改任何配置后，必须点击 **保存** → **发布** --- 进阶主题 多 Agent 配置 配置多个机器人连接到不同的 Agent： 更多详情请参考 OpenClaw 多 Agent 配置指南。 --- 会话命令 用户可以发送以下命令清理对话历史，重新开始会话： • 、 、 • 、 、 --- 钉钉文档（Docs）与 MCP（ ） 钉钉文档能力（ ，包含 / / / / ）依赖 MCP（Model Context Protocol）提供底层 tool。你需要先在 OpenClaw 的 Gateway/Agent 侧启用对应的 MCP Server/Tool，然后上述 才能正常工作。 • **获取 MCP Server/Tool**：可通过 钉钉 MCP 市场 安装启用（或你们团队维护的 MCP 市场）；也可以选择同类的“DingTalk Docs Read / DingTalk Docs Reader”能力并接入到 OpenClaw。 • **配置位置**：通常在 **Gateway 或 Agent 的工具配置**中完成（而不是在连接器里）。 • **生效方式**：配置完成后重启 Gateway，并确认该 tool 已对目标 Agent 暴露。 参考（OpenClaw 官方配置文档）： • • 从你的 Agent 中创建和管理钉钉文档： --- 项目结构 --- 依赖 | 包 | 用途 | |----|------| | | 钉钉 Stream 协议客户端 | | | HTTP 客户端 | | | Word 文档（.docx）解析 | | | PDF 文档解析 | --- 许可证 MIT --- 支持 • **问题反馈**：GitHub Issues • **更新日志**：CHANGELOG.md