Deploy your own Telegram AI bot in 15 minutes

Telegram is the easiest place to put an AI agent in front of real people: bots are free, setup takes a minute, and there is no app review. The hard part is everything behind the bot — memory, tools, a safe place to run commands, and keeping each chat's history separate.

This tutorial walks through running your own Telegram AI bot on FastClaw, from an empty machine to a paired bot that remembers people and can use tools. You will need a computer (macOS, Linux or Windows), an API key for a model provider, and a Telegram account.

What you will end up with

• A FastClaw agent with its own personality, memory and skills.
• A Telegram bot connected to that agent, with each private chat and group keeping its own history.
• Owner pairing, so only your Telegram account gets owner access.
• The same agent available in the web console and over an OpenAI-compatible API.

Step 1: install FastClaw

FastClaw is a single binary. On macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/fastclaw-ai/fastclaw/main/install.sh | bash

The script drops fastclaw into ~/.local/bin and adds it to your PATH. On Windows, run the PowerShell installer from the README instead.

Step 2: first run and model provider

Start it in the foreground:

fastclaw

The first run opens a setup wizard. Pick a model provider — OpenAI, Anthropic, DeepSeek, OpenRouter, Ollama or any OpenAI-compatible API — paste a key, and the wizard creates your first agent. Running a local model with Ollama works too if you want nothing to leave the machine.

When the wizard is done, open the console at http://localhost:18953 and sign in.

To keep FastClaw running after you close the terminal:

fastclaw daemon start      # run in the background
fastclaw daemon install    # or register a launchd / systemd service

Prefer the command line? fastclaw agents init creates an agent and starts the gateway in one go:

fastclaw agents init tgbot \
  --provider openai \
  --model openai/gpt-4o-mini \
  --api-key-env OPENAI_API_KEY

Step 3: give the agent a personality

A bot that sounds like a generic assistant is forgettable. Open the agent in the console and edit its files:

• SOUL.md — who the agent is: tone, values, what it should and should not do.
• IDENTITY.md — name and short self-description.
• AGENTS.md — working rules, such as how to format replies for chat.

A good Telegram SOUL.md is short and specific. For example: reply in the user's language, keep answers under a few paragraphs, use bullet lists rather than tables (Telegram renders tables poorly), and ask a clarifying question instead of guessing.

You can also upload these files from the CLI with fastclaw agents files put tgbot SOUL.md ./SOUL.md. More on agent files in Agents.

Step 4: create the bot in Telegram

1. Open a chat with @BotFather in Telegram.
2. Send /newbot, choose a display name, then a username ending in bot.
3. BotFather replies with an HTTP API token. Copy it and keep it secret — anyone with it controls the bot.

Optional but useful: send /setdescription and /setuserpic to BotFather so the bot looks finished.

Step 5: bind the bot to your agent

In the console, open your agent and go to Channels, choose Telegram and paste the token.

FastClaw calls Telegram's getMe before saving, so a mistyped or revoked token is rejected immediately instead of producing a silent, dead bot. It also clears any old webhook and uses long polling, which means you do not need a public URL, a domain or an open port. A laptop behind home Wi-Fi works.

Details for this channel live on the Telegram integration page.

Step 6: pair the bot with your account

Connecting a bot proves you control the token, not which Telegram account is yours. So a freshly connected bot answers everyone with a "not paired" notice and routes nothing to the agent.

To claim it:

1. On the channel card in the console, generate a pairing code. It is valid for ten minutes.
2. In Telegram, open a direct message with your bot and send the command the console shows, for example /pair ABCD2345.
3. The bot replies "Paired. This account is now the owner of this bot."

Pairing only works in DMs, never in groups, and a few wrong guesses void the current code. To hand the bot to someone else, unpair it in the console and pair again from the new account.

After pairing, anyone can chat with the bot. The difference is trust: your paired account is the owner, while everyone else is a guest whose commands run in the sandbox — or are refused if no sandbox is configured.

Step 7: test it

Send the bot a message in your DM. Then try:

• Telling it something about yourself and asking about it later — memory works across conversations.
• Asking it to remind you of something tomorrow morning. Agents can create cron jobs, which you can inspect or pause on the agent's Scheduler page. See Scheduler.
• Adding it to a group. In groups the bot replies when it is @-mentioned, and the group keeps a history separate from your DMs.

Every Telegram chat ID gets its own session, and Telegram sessions are separate from the same person's sessions on other channels.

Make it safe for strangers

If the bot will be public, take two precautions:

1. Turn on the sandbox. In Settings → Runtime, enable Docker or E2B. Guests' commands then run in an isolated container with the agent's skills and workspace hydrated automatically.
2. Lock it down fully. On a self-hosted install, set FASTCLAW_SANDBOX_ENFORCE=1 so every exec and file call is confined to the sandbox, even for the owner.

Going further

• Add skills from ClawHub or GitHub to give the bot new abilities — see Skills.
• Bind the same agent to Discord, Slack, WeChat or WhatsApp; see Channels.
• Running a bot for a whole community? The communities use case covers moderation-friendly setups.

Self-hosting as above is free. If you would rather not run a server at all, compare the options on the pricing page.