How to Connect OpenClaw to Telegram: Talk to Your AI Agent From Your Phone

#Why Telegram Is the Best Way to Talk to Your Agent

You have OpenClaw installed. Your agent works. But right now, you are probably talking to it through a terminal or a web dashboard — which means you need to be at your computer.

Telegram changes that. Once connected, your OpenClaw agent becomes a contact on your phone. You can message it from anywhere — waiting in line, lying in bed, sitting in a meeting you should not be in. It responds in seconds, has full access to all its tools and skills, and the conversation persists across devices.

Most OpenClaw users eventually land on Telegram as their primary interface, and for good reason. It is fast, encrypted, available on every platform, supports file sharing, and — critically — it is free. No API costs for the messaging layer. You only pay for the AI model usage, which you are paying for anyway.

This guide takes you from zero to a working Telegram connection in about ten minutes.

#What You Need Before Starting

• OpenClaw installed and running on your machine (Mac, Linux, or Windows). If you have not done this yet, follow our getting started guide first.
• An AI model configured (Anthropic, OpenAI, Google, or a local model via Ollama).
• A Telegram account on your phone or desktop.

That is it. No server, no domain, no paid Telegram plan.

#Step 1: Create Your Bot With BotFather

Every Telegram bot starts with BotFather — Telegram's official tool for creating and managing bots.

1. Open Telegram and search for @BotFather (make sure it has the blue verified checkmark).
2. Send the command /newbot.
3. BotFather will ask you for a display name — this is what people see in the chat list. Pick something like "My OpenClaw Agent" or whatever you named your agent.
4. Next, it asks for a username — this must end in bot (like my_openclaw_bot). This is the unique handle.
5. BotFather will respond with your bot token — a long string that looks like 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ. Copy this token and save it somewhere safe. You will need it in the next step.

Security note: Your bot token is like a password. Anyone who has it can control your bot. Do not share it publicly, do not commit it to a git repository, and do not paste it into a chat message to your agent.

#Step 2: Configure OpenClaw With Your Token

Now you need to tell OpenClaw about your new bot. There are two ways to do this:

#Option A: Using the CLI (Recommended)

Run these commands in your terminal:

openclaw config set channels.telegram.botToken '"YOUR_BOT_TOKEN_HERE"' --json
openclaw config set channels.telegram.enabled true --json

Replace YOUR_BOT_TOKEN_HERE with the actual token from BotFather. Keep the quotes — they are part of the JSON syntax.

#Option B: Edit the Config File Directly

Open your OpenClaw config file, the optional JSON5 config that OpenClaw reads from ~/.openclaw/openclaw.json, and add or update the Telegram section:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "YOUR_BOT_TOKEN_HERE",
      dmPolicy: "pairing",
    },
  },
}

The dmPolicy: "pairing" setting means the first time someone messages your bot, they will need to be approved. This prevents random people from using your agent.

#Step 3: Start (or Restart) the Gateway

If OpenClaw is not running yet:

openclaw gateway

If it is already running as a service:

openclaw gateway restart

You should see a log message confirming that the Telegram channel is connected. Something like:

✓ Telegram bot connected (@your_bot_username)

If you see an error about the token, double-check that you copied it correctly and that there are no extra spaces.

#Step 4: Send Your First Message and Pair

Now open Telegram and find your bot. You can either:

• Search for the username you chose (like @my_openclaw_bot)
• Or click the link BotFather gave you (like t.me/my_openclaw_bot)

Send any message — even just "hello."

Since you are using pairing mode, your bot will ask you to complete a pairing step. Back in your terminal, run:

openclaw pairing list telegram

You will see a pairing request with a code. Approve it:

openclaw pairing approve telegram YOUR_CODE

That is it. Your Telegram bot is now connected to your OpenClaw agent. Every message you send in this chat goes directly to your agent, and every response comes back in real time.

#Step 5: Lock It Down (Optional but Recommended)

Once you are paired and confirmed everything works, you might want to switch from pairing mode to allowlist mode. This ensures that only your specific Telegram account can use the bot, even if someone discovers the bot username.

First, find your Telegram user ID. Your agent can tell you — just ask "What is my Telegram user ID?" in the chat. Or use a bot like @userinfobot.

Then update your config:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "YOUR_BOT_TOKEN_HERE",
      dmPolicy: "allowlist",
      allowFrom: ["YOUR_NUMERIC_USER_ID"],
    },
  },
}

Restart the gateway and you are locked down. Only your account can talk to the bot.

#Adding Your Bot to Group Chats

If you want your agent in a Telegram group (for example, a team chat or a family group), there are a couple of extra steps:

#1. Disable Privacy Mode

By default, Telegram bots in groups can only see messages that directly mention them or are replies to their messages. To let your agent see all group messages:

• Chat with @BotFather
• Send /setprivacy
• Select your bot
• Choose Disable

#2. Add to Group and Configure

Add the bot to your group. Then update your OpenClaw config to allow group messages:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "YOUR_BOT_TOKEN_HERE",
      dmPolicy: "allowlist",
      allowFrom: ["YOUR_USER_ID"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["GROUP_CHAT_ID"],
      groups: {
        "*": { requireMention: true },
      },
    },
  },
}

The requireMention: true setting means the bot only responds when someone @mentions it in the group — which is usually what you want to avoid your agent jumping into every conversation.

#What You Can Do Now

With Telegram connected, you can:

• Send voice messages — your agent can transcribe and respond to them
• Share files — send photos, PDFs, documents, and your agent can analyze them
• Get proactive notifications — if your agent has heartbeats or cron jobs configured, it will message you with updates
• Control everything remotely — manage your agent from your phone while your computer runs at home

#Troubleshooting

Bot does not respond at all:

• Check that the gateway is running (openclaw gateway status)
• Verify the token is correct (openclaw doctor can help)
• Make sure you completed pairing

Bot responds slowly:

• This is usually the AI model, not Telegram. Try a faster model or check your API key rate limits.

"Unauthorized" errors in the logs:

• Your token may have been regenerated in BotFather. Get the current token from BotFather (/mybots → select bot → API Token) and update your config.

Bot does not see group messages:

• Make sure privacy mode is disabled in BotFather
• After changing privacy mode, remove and re-add the bot to the group
• Or make the bot a group admin (admins always see all messages)

Now that your agent lives on your phone, it is time to make it yours. Customize its personality with SOUL.md, set up a morning routine, or explore the best skills to install.