Introduction

When developing agents in DeepSeek Harness (DSH), you often encounter situations where you need to leave your machine but still want to check agent status, dispatch tasks, execute commands, and receive screenshots. Existing methods usually rely on local terminal or panel access. dsh-qq-remote provides another entry point: sending commands to DSH via QQ messages, which are then bridged to the plugin via OneBot 11. Below is an introduction to its positioning, environment requirements, installation and configuration, and typical usage.

Positioning

dsh-qq-remote is a DSH plugin, repository address is https://github.com/ASAKAFENG/dsh-qq-remote, license is MIT. It implements remote control via QQ messages, mainly including:

  • Execute shell commands and return output: /exec
  • Dispatch tasks to the current DSH agent session: /ask
  • View agent status and recent progress: /status, /progress
  • Phase reporting and automatic progress push: phase mode
  • Session title management: /sessions, /session, /title, /newsession
  • AI chat mode and chat-specialized sessions: /chat, /chatbind
  • Cancel tasks: /cancel
  • Screenshot return: /screenshot
  • Agent actively sends text or screenshots to QQ: qq_report, qq_screenshot
  • QQ graphical control panel and QR code login recovery: /panel

It does not contain a QQ protocol implementation and requires a OneBot 11 implementation such as NapCat, Lagrange.OneBot, go-cqhttp, or LLOneBot as the QQ bridge.

Environment Requirements

The plugin requirements are as follows:

  • Node.js >= 22, using built-in WebSocket / fetch, zero npm dependencies
  • Hosted in a DSH environment, providing @deepseek-ai/* peer dependencies
  • Any OneBot 11 implementation: NapCat, Lagrange.OneBot, go-cqhttp, LLOneBot
  • Platforms: Full support for Linux; Core features available for macOS / Windows; Installation verified on Ubuntu

Installation and Setup

First, prepare the QQ bridge. Taking NapCat as an example:

  1. Install and start NapCat, complete the bot QQ scan code login.

  2. Add a WebSocket server in the NapCat WebUI:

127.0.0.1:3001
Path: /ws
Message format: array
  1. Clone the plugin and run the installation script:
git clone https://github.com/ASAKAFENG/dsh-qq-remote
cd dsh-qq-remote
bash scripts/install.sh

  1. Configure the whitelist. You can add your QQ number in the DSH Settings page “QQ Remote” panel, or edit the allowedUsers in ~/.dsh/qq-remote.json.

  2. Send /ping via QQ; receiving pong indicates connectivity.

After the steps above, you can use the following commands to verify the basic connection:

/ask help me organize desktop files
/exec ls -la
/screenshot

Whitelist and Configuration

allowedUsers is a critical configuration item. If allowedUsers is left empty, any QQ number can control your computer.

The overlay configuration file path is:

~/.dsh/qq-remote.json

Verified configuration field examples provided by documentation include:

{
  "wsUrl": "ws://127.0.0.1:3001/ws",
  "allowedUsers": [123456789],
  "groupPrefix": "/",
  "privatePlainAsTask": true,
  "autoReport": true,
  "reportMode": "phase",
  "chatHistoryLimit": 0,
  "chatMaxChars": 0,
  "chatSessionNames": []
}

In the default example [123456789] in allowedUsers, any message will be allowed, be sure to replace it with your own QQ number. reportMode is used for phase mode. See USAGE.md for the complete configuration options.

Common Commands

Below are the verified common commands:

  • /ping: Connectivity test, success is indicated by a pong reply
  • /ask <task>: Dispatch a task to the current DSH agent session
  • /exec <command>: Execute a shell command on the computer and return the output
  • /status: View agent status
  • /progress: View recent progress
  • /screenshot: Take a screenshot and send it
  • /cancel: Cancel the current task
  • /sessions: List sessions
  • /session <title or id>: Switch to the target session
  • /title <name>: Rename the current target session
  • /newsession: Create a new session
  • /chat on: Enable AI chat mode
  • /chat off: Disable AI chat mode
  • /chatbind on: Enable chat-specialized sessions
  • /chatbind off: Disable chat-specialized sessions
  • /panel: Open the QQ graphical control panel

Phase Reporting and Active Sending

The plugin supports phase mode for phase reporting and automatic progress pushing. The Agent can also actively call qq_report, qq_screenshot in a session to send text or screenshots to QQ.

Login Failure Recovery

When login fails, use /panel to open the QQ graphical control panel. The QR code is valid for about 2 minutes; it can be refreshed automatically or rescanned to recover after expiration.

Security and Use Cases

This plugin has high permissions: it can remotely execute commands, take screenshots, and view files via QQ. Since it relies on the DSH process’s local execution capabilities, permissions depend on the current DSH process and system environment and should be treated as a high-privilege tool.

Recommendations before use:

  1. The allowedUsers whitelist must be configured.

  2. It is strongly recommended to use a secondary account or a dedicated bot QQ account to avoid risk control or account bans on your main account.

  3. Check the source code before installation and confirm that the MIT license meets your usage requirements.

It is suitable for the following scenarios:

  • Checking DSH agent status and recent progress via QQ when away from the computer
  • Dispatching tasks, executing commands, and canceling tasks on a mobile phone
  • Receiving screen screenshots
  • Performing AI chat or switching sessions via QQ
  • Having NapCat or another OneBot 11 implementation as the QQ bridge

Conclusion

dsh-qq-remote consolidates DSH remote operations into the QQ messaging chain, suitable as a remote control entry point on a personal development machine. Since it can execute commands and screenshots, be sure to configure the whitelist first, then test with a secondary account.

Repository address: https://github.com/ASAKAFENG/dsh-qq-remote