DingTalk channel plugin for Clawdbot with Stream Mode support (forked by xuzizhan)
npm install @xuzizhan/dingtalk

钉钉(DingTalk)频道插件,支持通过 Stream 模式接收和回复私聊及群聊消息。无需公网域名,开箱即用!
---
- ✅ Stream 模式连接(无需公网域名)
- ✅ 私聊消息支持(DM)
- ✅ 群聊消息支持(@机器人)
- ✅ Pairing 模式访问控制
- ✅ SessionWebhook 优先回复(35分钟内快速响应)
- ✅ REST API 兜底回复
1. 钉钉企业内部应用(已创建并配置 Stream 模式)
2. Node.js 环境(clawdbot 已安装)
3. 应用的 AppKey (clientId) 和 AppSecret (clientSecret)
> 从 v0.1.0 升级? 查看 升级指南
``bash安装插件
clawdbot plugins install @xuzizhan/dingtalk
就这么简单!配置向导会引导你完成所有设置。
$3
如果你想从源码安装或进行开发:
`bash
克隆或下载源码
git clone https://github.com/yourusername/dingtalk-clawdbot.git本地安装
cd dingtalk-clawdbot
npm install
clawdbot plugins install .
`配置说明
$3
运行
clawdbot onboard --channel dingtalk 启动配置向导,它会:1. ✅ 要求输入 Client ID 和 Client Secret
2. ✅ 自动测试连接
3. ✅ 引导选择私聊策略(Pairing/Allowlist/Open/Disabled)
4. ✅ 引导选择群聊策略(Allowlist/Open/Disabled)
5. ✅ 自动保存配置到
~/.clawdbot/clawdbot.json$3
编辑
~/.clawdbot/clawdbot.json,添加 DingTalk 频道配置:`json
{
"channels": {
"dingtalk": {
"enabled": true,
"clientId": "dingXXXXXXXXXXXXXXXX",
"clientSecret": "YOUR_APP_SECRET_HERE",
"dm": {
"policy": "pairing",
"allowFrom": ["YOUR_STAFF_ID"]
},
"groupPolicy": "allowlist",
"groupAllowlist": ["YOUR_CONVERSATION_ID"],
"requireMention": true
}
}
}
`配置说明:
-
clientId: 钉钉应用的 AppKey
- clientSecret: 钉钉应用的 AppSecret
- dm.policy: 私聊策略
- "pairing": 需要明确允许的用户才能使用(推荐)
- "open": 任何人都可以私聊
- "disabled": 禁用私聊
- dm.allowFrom: 允许私聊的 staffId 列表(当 policy 为 pairing 时生效)
- groupPolicy: 群聊策略
- "allowlist": 仅允许列表中的群
- "open": 允许所有群
- "disabled": 禁用群聊
- groupAllowlist: 允许的群聊 conversationId 列表(当 groupPolicy 为 allowlist 时生效)
- requireMention: 是否要求在群聊中 @机器人(推荐 true)
- messageFormat: 消息格式(可选)
- "text": 纯文本格式(默认,推荐)
- "markdown": Markdown 格式(⚠️ 钉钉仅支持有限的 Markdown 语法,不支持表格)Markdown 格式说明:
- ✅ 支持:标题、粗体、斜体、链接、图片、引用、列表、代码块
- ❌ 不支持:表格、复杂嵌套列表、HTML 标签、任务列表
- 📝 自动转换:插件会自动将 Markdown 表格转换为纯文本代码块显示
- ⏰ 仅 SessionWebhook 可用:REST API 兜底时自动降级为纯文本
- 🔄 自动分段:超过 2500 字符的长消息会自动分多条发送,标题自动添加(1/N)标记
> 📖 详细语法指南请参阅 MARKDOWN.md
配置示例:
`json
{
"messageFormat": "markdown"
}
`$3
`bash
如果已经在运行,需要重启
clawdbot gateway restart或者首次启动
clawdbot gateway
`$3
`bash
查看实时日志
tail -f /tmp/clawdbot/clawdbot-$(date +%Y-%m-%d).log | grep dingtalk成功的标志:
[dingtalk:default] Starting Stream...
[dingtalk:default] Stream connected
[dingtalk] Stream connection started successfully
`获取你的 staffId
首次使用时,机器人会告诉你的 staffId:
1. 在钉钉中找到机器人
2. 发送任意消息
3. 机器人会回复:"Access denied. Your staffId: XXXXXXXXXXXXXXXXXXXX Ask admin to add you."
4. 将这个 staffId 添加到配置文件的
dm.allowFrom 数组中
5. 重启 gateway获取群聊 conversationId
如果使用
groupPolicy: "allowlist",需要获取群聊的 conversationId:方法1: 查看日志
1. 在群聊中 @机器人发送消息
2. 查看 gateway 日志:
`bash
tail -f /tmp/clawdbot/clawdbot-$(date +%Y-%m-%d).log | grep "dingtalk.*Group"
`
3. 日志会显示:[dingtalk] Group from XXX: ... 以及相关的 conversationId
4. 或者查看日志中的 "Group not in allowlist" 消息获取 conversationId方法2: 临时设置为 open
1. 临时修改配置为
groupPolicy: "open"
2. 重启 gateway
3. 在群聊中 @机器人发送消息
4. 查看日志获取 conversationId(格式类似 cidXXXXXXXXXXXXXXXXXX==)
5. 将 conversationId 添加到 groupAllowlist 数组
6. 改回 groupPolicy: "allowlist" 并重启配置示例:
`json
{
"groupPolicy": "allowlist",
"groupAllowlist": [
"cidXXXXXXXXXXXXXXXXXX==",
"cidYYYYYYYYYYYYYYYYYY=="
],
"requireMention": true
}
`钉钉应用配置
$3
1. 登录 钉钉开发者平台
2. 进入 应用开发 → 企业内部开发
3. 点击 创建应用
4. 添加 机器人 能力
5. 消息接收模式选择 Stream 模式
$3
应用需要以下权限:
-
qyapi_chat_manage(企业会话管理)
- qyapi_robot_sendmsg(机器人发送消息)$3
在应用详情页面:
- AppKey → 这是你的
clientId
- AppSecret → 点击查看并复制,这是你的 clientSecret$3
配置完成后,点击 发布 使应用生效。
故障排查
$3
`
[dingtalk] Failed to start Stream
`可能原因:
1. clientId 或 clientSecret 错误
2. 应用未选择 Stream 模式
3. 应用未发布
解决方法:
- 检查配置文件中的凭证是否正确
- 确认钉钉应用已选择 Stream 模式并发布
$3
可能原因:
1. staffId 未添加到 allowFrom 列表
2. 群聊未 @机器人(requireMention 为 true 时)
解决方法:
- 查看日志获取 staffId 并添加到配置
- 在群聊中使用 @机器人名称 来触发
$3
原因:配置修改需要重启 gateway
解决方法:
`bash
clawdbot gateway restart
`技术细节
$3
- Stream SDK:
dingtalk-stream@2.1.4
- 消息处理: 通过 DWClient 建立 WebSocket 长连接
- 配置加载: 自动调用 cfg.loadConfig() 获取实际配置(重要修复)
- 回复策略: SessionWebhook (35分钟内) → REST API (兜底)$3
| 文件 | 作用 |
|------|------|
|
src/monitor.ts | Stream 连接 + 消息处理核心逻辑 |
| src/api.ts | 钉钉 REST API 封装 |
| src/channel.ts | ChannelPlugin 接口实现 |
| src/accounts.ts | 账号凭证解析 |$3
- Markdown 有限支持:钉钉不支持 Markdown 表格,插件会自动转换为纯文本代码块
- 消息格式:默认纯文本,可选 Markdown(但有语法限制)
- 媒体消息:暂不支持文件、图片等媒体消息发送
- 钉钉限流:20条/分钟/群,超限后10分钟限流
更新日志
查看 CHANGELOG.md 获取详细的版本历史。
$3
- ✅ 官方 NPM 安装支持 -
clawdbot plugins install @xuzizhan/dingtalk
- ✅ 交互式配置向导 - clawdbot onboard --channel dingtalk`- ✅ 初始版本发布
- ✅ Stream 模式连接
- ✅ 私聊 + 群聊支持
- ✅ Pairing 访问控制
- ✅ 群聊白名单(groupAllowlist)
- ✅ Markdown 消息格式支持(自动转换表格为纯文本)
MIT License - 查看 LICENSE 文件获取详细信息。
发现问题或有改进建议?欢迎提交 Issue 或 Pull Request。