Introduction

The core design philosophy of DeepSeek Harness (DSH) is “everything is a plugin.” When interacting with an agent on a Telegram Bot, manually writing bridge code involves extensive Bot API call logic and requires handling details such as session mapping and long-running task queues. dsh-channel-telegram provides a standalone solution by receiving private chat messages via long polling and mapping Telegram chats to DSH agent sessions, without requiring source code changes to DSH.

Plugin Role

This is a thin Telegram bridge plugin maintained by LosEcher. It exposes DSH agents through a Telegram Bot and uses the exact same driver model as the ACP bridge (agents.create → agent.followup → agent.whenIdle), returning the final assistant text. The plugin is delivered standalone, and DSH’s Host loader supports absolute-path plugin entries.

Core Features

Based on verified facts, the plugin provides the following capabilities:
* Receives private chat messages via long polling.
* Maps DSH agent sessions by chatId, with session ID telegram-<chatId>.
* Serial queue for long-running tasks: one queue per chat, so long-running tasks do not block polling.
* Supports commands: /start, /help, /new, /status.
* Chunked message replies at 4096 characters.
* Automatic handling of 409/401 errors.

Installation and Enablement

The plugin is provided as a standalone bundle and does not involve official installation commands. The enablement workflow is as follows:

  1. Obtain a Bot Token
    Find @BotFather on Telegram, create a bot, and obtain its Token.

  2. Configure Environment Variables
    Ensure the environment variables for the DSH process include TELEGRAM_BOT_TOKEN (the default variable name; it can be changed via tokenEnv). If importing source code for development via an absolute path, ensure name is an absolute path.

  3. Obtain Your Chat ID
    Send any message to @userinfobot to obtain the chatId used for configuration.

  4. Merge the Configuration File
    Merge the plugin’s cordis.telegram.yml contents into DSH’s configuration file. Usually merge it into $DSH_HOME/cordis.patch.yml (all profiles) or $DSH_HOME/profiles/<name>/cordis.patch.yml (a single profile). Fill the allowlist in the configuration with your private chat ID (an empty array denies all).

  5. Restart the Service
    Restart dsh web. The logs should show [dsh-channel-telegram] connected as @....

- insert:
    - id: channel-telegram
      name: dsh-channel-telegram
      config:
        tokenEnv: TELEGRAM_BOT_TOKEN
        allowlist: [123456789]            # 你的私聊 id
        # workspace: /abs/path            # 可选，agent 会话 cwd（默认 ~/.dsh-telegram/workspace）
        # provider: los-gateway           # 可选：agent 走的 provider 路由
        # model: deepseek                 # 可选：该路由上的模型

Typical Usage

After configuration, you can interact with the Bot via private chat.

  • Session management: Each private chat corresponds to one telegram-<chatId> session with continuous context. Use the /new command to destroy and recreate the session.
  • Command responses:
    • /start: Start the session.
    • /help: View help.
    • /new: Destroy the current session and create a new one.
    • /status: View the current session status.
  • Message replies: The Bot sends a typing action and sends the assistant text after the full response completes. If the assistant text exceeds 4096 characters, it is automatically chunked and sent.

Use Cases and Notes

  • Dependency requirement: Depends on @deepseek-ai/cordis (>=4.0.0 <5.0.0).
  • Functional limitations:
    • No streaming output: It waits until the entire task round completes before replying.
    • No media handling: Currently only text message reception is supported.
    • In-memory sessions: Session mappings are stored in memory, and after restarting the DSH process the /new semantics are naturally achieved (i.e., a new process requires configuring the allowlist again).
    • Message deduplication: Relies on the Bot API offset mechanism to avoid redelivery, but DSH has no additional deduplication logic.
  • Security mechanism: The allowlist is the only security gate. Private chats not on the allowlist receive an “unauthorized” notice for the first time, and non-private-chat messages are ignored. The agent inherits the host’s global permission settings; running it under a low-privilege preset or a separate profile is recommended.

Conclusion

dsh-channel-telegram provides DSH with standardized Telegram interaction capabilities through long polling and a thin bridge design. It focuses on private-chat scenarios and, through command and session-management mechanisms, provides necessary functional coverage while remaining lightweight. For users who need to invoke DSH agents through Telegram, this is a directly integrable option.