Claude Agent SDK - Telegram Bot (Minimal 100-line Version)

Transform Claude Code into a free, enhanced Clawdbot alternative

A Telegram bot powered by Claude Agent SDK. Get Claude Code running on Telegram in 15 minutes.

中文文档 / Chinese Documentation

Why Not Just Use Clawdbot?

Comparison	Clawdbot	This Project
Cost	Free	Free (uses your existing Claude quota)
Data Privacy	Free	Free, self-hosted data
Extensibility	Wait for official updates	Add any feature with Claude Code
Configuration	Complex backend setup	Single .env file

In short: Everything Clawdbot can do, Claude Code can do — with better extensibility!

Architecture

┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│  Telegram   │ ───▶ │  Bot Server │ ───▶ │ Claude Code │
│ (Your Phone)│ ◀─── │(Your Machine│ ◀─── │    (AI)     │
└─────────────┘      └─────────────┘      └─────────────┘

The bot is just a "messenger" — the real work is done by Claude Code.

Features

• Session Memory: Multi-turn conversation context (via SDK session resume)
• Tool Calling: WebSearch, WebFetch, Read, Bash and more
• Multi-User: Independent sessions per Telegram chat
• Long Messages: Auto-splits responses over 4000 characters
• Proxy Support: HTTPS proxy configuration

Quick Start (15 minutes)

1. Clone the Project

git clone https://github.com/liangyimingcom/ClaudeAgentSDK-TelegramBot.git
cd ClaudeAgentSDK-TelegramBot

Or download ZIP: Click to Download

2. Install Dependencies

npm install

3. Create a Telegram Bot

1. Search for @BotFather on Telegram
2. Send /newbot and follow the prompts
3. Get your Bot Token

4. Configure Environment Variables

Copy the example config file:

cp .env.example .env

Edit the .env file:

# Required: Telegram Bot Token
TELEGRAM_BOT_TOKEN=your_bot_token

# Claude API Configuration (Choose One)
# Option 1: Anthropic API
# ANTHROPIC_API_KEY=sk-ant-xxxxx
# HTTPS_PROXY=http://127.0.0.1:7890  # Optional: Proxy (required in China)

# Option 2: Bedrock + LiteLLM
# CLAUDE_CODE_USE_BEDROCK=1
# ANTHROPIC_BEDROCK_BASE_URL=http://your-url:4000/bedrock
# CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
# ANTHROPIC_AUTH_TOKEN=your_token

5. Run

node bot.mjs

When you see 🚀 Bot started successfully!, you can start chatting with your bot on Telegram!

📋 Detailed Setup Steps (From Scratch)

If you want to create the project from scratch instead of cloning this repository, follow these steps:

Step 1: Create Project Folder

# Create a new folder
mkdir claude-telegram-bot
cd claude-telegram-bot

Step 2: Initialize Project and Install Dependencies

# Initialize npm project
npm init -y

# Install required dependencies
npm install node-telegram-bot-api @anthropic-ai/claude-agent-sdk dotenv

Step 3: Create Configuration File

Create a .env file and fill in your configuration (refer to the Configure Environment Variables section above).

Step 4: Create bot.mjs

Copy the bot.mjs file from this repository to your project directory, or implement it yourself based on the source code.

Step 5: Run

node bot.mjs

Bot Commands

Command	Description
/start	Start conversation
/clear	Clear conversation history

What Can It Do?

Since it's powered by the full Claude Code, it can do a lot:

• 🔍 Web Search: Search for the latest information
• 📁 File Operations: Read and write local files
• 💻 Execute Commands: Run Bash commands
• 🎵 Download Media: YouTube, Bilibili MP3 downloads
• 📅 Calendar Management: Interact with calendar apps
• 🔧 Anything You Can Imagine: Tell Claude Code what you want, it'll help you build it!

Security Warning

⚠️ In bypassPermissions mode, Claude can execute arbitrary commands.

• Do not run on your primary machine
• Recommended to use a virtual machine or container
• Remember to stop the bot after testing

How It Works

Message Processing Flow

flowchart TD
    A[User sends message] --> B{Is it a command?}
    B -->|/start| C[Return welcome message]
    B -->|/clear| D[Clear session history]
    B -->|Normal message| E[Show typing...]

    E --> F{Existing session?}
    F -->|Yes| G[Resume context with session ID]
    F -->|No| H[Create new session]

    G --> I[Call Claude Agent SDK]
    H --> I

    I --> J[Stream response]
    J --> K[Capture session_id]
    K --> L[Get final result]

    L --> M{Response length > 4000?}
    M -->|Yes| N[Split and send chunks]
    M -->|No| O[Send directly]

    N --> P[Save session_id]
    O --> P
    P --> Q[Wait for next message]

Loading

Session Management

sequenceDiagram
    participant U as User
    participant T as Telegram
    participant B as Bot Server
    participant S as chatSessions Map
    participant C as Claude Agent SDK

    U->>T: Send first message
    T->>B: Forward message
    B->>S: Query chatId
    S-->>B: No session found
    B->>C: query(prompt)
    C-->>B: Return session_id + result
    B->>S: Save session_id
    B->>T: Send reply
    T->>U: Display reply

    U->>T: Send second message
    T->>B: Forward message
    B->>S: Query chatId
    S-->>B: Return session_id
    B->>C: query(prompt, resume: session_id)
    C-->>B: Restore context + return result
    B->>T: Send reply
    T->>U: Display reply (with context)

Loading

Core Code Logic

Component	Purpose	Location
chatSessions	Map storing chatId → sessionId	bot.mjs:19
query()	Claude Agent SDK core function	bot.mjs:75
resume	Parameter to restore session context	bot.mjs:70
session_id	Session identifier from SDK	bot.mjs:77
Message chunking	Handle Telegram's 4096 char limit	bot.mjs:95-99

Related

• Anthropic - Claude Agent SDK

License

MIT