dailytutorfor.you
Web Development

Claude Code Telegram Plugin: Complete Setup Guide 2026 (Production-Ready)

A complete guide to setting up the Claude Code Telegram Plugin from zero to production-ready: from BotFather, plugin installation, and pairing to allowlist hardening and operational best practices so it stays secure and stable for daily use.

7 min read

Claude Code Telegram Plugin: Complete Setup Guide 2026 (Production-Ready)

Have you ever thought, "what if I could chat with Claude Code directly from Telegram, so I can control it from my phone anytime?"
The good news: this is no longer an experiment — it’s now a very realistic workflow for solo developers and small teams.

In this tutorial, we’ll cover the end-to-end setup of the Claude Code Telegram plugin until it’s ready for daily use, plus security hardening so your bot doesn’t become an entry point for strangers.

We’ll also complement the context with several official references: Telegram plugin documentation, BotFather/Telegram Bot API fundamentals, and operational insights from modern gateway/chat-agent implementations.

Prerequisites

Before you begin, make sure you already have:

  1. An active Telegram account
  2. Access to a Claude Code session (on local machine/VPS)
  3. A runtime supported by the plugin (commonly Bun for certain plugin servers)
  4. Terminal access
  5. A stable internet connection

Optional but highly recommended:

  • Tailscale / private network if you want secure cross-device access
  • A session manager (tmux/screen/systemd) so the process stays alive
  • Basic log monitoring

Core Concepts (So You Don’t Use the Wrong Mental Model)

Before jumping into setup, understand the architecture first:

  • Telegram Bot = your public chat endpoint (created via BotFather)
  • Plugin / MCP server = bridge between Telegram and Claude Code
  • Claude Code session = the “brain” that processes prompts

Simple flow:

[Telegram User]
     |
     v
[Telegram Bot API]
     |
     v
[Telegram Plugin / MCP Bridge]
     |
     v
[Claude Code Session]
     |
     v
[Reply back to Telegram]

Why is this powerful?

Because you can:

  • send instructions from your phone,
  • check progress,
  • update/react/edit messages,
  • and still keep your main coding environment on your server/laptop.

Step-by-Step Setup

1) Create a Bot in BotFather

Chat with @BotFather, then run:

/newbot

Fill in:

  • Bot name (anything)
  • Bot username (must end with bot)

You’ll get a token like:

123456789:AAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Store this token like a password. Don’t put it in a public repository.

2) Install the Telegram Plugin in Claude Code

Enter your Claude Code session, then install the official Telegram plugin.

Example commands (adjust to your environment):

/plugin install telegram@claude-plugins-official
/reload-plugins

If plugin commands don’t appear yet, restart your Claude Code session.

3) Configure the Bot Token

Set the token for the plugin:

/telegram:configure <BOT_TOKEN>

Usually, the token is stored at a path like:

~/.claude/channels/telegram/.env

Minimum content:

TELEGRAM_BOT_TOKEN=123456789:AAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

4) Relaunch Claude Code with Channel Flag

To enable the Telegram channel, run Claude Code with the Telegram plugin channel.

Example:

claude --channels plugin:telegram@claude-plugins-official

If you use a service manager, this flag must be included in your service startup command.

5) Pairing Telegram User

By default, many setups use pairing mode first.

Common flow:

  1. DM your bot from Telegram
  2. Get a pairing code
  3. Submit the pairing code from Claude/plugin command side

Example:

/telegram:access pair ABC123

After success, messages from your Telegram account will be forwarded to the assistant.

6) Hardening: Switch to Allowlist

After pairing succeeds, don’t leave pairing/open policy enabled forever.

Set the policy to allowlist:

/telegram:access policy allowlist

Then make sure only authorized user IDs can access.

Access policy concept:

  • pairing → safe for initial onboarding
  • allowlist → safe for production
  • open → do not use except in a closed experiment environment

Recommended Production Architecture

                    Internet
                       |
                [Telegram Cloud]
                       |
                [Bot API Traffic]
                       |
             +---------------------+
             |  VPS / Home Server  |
             |---------------------|
             | Claude Code Session |
             | Telegram Plugin     |
             | Logs + Monitoring   |
             +---------------------+
                       |
             (Optional Private Access)
                       |
                   [Tailscale]

