deepseek-harness-dingtalk

基于钉钉官方 dingtalk-stream SDK 的 DeepSeek Harness 长连接通道。无需公网 IP 或回调服务器，使用 Client ID 和 Client Secret 即可连接应用机器人。

功能

• 官方 Stream WebSocket 长连接和心跳；插件托管自动重连并闭合 SDK 的异步失败
• 单聊和群聊访问策略与白名单
• 普通文字、Markdown、富文本、语音转写、图片和普通文件输入
• 通过官方 downloadCode API 下载图片与文件；普通文件安全保存到当前 Agent 工作目录
• 根据模型能力启用图片多模态输入，文本模型得到附件说明
• 模型回复使用钉钉原生 Markdown，生成图片和工作目录文件可上传发送
• 完整 Harness Agent Loop：工具调用会正常解析、执行并以结构化事件持久化，只发送最终可见回复
• 每个钉钉会话独立、可恢复的 Harness 会话；恢复原 Agent preset，并复用已有 live Agent
• 工具审批可在原钉钉会话使用一次性的 /approve <短码> 或 /reject <短码> 决定
• /new、Harness 注册斜命令，以及 /bot-ping、/bot-help、/bot-image-test、/bot-file-test、/bot-status、/bot-cancel
• Client Secret 通过 Harness 凭据服务解析
• 缺少配置或后台鉴权失败时通道保持离线，不阻塞 Harness Web 启动

环境要求

• Node.js 22.19 或更高版本
• pnpm 10.33.4
• DeepSeek Harness 0.1.0-rc.7 或更高版本

安装

pnpm dsh plugin --profile web add github:sliverp/DeepSeek-harness-dingtalk

本地开发版本：

pnpm dsh plugin --profile web add /absolute/path/to/DeepSeek-harness-dingtalk

钉钉开放平台配置

1. 打开钉钉开放平台，进入「应用开发」。
2. 创建企业内部应用并添加机器人能力；也可以使用官方「一键创建 OpenClaw 机器人应用」。
3. 在「凭证与基础信息」复制 Client ID（原 AppKey）和 Client Secret（原 AppSecret）。
4. 把 Client ID 写入 DINGTALK_CLIENT_ID，把 Client Secret 保存为 Harness 凭据 DINGTALK_CLIENT_SECRET。

开发时可从环境变量注入：

export DINGTALK_CLIENT_ID='ding_your-client-id'
export DINGTALK_CLIENT_SECRET='your-client-secret'
pnpm dsh --profile web

长期运行时，建议把 Client ID 放在 ~/.dsh/.env，并通过 Harness 凭据设置界面保存 Client Secret。不要把真实凭据提交到 Git。

配置

安装包默认添加：

- id: dingtalk-channel
  name: deepseek-harness-dingtalk
  config:
    clientId: !!js process.env.DINGTALK_CLIENT_ID
    clientSecretRef: DINGTALK_CLIENT_SECRET
    cwd: !!js process.env.DSH_DINGTALK_CWD ?? process.cwd()
    agentPreset: standard

生产环境建议改为白名单：

    singlePolicy: allowlist
    singleAllowFrom: [staff-id-1]
    groupPolicy: allowlist
    groupAllowChats: [conversation-id-1]
    imageInputMode: auto
    maxInboundFileBytes: 20971520
    maxOutboundFileBytes: 20971520
    approvalTimeoutMs: 240000
    reconnectDelayMs: 1000

访问策略可选 open、allowlist、disabled。机器人收到第一条消息后，可从钉钉回调中的发送者和会话标识配置白名单。

连接和鉴权在后台运行。缺少或错误的钉钉凭据只会让该通道保持离线并记录日志，不会阻塞 Harness 启动。官方 SDK 自带的自动重连会把端点发现失败留成未处理 Promise，因此插件会禁用该路径并以 reconnectDelayMs（默认 1,000 毫秒）自行监督重连；DNS、鉴权端点或 WebSocket 临时失败只会让钉钉离线和继续重试，不能退出 Harness 进程。

Harness 请求工具审批时，插件会向原钉钉会话发送绑定请求者的六位短码。回复 /approve <短码> 只允许该操作一次，回复 /reject <短码> 拒绝该操作。短码只能消费一次，不能跨会话使用；原回合等待期间会绕过普通消息容量限制。超时、取消、发送失败或服务退出都会按失败闭合。approvalTimeoutMs 必须小于 responseTimeoutMs。

验证

启动后向机器人发送：

/bot-ping
/bot-image-test
/bot-file-test

前者应返回 pong，其余两个命令应分别返回蓝色图片和文本文件。再发送“我当前有啥文件？”以及一张图片或普通文件，验证工具、图片和文件链路。最后请求一个需要审批的操作，并原样回复机器人给出的 /approve <短码> 或 /reject <短码>；同一回合应继续或停止，网页不应接管这次审批。

异步隔离可通过暂时让钉钉端点不可达来验证：日志应报告重连失败并按 reconnectDelayMs 重试，同时 Harness Web 必须继续返回 HTTP 200；网络恢复后钉钉连接应自行恢复。

会话兼容

0.1.1 使用新的 dingtalk-v2 session namespace。旧 dingtalk-v1 会话不会删除，仍保留在 Harness 持久化目录中；钉钉通道不再向这些可能已被旧实现污染的会话追加事件，而是从干净的 v2 会话开始。/new 会创建新的持久会话并保留已有记录。

安全说明

• Stream 回调会立即确认，避免钉钉重复投递；业务消息 ID 也会去重。
• sessionWebhook 只用于当前消息回复，不记录、不持久化、不发送给模型。
• 媒体下载和上传均使用钉钉官方 API；兼容其认证接口返回的 HTTP/HTTPS 临时签名下载地址，图片和普通文件均有数量与大小限制。
• 入站文件使用安全文件名和私有目录保存；出站只接受最终回复中明确链接的当前工作目录内普通文件，并阻止符号链接逃逸。
• 生产环境应配合 Harness 最小工具权限和工作目录限制。

开发

pnpm install
pnpm run check
pnpm pack

仓库使用 PNPM 10.33.4；插件运行时要求 Node.js >=22.19，不要求 PNPM 11。

协议、消息格式和媒体流程参考钉钉官方 DingTalk-Real-AI/dingtalk-openclaw-connector v0.8.24。本项目使用 MIT 许可证。