Introduction

DeepSeek Harness (DSH) uses a plugin-based architecture and provides scenario-specific integration through extensible capabilities. Integrating DSH with a QQ Bot requires handling protocol conversion and session management. The dsh-qqbot plugin supports dual transport channels: OneBot 11 (forward WebSocket from NapCat/Lagrange, etc.) and the official QQ Open Platform (q.qq.com). It allows each QQ conversation to map to a persistent Agent, supports the full toolchain including files, Shell, and web access, and allows the Agent to proactively send messages.

Core Features

  • Dual-channel access: Supports OneBot 11 protocol endpoints (NapCat, Lagrange, etc.) and the official QQ Open Platform (direct AppID/AppSecret connection).
  • Persistent sessions: Each QQ conversation (private chat, group chat, channel) maps to an independent Agent, with history retained across restarts.
  • Full toolchain: Mounts DSH presets (default standard), providing file read/write, Shell/PowerShell, web search, sub-agents, task lists, and more.
  • Active messaging: Registers the qq_send tool, allowing the Agent to proactively report or ask questions to the conversation partner.
  • Local commands: Supports local commands such as #help, #status, and #reset.

Installation and Configuration

1. Prepare the QQ Endpoint

  • OneBot channel: Choose a protocol implementation such as NapCat or Lagrange, enable forward WebSocket, and obtain the URL and token.
  • Official channel: Create a bot on the QQ Open Platform and obtain the AppID and AppSecret.

2. Install the Plugin

Run the installation command under the DSH web profile:

dsh plugin --profile web add file:C:\path\to\dsh-qqbot

After installation, restart the dsh web process. The installation is successful when the startup log shows qqbot: connected to ....

3. Configuration

Configuration can be completed using environment variables or cordis.patch.yml.

OneBot channel (default):

set QQBOT_WS_URL=ws://127.0.0.1:3001
set QQBOT_ACCESS_TOKEN=你的token
dsh web

QQ official channel:

set QQBOT_TRANSPORT=official
set QQBOT_APP_ID=你的AppID
set QQBOT_APP_SECRET=你的AppSecret
dsh web

Or edit $DSH_HOME/profiles/web/cordis.patch.yml:

- id: qqbot
  config:
    transport: official
    appId: '你的AppID'
    clientSecret: '你的AppSecret'
    allowedGroups: []  # 限制回复群组，空为全部
    allowedUsers: []  # 限制私聊用户，空为全部

Usage

  • Regular conversation: Send any message to the bot, and the current session’s Agent will process and reply.
  • Check status: Enter #status to view the access channel, connection, and session status.
  • Reset session: Enter #reset to clear the current session context.
  • Agent active messages: The Agent can call the qq_send tool to send text to the current conversation.

Notes

  • Security restriction: The QQ bot entry point has no authentication, and anyone who can send a message can invoke Agent capabilities (including Shell). You must restrict the scope using allowedUsers / allowedGroups.
  • Official channel restriction: The official QQ Open Platform disabled the active messaging capability from 2025-04-21, so qq_send will report an error under the official channel. The OneBot channel is not subject to this restriction.
  • Reply restriction: Official replies are subject to the platform reply window and the limit that the same incoming message can be replied to at most 5 times; the plugin will refuse chunked sends exceeding 5 messages.
  • Working directory: The Agent’s working directory is by default located within the DSH sandbox root. If you modify workspaceRoot, ensure the path stays within the sandbox; otherwise, file-related tools will be blocked.

Conclusion

dsh-qqbot provides DSH users with a standardized QQ bot integration solution. With dual-channel support and a persistent Agent mechanism, it is suitable for development scenarios that require integrating large model capabilities into the QQ ecosystem. See the GitHub repository for more details.