openclaw-channel-telegram-userbot

OpenClaw channel plugin that connects your personal Telegram account (not a bot) to OpenClaw via MTProto. Your AI assistant responds as you — from your real Telegram account.

Features

• MTProto via GramJS — full Telegram user API, not the limited Bot API
• Media support — photos, videos, documents, voice, stickers, animations (inbound & outbound)
• Reply context — AI sees the quoted message when someone replies
• Conversation memory — multi-turn context with configurable history depth, persisted to disk
• System prompts — per-chat or global system prompt for AI personality
• Markdown formatting — bold, italic, code, strikethrough, spoilers in AI responses
• DM and group chat support — with configurable mention requirements
• Machine-bound session encryption — AES-256-GCM, sessions are useless on another device
• Human-like reply delay — configurable pause + typing indicator before responding
• Chat allowlist / denylist — control which chats the assistant can access
• Per-group settings — different behavior for different groups

Requirements

• OpenClaw >= 2026.3.0
• Telegram API credentials from my.telegram.org
• Bun >= 1.0 or Node.js >= 22

Installation

openclaw plugins install openclaw-channel-telegram-userbot

Setup

1. Get Telegram API credentials

Go to my.telegram.org, create an app, and note the api_id and api_hash.

2. Generate session string

cd openclaw-channel-telegram-userbot
bun run src/auth.ts

Follow the prompts to log in. You'll receive a session string (optionally encrypted with your machine ID).

3. Configure OpenClaw

openclaw config set channels.telegram-userbot.apiId 12345678
openclaw config set channels.telegram-userbot.apiHash "your_api_hash"
openclaw config set channels.telegram-userbot.sessionString "your_session_string"

Or add to ~/.openclaw/openclaw.json:

{
  channels: {
    "telegram-userbot": {
      apiId: 12345678,
      apiHash: "abc123...",
      sessionString: "1BQA...",
      allowFrom: ["*"],
      replyDelaySec: 2,
      groups: {
        "*": { requireMention: true }
      }
    }
  }
}

4. Enable and restart

openclaw plugins enable telegram-userbot

Configuration

| Key | Type | Default | Description | |-----|------|---------|-------------| | apiId | number | required | Telegram API ID | | apiHash | string | required | Telegram API Hash | | sessionString | string | required | GramJS session (from auth helper) | | allowFrom | string[] | ["*"] | Allowed chat IDs (* = all) | | denyFrom | string[] | [] | Denied chat IDs (overrides allowFrom) | | replyDelaySec | number | 2 | Delay before reply (seconds) | | groups | object | {} | Per-group settings | | groups.*.requireMention | boolean | false | Only respond when mentioned | | groups.*.enabled | boolean | true | Enable/disable group | | conversations.maxMessages | number | 20 | Max messages per chat history | | conversations.defaultSystemPrompt | string | "" | System prompt for all chats | | conversations.systemPrompts | object | {} | Per-chat system prompts | | conversations.dataDir | string | ~/.openclaw/telegram-userbot | History storage path |

Security

Session strings are encrypted with your machine's hardware ID by default (AES-256-GCM via node-machine-id). Encrypted sessions are useless if copied to another machine.

Override with a custom key:

export OPENCLAW_TELEGRAM_SESSION_KEY=my-secret-key

Conversation data: History is stored in ~/.openclaw/telegram-userbot/ as JSON files. These may contain sensitive chat content. Ensure appropriate file permissions on multi-user systems.

Recommendations:

• Use a secondary Telegram account
• Check Telegram → Settings → Devices periodically
• Use allowFrom / denyFrom to limit access
• Set replyDelaySec > 0 to avoid rate limits

Development

bun install
bun run lint         # check code with Biome
bun run lint:fix     # auto-fix
bun run typecheck    # TypeScript check
bun test             # run tests

License

MIT

Related

• mcp-telegram — Telegram MCP server (59 tools)
• mcp-whatsapp — WhatsApp MCP server