OpenClaw Telegram Bot

An autonomous AI agent accessible through Telegram. Built with Upsonic following the OpenClaw philosophy: simple tools, agent-driven autonomy, and memory without limitations.

This is not a chatbot wrapper. It's a full autonomous agent with filesystem and shell access, controlled entirely through Telegram.

What It Can Do

• Remember conversation context between messages
• Run shell commands on your machine
• Read, write, and edit files in its workspace
• Build up its own memories over time via AGENTS.md

Prerequisites

• Python 3.10+
• uv package manager
• A Telegram account
• An ngrok account (free tier works)
• An OpenAI API key

Setup

Step 1: Install Dependencies

uv venv
uv pip install upsonic fastapi uvicorn

Step 2: Create a Telegram Bot and Get Your User ID

1. Open Telegram and search for @BotFather
2. Send /newbot and follow the prompts to pick a name and username
3. Copy the Bot API Token BotFather gives you

Now get your Telegram user ID:

1. Search for @userinfobot on Telegram
2. Send it any message
3. It replies with your numeric user ID — write it down

Why? This agent has filesystem and shell access on your machine. Locking it to your user ID ensures nobody else can interact with it.

Step 3: Set Up ngrok

Install ngrok:

# macOS
brew install ngrok

# Linux
snap install ngrok

# Windows
choco install ngrok

Create a free account at ngrok.com/signup, grab your authtoken, and run:

ngrok config add-authtoken YOUR_AUTH_TOKEN

Start the tunnel:

ngrok http 8000

You'll see output like:

Forwarding  https://abc123.ngrok-free.app -> http://localhost:8000

Copy that https://....ngrok-free.app URL. That's your public webhook endpoint.

Important: Keep this terminal open. If you close ngrok, the tunnel dies and your bot goes deaf. When you restart ngrok, the URL changes — update your .env accordingly.

Step 4: Configure Environment Variables

Copy the example env file and fill in your values:

cp .env.example .env

Edit .env:

TELEGRAM_BOT_TOKEN=your-bot-token-from-botfather
TELEGRAM_WEBHOOK_URL=https://abc123.ngrok-free.app
TELEGRAM_USER_ID=your-numeric-user-id
OPENAI_API_KEY=your-openai-api-key

Step 5: Set Up the Workspace

The workspace is the agent's home directory. All file and shell operations are sandboxed here.

Copy the included workspace to ~/my-agent-workspace:

cp -r workspace ~/my-agent-workspace

Your workspace will look like this:

~/my-agent-workspace/
├── AGENTS.md    # Agent behavior & guidelines
├── SOUL.md      # Agent identity
├── USER.md      # User context
└── memory/      # Daily logs will go here

Customize it: Edit AGENTS.md to change how your agent behaves. Edit SOUL.md to change who it is. No code changes needed.

Step 6: Run It

Make sure ngrok is running in one terminal, then in another:

uv run bot.py

Open Telegram, find your bot by its username, and start chatting.

Usage

Commands

• /reset — Clears the conversation history. The agent re-reads the workspace and sends a fresh greeting.

Example Messages

Since there's an actual autonomous agent behind Telegram, you can send messages like:

• "Find all TODO comments in the codebase"
• "Run the tests and tell me if anything fails"
• "Create a new file called hello.py with a hello world program"
• "Read the README and summarize it"
• "List all Python files in the project"

The agent uses its filesystem and shell tools to actually do these things and report back.

How It Works

• AutonomousAgent comes with built-in filesystem and shell tools — no extra config needed
• AGENTS.md is automatically loaded into the system prompt. The agent's personality and rules come from there
• InterfaceMode.CHAT means the agent remembers your conversation across messages
• allowed_user_ids locks the bot to your Telegram account only
• workspace points to the folder where the agent operates — it's sandboxed and can't escape

Project Structure

openclaw-telegram-bot/
├── bot.py            # Main entry point
├── .env.example      # Environment variables template
├── README.md         # This file
└── workspace/        # Agent workspace (copy to ~/my-agent-workspace)
    ├── AGENTS.md     # Agent behavior & guidelines
    ├── SOUL.md       # Agent identity
    ├── USER.md       # User context
    └── memory/       # Daily memory logs

Next Steps

• TASK mode: Switch InterfaceMode.CHAT to InterfaceMode.TASK for stateless one-off queries
• Custom tools: Give your agent domain-specific capabilities (API calls, database queries, deployment scripts)
• Heartbeat: Enable periodic check-ins by setting heartbeat=True on the AutonomousAgent

Full docs: docs.upsonic.ai