Running a personal AI agent on Telegram — one that can search the web, write code, manage files, and respond from your pocket — takes about 15 minutes with OpenClaw. This guide walks through the complete OpenClaw Telegram setup from a clean machine to a working bot, including access control, group configuration, and the fixes for every common error along the way.
OpenClaw is a self-hosted gateway that connects messaging apps to AI agents. Telegram is its fastest channel to configure: no QR codes, no phone number linking, no OAuth dance. One bot token and a few lines of JSON get you a working personal AI agent on Telegram. (Weighing Telegram against other surfaces? See the Claude Code Channels vs. OpenClaw comparison for a fuller picture of the tradeoffs.)
What You Need Before Starting
Before beginning the OpenClaw Telegram setup, confirm you have:
- Node.js 24 (recommended) or Node 22.14+ (LTS minimum). Check with
node --version. - An API key from a model provider — Anthropic, OpenAI, Google, or another supported provider. OpenClaw’s onboarding wizard will prompt you to enter one.
- A Telegram account with access to the app (mobile or desktop).
- A machine to run the Gateway — your laptop, a VPS, a Raspberry Pi, or any Linux/macOS/Windows box with Node installed. WSL2 is recommended on Windows.
No paid Telegram plan is required. The standard Telegram Bot API is free.
Step 1: Install OpenClaw
Open a terminal and run the install script:
macOS / Linux:
curl -fsSL https://openclaw.ai/install.sh | bashWindows (PowerShell):
iwr -useb https://openclaw.ai/install.ps1 | iexAlternative methods (Docker, Nix, npm) are listed in the official install docs, but the one-liner above is the fastest path.
Step 2: Run Onboarding
openclaw onboard --install-daemonThe onboarding wizard does three things:
- Asks which model provider you want to use and stores your API key.
- Writes the initial configuration to
~/.openclaw/openclaw.json. - Installs the Gateway as a system daemon so it starts automatically on boot.
The whole process takes about two minutes. When it finishes, verify the Gateway is running:
openclaw gateway statusYou should see it listening on port 18789. If not, start it manually with openclaw gateway start.
Step 3: Create a Telegram Bot With BotFather
Open Telegram and search for @BotFather — the official Telegram bot for creating and managing bots. Confirm the handle is exactly @BotFather (with the blue checkmark) to avoid impersonators.
Send /newbot and follow the prompts:
- Choose a display name for your bot (e.g., “Magnus Assistant”).
- Choose a username that ends in
bot(e.g.,magnus_agent_bot). - BotFather replies with your bot token — a string like
123456789:ABCdefGHIjklMNOpqrsTUVwxyz. Copy it. You will need it in the next step.
Keep this token private. Anyone with the token can control your bot.
Step 4: Configure the Telegram Channel
Open your OpenClaw config file at ~/.openclaw/openclaw.json and add the Telegram channel block:
{
channels: {
telegram: {
enabled: true,
botToken: "YOUR_BOT_TOKEN_HERE",
dmPolicy: "pairing",
groups: { "*": { requireMention: true } },
},
},
}Alternatively, set the bot token as an environment variable instead of putting it in the config file:
export TELEGRAM_BOT_TOKEN="YOUR_BOT_TOKEN_HERE"The environment variable works for single-bot setups. If you run multiple Telegram bot accounts through one Gateway, put each token in the config file under separate account entries.
After saving the config, restart the Gateway:
openclaw gateway restartStep 5: Pair Your Telegram Account
With dmPolicy: "pairing" (the default), OpenClaw requires you to approve your Telegram account before it responds to your messages. This prevents strangers from using your bot.
- Open Telegram and send any message to your new bot.
- The bot will not reply yet — your account needs approval first.
- In your terminal, list pending pairing requests:
openclaw pairing list telegram- You will see a pairing code. Approve it:
openclaw pairing approve telegram <CODE>Pairing codes expire after one hour. If yours has expired, send another message to the bot and check again.
Once approved, send a message to your bot. It should reply through your configured AI model. That is the complete OpenClaw Telegram tutorial for direct messages — you now have a personal AI agent on Telegram.
Locking Down Access: Allowlists Over Pairing
Pairing works well for initial setup, but the OpenClaw security documentation recommends switching to an explicit allowlist for long-term use. Allowlists are durable — they survive config changes and don’t depend on a pairing store file.
To switch, find your Telegram numeric user ID. The safest method:
- DM your bot.
- Run
openclaw logs --followin your terminal. - Look for
from.idin the log output — that is your numeric ID.
Then update your config:
{
channels: {
telegram: {
enabled: true,
botToken: "YOUR_BOT_TOKEN_HERE",
dmPolicy: "allowlist",
allowFrom: ["YOUR_NUMERIC_USER_ID"],
},
},
}Restart the Gateway after any config change. With dmPolicy: "allowlist", only the user IDs listed in allowFrom can DM the bot. No pairing step required.
For those evaluating the security posture of self-hosted AI agents, NCT previously covered the enterprise security challenges facing OpenClaw deployments and the AI agent governance gap — both relevant reading for anyone exposing an agent to a messaging surface.
Adding Your Bot to Telegram Groups
OpenClaw supports group conversations. The setup has two layers: which groups are allowed, and which users within those groups can trigger the bot.
Allow a Specific Group
First, get the group’s chat ID. Forward a message from the group to @userinfobot or @getidsbot, or read chat.id from openclaw logs --follow after the bot receives a group message.
Telegram group and supergroup IDs are negative numbers (e.g., -1001234567890).
{
channels: {
telegram: {
groups: {
"-1001234567890": {
requireMention: true,
groupPolicy: "open",
},
},
},
},
}With requireMention: true, the bot only responds when mentioned by its @username in the group. This is the recommended default to prevent the bot from replying to every message.
Privacy Mode
Telegram bots default to Privacy Mode, which limits what group messages they can see. If your bot needs to see all messages in a group (not just those mentioning it), either:
- Disable privacy mode via
/setprivacyin BotFather, or - Make the bot a group admin.
After toggling privacy mode, remove and re-add the bot in each group so Telegram applies the change.
Group User Restrictions
To restrict which users can trigger the bot within a group, use allowFrom at the group level:
{
channels: {
telegram: {
groups: {
"-1001234567890": {
requireMention: true,
allowFrom: ["8734062810", "745123456"],
},
},
},
},
}One important security note from the official docs: group sender authorization does not inherit DM pairing-store approvals (as of the 2026.2.25 release). Pairing is DM-only. For groups, set groupAllowFrom or per-group allowFrom explicitly.
Streaming and Message Formatting
OpenClaw can stream partial replies in real time on Telegram using message edits. This is controlled by the streaming setting:
{
channels: {
telegram: {
streaming: "partial",
},
},
}Options are off, partial, block, and progress (which maps to partial on Telegram). The default is partial — you will see the reply typing out live, then finalize in place.
Outbound messages use Telegram’s HTML parse mode. OpenClaw handles the Markdown-to-HTML conversion automatically. If Telegram rejects the parsed HTML for any reason, OpenClaw retries as plain text.
Custom Commands
OpenClaw registers a command menu in Telegram automatically at startup. You can add custom entries:
{
channels: {
telegram: {
customCommands: [
{ command: "backup", description: "Git backup" },
{ command: "generate", description: "Create an image" },
],
},
},
}Command names must be lowercase, alphanumeric (plus underscores), and between 1 and 32 characters. Custom commands cannot override built-in native commands.
Troubleshooting Common OpenClaw Telegram Setup Issues
Bot Does Not Respond to Messages
Check the Gateway is running: openclaw gateway status. If it reports stopped, start it with openclaw gateway start.
Check pairing: If dmPolicy is "pairing", your account must be approved. Run openclaw pairing list telegram to see pending requests. If no requests appear, make sure channels.telegram.enabled is true and the bot token is correct.
Check the bot token: An invalid or revoked token will prevent the Gateway from connecting to the Telegram Bot API. Regenerate in BotFather if needed.
”BOT_COMMANDS_TOO_MUCH” Error at Startup
This means the Telegram command menu has too many entries after combining native, plugin, skill, and custom commands. Reduce the number of custom commands, or disable native command registration with channels.telegram.commands.native: false.
Bot Does Not See Group Messages
Telegram’s Privacy Mode is likely enabled. Run /setprivacy in BotFather to disable it, or make the bot a group admin. After changing, remove and re-add the bot in the affected group.
Pairing Code Expired
Codes expire after one hour. Send a new message to the bot, then run openclaw pairing list telegram again. Approve the fresh code.
”setMyCommands Failed” With Network Errors
The Gateway cannot reach api.telegram.org. Check outbound DNS and HTTPS connectivity from your server. Common on locked-down VPS instances or corporate networks with egress filtering.
Config Changes Not Taking Effect
Always restart the Gateway after editing openclaw.json:
openclaw gateway restartThen verify with openclaw gateway status.
Running OpenClaw Telegram on a VPS
For an always-on personal AI agent on Telegram, most users deploy the Gateway on a VPS rather than their laptop. The setup is identical — install Node, run openclaw onboard --install-daemon, configure the Telegram channel, and approve pairing. If you’re new to OpenClaw entirely, the mainstream adoption guide from Lenny Rachitsky and Claire Vo covers the broader onboarding picture before you start any channel configuration.
The daemon installer handles systemd service creation automatically. Once installed, the Gateway starts on boot and restarts on failure. SSH into the VPS to manage configuration or check logs:
openclaw logs --followFor remote access to the Control UI dashboard, the OpenClaw docs recommend using Tailscale rather than exposing port 18789 to the public internet.
Frequently Asked Questions
How do I connect OpenClaw to Telegram?
Follow Steps 1–5 in this guide: install OpenClaw, run onboarding, create a bot with BotFather, add the bot token to your openclaw.json config, restart the Gateway, then approve the pairing request from your terminal. The full OpenClaw Telegram tutorial takes about 15 minutes on a fresh machine.
Is OpenClaw free to use with Telegram?
OpenClaw itself is free and open-source (MIT license). You pay only for the AI model API usage from your chosen provider (Anthropic, OpenAI, Google, etc.). The Telegram Bot API is also free.
Can I use OpenClaw on Telegram and WhatsApp at the same time?
Yes. OpenClaw is a multi-channel gateway. One Gateway process can serve Telegram, WhatsApp, Discord, and iMessage simultaneously. Each channel has its own configuration block in openclaw.json.
How do I change the AI model my Telegram bot uses?
The model is configured at the Gateway level, not per channel. During onboarding, you selected a provider and model. To change it later, edit the provider and model settings in ~/.openclaw/openclaw.json and restart the Gateway. The configuration docs cover all available options.
Is my data private when using OpenClaw on Telegram?
OpenClaw is self-hosted — your messages route through your own Gateway on your own hardware, not through a third-party service. The Gateway sends prompts to your chosen model provider’s API (the same privacy model as using the provider’s API directly). No message data passes through OpenClaw’s servers. The security documentation details the trust model and hardening options.
Sources: OpenClaw Telegram channel documentation, OpenClaw Getting Started guide, OpenClaw security documentation.