Introduction

When integrating a DeepSeek Harness (DSH) Agent into DingTalk, common challenges involve handling public network callbacks, message parsing, media downloads, tool approvals, and session isolation on the channel side. deepseek-harness-dingtalk is a DingTalk channel plugin for DSH that uses the official Stream WebSocket connection, eliminating the need for a public callback server. The application bot only needs a Client ID and Client Secret to connect and send text, Markdown, rich text, speech-to-text, images, and regular files to the DSH Agent.

What is this

Maintained by sliverp, deepseek-harness-dingtalk is licensed under MIT. Its one-sentence positioning is: DingTalk Stream text, image, and file channel bridge for DeepSeek Harness. It solves the channel adaptation between the DSH Agent and DingTalk sessions: input, output, media, approvals, and sessions are all handled on the DingTalk side.

Core Capabilities

Input and Media

The plugin supports the following inputs:

  • Text
  • Markdown
  • Rich text
  • Speech-to-text
  • Images
  • Regular files

For images and files, the plugin uses the official downloadCode to retrieve them. Regular files are safely stored in the Agent workspace. Multimodal inputs are processed based on the model’s capabilities and retain text-only fallback metadata.

Output and Execution

The plugin supports:

  • Native DingTalk Markdown replies
  • Generated image uploads
  • Workspace file uploads
  • Full Harness Agent Loop execution
  • Structured tool events
  • final-visible-reply-only delivery

Sessions are persistent and isolated, restoring the corresponding Agent preset and borrowing an existing live Agent writer.

Approvals and Commands

Tool approvals are completed within the same session using one-time codes:

/approve <code>
/reject <code>

The plugin also supports /new, registered Harness slash commands, and the following check commands:

/bot-ping
/bot-help
/bot-image-test
/bot-file-test
/bot-status
/bot-cancel

Startup and Fault Tolerance

The Client Secret is parsed via the Harness credential service. If the Client ID or Client Secret is not configured, the plugin starts in a dormant state; installing it alone does not block Harness Web.

The connection side uses the official Stream WebSocket and heartbeat, with a plugin-supervised reconnection that includes handling for SDK promise failures. When credentials are missing or invalid, the channel goes offline and logs errors but does not prevent Harness from starting.

Environment Requirements

Before running, ensure the following:

Node.js 22.19 or later
pnpm 10.33.4
DeepSeek Harness 0.1.0-rc.7 or later

The current version number in package.json is 0.1.5.

Installation and Enablement

After confirming the version, add the plugin:

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

If using a local checkout, you can use an absolute path:

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

Configure DingTalk Application

First complete the DingTalk application configuration, then configure the DSH credentials.

  1. Open the DingTalk Developer Console and create an internal application.
  2. Add bot capabilities, or use the official DingTalk one-click OpenClaw robot application flow.
  3. Copy the Client ID (formerly AppKey) and Client Secret (formerly AppSecret) from the credentials page.
  4. Place the Client ID into DINGTALK_CLIENT_ID and store the Client Secret in the Harness credential reference DINGTALK_CLIENT_SECRET.

For development environments, you can use environment variables:

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

For long-term use, it is recommended to put the Client ID into ~/.dsh/.env and save the Client Secret via the Harness credential settings interface. Do not commit credentials.

Verification

After configuration, first send:

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

Then send a question with an image or regular file to check the tools, images, and file paths:

What files do I have?

If you need to verify approvals, you can request an action that requires approval, then reply with the precise code given by the plugin:

/approve <code>
/reject <code>

The approval code is used for one-time decisions within the same session.

Strategy and Timeout

Direct chat and group chat strategies accept open, allowlist, or disabled. When enabling the allowlist, it should be used in conjunction with Harness tools and workspace permissions with the least privilege.

If approval timeout is configured, approvalTimeoutMs must be less than responseTimeoutMs.

Security Boundaries

The plugin’s security handling includes:

  • sessionWebhook is only used for the corresponding original reply, not recorded, not persisted, and not exposed to the model.
  • Media transmission uses the official DingTalk API, including authenticated HTTP/HTTPS signed download URLs; images and files have quantity and byte limits.
  • Inbound files use safe filenames and private directories.
  • Outbound files only accept regular files explicitly linked within the current workspace and reject symlink escape.
  • When credentials are missing or invalid, the channel goes offline and logs errors but does not prevent Harness from starting.

Session Namespace

The 0.1.1 update in the README introduces the new dingtalk-v2 session namespace. The old dingtalk-v1 sessions will not be deleted and continue to be retained in Harness persistence; however, this channel will no longer append content to these potentially polluted sessions, but instead start from a clean v2 session. /new can create another durable session while preserving existing records.

The current version number in package.json is 0.1.5; please verify the session migration relationships between versions against the corresponding version documentation.

Applicable Scenarios and Notes

Suitable for:

  • Developers who want to connect a DSH Agent to DingTalk sessions.
  • Channels requiring text, Markdown, rich text, speech-to-text, images, and regular file inputs.
  • Scenarios requiring tool approvals, session isolation, and media input/output processing on the DingTalk side.

Notes before use:

  • The plugin runs with the permissions of the current DSH process; check the source code, dependencies, and MIT license before installing.
  • Do not commit Client ID or Client Secret to the repository.
  • The allowlist should be used with Harness tools and workspace permissions with the least privilege.
  • The community directory is an independent site with no official affiliation with DeepSeek / Huanfang; it should not be interpreted as an official app store.

Links