If this is used daily:

  • run the session via systemd/tmux,
  • store logs,
  • restrict who can DM the bot,
  • and rotate the token if there are signs of leakage.

Real Workflow Example

For example, you’re outside and only have your phone:

A) Trigger a coding task

"Refactor the auth service so refresh tokens use rotation, then send me a summary of changes."

B) Ask for status

"How far along is it? test result?"

C) Finalize

"Send the final summary + list of modified files."

This is very useful for async workflows, especially if you develop while mobile.

Best Practices (To Keep It Stable)

  1. Always start private, then open selectively
    Start with pairing + allowlist, not open.

  2. Separate production bot vs experimental bot
    Don’t mix important channels with playgrounds.

  3. Use user ID, not username, for policy
    Usernames can change; user IDs are more stable.

  4. Enable simple observability
    Log incoming/outgoing events + errors for faster debugging.

  5. Limit sensitive commands
    If there are high-risk tools/actions, use approval checkpoints.

  6. Rotate bot token periodically
    At minimum whenever suspicious access appears.

Common Mistakes (Happens Very Often)

❌ 1) Forgetting to relaunch with the channel flag

Symptom: bot is online, but Claude doesn’t respond.

Fix: ensure your launch command actually includes the Telegram plugin channel.

❌ 2) Staying in pairing/open mode too long

Symptom: random users can trigger the pairing flow.

Fix: once pairing succeeds, immediately switch to allowlist.

❌ 3) Storing token in the wrong place

Symptom: token gets captured in shell history / repository.

Fix: store it in a secure env file, never commit it to git.

❌ 4) Assuming the bot can read old history

In common Telegram Bot API practice, it is more event-driven (push when messages arrive), not full historical search.

Fix: for old context, send a manual summary to the bot.

❌ 5) No process supervisor

Symptom: session dies when SSH disconnects / machine reboots.

Fix: use tmux or a systemd service.

Advanced Tips

1) Run with systemd (Linux)

Example unit service:

[Unit]
Description=Claude Code Telegram Channel
After=network.target

[Service]
User=dev
WorkingDirectory=/home/dev
Environment=TELEGRAM_BOT_TOKEN=123456789:AAxxxxxxxxxxxxxxxx
ExecStart=/usr/local/bin/claude --channels plugin:telegram@claude-plugins-official
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Enable:

sudo systemctl daemon-reload
sudo systemctl enable claude-telegram.service
sudo systemctl start claude-telegram.service
sudo systemctl status claude-telegram.service

2) Segment access per environment

  • Bot A: production
  • Bot B: staging/testing

With this, if the test bot gets messy, production is not affected.

3) Incident playbook (must have)

If you suspect the bot is accessed by unauthorized parties:

  1. revoke token via BotFather
  2. update token in config
  3. restart service
  4. audit logs from the last 24 hours
  5. reset allowlist if needed

Quick Deployment Checklist

  • Bot created via BotFather
  • Telegram plugin installed
  • Token stored securely
  • Session relaunched with channel flag
  • Pairing successful
  • Policy switched to allowlist
  • Valid user IDs verified
  • Persistent service (tmux/systemd)
  • Basic logging enabled

If all checklist items are green, your setup is ready for daily use.

Summary & Next Steps

In this tutorial you’ve learned:

  • how to set up the Claude Code Telegram plugin from scratch,
  • how to pair a Telegram account with the assistant,
  • how to harden security with allowlist,
  • and production practices to keep it stable.

Next steps I recommend:

  1. Add observability (alerts when service is down)
  2. Implement approval checkpoints for high-risk actions
  3. Separate prod and staging bots
  4. Integrate with your coding workflow (daily command templates)

If you want, in the next stage we can create an operational SOP template (new user onboarding, token rotation, incident response) so this setup is ready for team use, not just personal use.

References

  1. Dev.to – Claude Code Telegram Official Plugin: Complete Setup Guide 2026
    https://dev.to/czmilo/claude-code-telegram-plugin-complete-setup-guide-2026-3j0p

  2. Anthropic official plugin repository (Telegram plugin docs & access policy)
    https://github.com/anthropics/claude-plugins-official

  3. Telegram Bot API tutorial (BotFather/token fundamentals)
    https://core.telegram.org/bots/tutorial

  4. OpenClaw docs (operational context for chat-agent gateway patterns)
    https://docs.openclaw.ai