How to set up OpenClaw on Telegram, and keep it private

Connect OpenClaw to Telegram: the BotFather token, the terminal steps, pairing and allowlists explained, a two-minute hosted route, a first week of prompts and fixes.

In this note

To put OpenClaw on Telegram, you create a bot with Telegram's @BotFather, give its token to OpenClaw, and send the bot your first message. Running OpenClaw yourself, that means adding the token from the terminal (openclaw channels add --channel telegram --token <bot-token>), keeping the gateway running, and approving your own pairing code. The one setting that matters most is who the bot answers: lock it to your own Telegram account, because the agent behind it can read your files and use your apps. On Heyron the same setup is a pasted token and one message, about two minutes.

Below: what you need, the self-hosted steps from OpenClaw's own docs, the access settings explained, the Heyron route, a first week of Telegram jobs with prompts to copy, and fixes for a bot that won't reply. OpenClaw's Telegram docs were checked on November 13, 2026.

Running OpenClaw yourself
  • Create a bot with @BotFather and copy the token
  • Add it with openclaw channels add or in ~/.openclaw/openclaw.json
  • Start the gateway and keep it running
  • Message the bot, then approve your pairing code within an hour
  • Optionally switch to an allowlist with your numeric user ID
On Heyron
  • Create a bot with @BotFather and copy the token
  • Paste it under Apps and messaging, Connect Telegram
  • Send the bot "hi" from your own Telegram
  • The agent now answers only you
  • Its computer is already on, so there's no gateway to keep running

What do you need before you start?

Three things: the Telegram app on your phone, a running OpenClaw agent, and two minutes with @BotFather. A Telegram bot is a separate account that your agent speaks through. You aren't giving the agent your personal Telegram; you're giving it a bot that you chat with.

To create the bot:

  1. In Telegram, search for @BotFather and check it has the blue verified mark.
  2. Send /newbot.
  3. Pick a display name, such as "Max", and a username that ends in bot, such as max_groomly_bot.
  4. BotFather replies with a token: a number, a colon, then a long string of letters (7123456789:AAH...). Copy it.

How do you set up OpenClaw on Telegram yourself?

If you run OpenClaw on your own machine or a rented server, the docs give these steps. Telegram doesn't use a login flow; the bot token is all OpenClaw needs.

  1. Add the token. Either run openclaw channels add --channel telegram --token <bot-token>, or put it in ~/.openclaw/openclaw.json under channels.telegram.botToken with enabled: true. A TELEGRAM_BOT_TOKEN environment variable also works for a single bot.
  2. Start the gateway. openclaw gateway start runs it as a background service; openclaw gateway runs it in the current terminal. Telegram only works while the gateway is running, so on a laptop that sleeps, your bot sleeps too.
  3. Check it. openclaw channels status --probe confirms OpenClaw can reach Telegram with that token.
  4. Pair yourself. Send your bot a message. It replies with an 8-character pairing code. On the server, run openclaw pairing list telegram, then openclaw pairing approve telegram <CODE>. Codes expire after one hour.

That's the whole connection. OpenClaw uses long polling by default, so you don't need a public web address or a webhook. If replies never arrive and the logs show 409 conflicts, another copy of OpenClaw is polling with the same token: stop the old one.

Who can message your OpenClaw bot?

Anyone on Telegram can find a bot by its username, so the access setting is the part to get right. OpenClaw's channels.telegram.dmPolicy has four options.

From OpenClaw's Telegram access-control docs, checked November 13, 2026. Each row stands on its own.
Setting What it does When to use it
pairing (the default) Strangers get a pairing code and are ignored until you approve it on the server Fine to start with; you approve yourself once
allowlist Only the numeric Telegram user IDs in allowFrom get answers Best for a one-owner bot, and what the docs recommend
open Anyone can talk to the agent (needs "*" in allowFrom) Almost never for a business agent with access to your apps
disabled The bot ignores direct messages When the bot should only work in an approved group

Approving a pairing code gives that person direct-message access, nothing more. Groups are a separate setting, groupPolicy, and it starts as an allowlist with nothing on it, so the bot ignores every group until you add one by its chat ID. In groups it only answers when mentioned, unless you change requireMention and turn off Telegram's privacy mode with BotFather's /setprivacy.

For a one-person business, keep it simple: one private chat between you and your agent. An agent that can read your inbox doesn't belong in a group chat with customers.

How do you connect Telegram on Heyron?

Heyron runs the same OpenClaw, so the bot and token are the same. What changes is everything after BotFather:

  1. In your dashboard, open Apps and messaging and click Connect Telegram.
  2. Paste the token and click Continue. Heyron checks it with Telegram before saving it.
  3. Open your bot in Telegram and send "hi". Whoever writes first is the only person the agent answers, so make sure it's you.
  4. Wait about a minute until the dashboard says your bot is connected.

Sending the first message does the pairing step for you: the agent is set to answer only your Telegram account, the allowlist the docs recommend, with no user ID to look up. Later, Check it works on the same page asks the agent to confirm it's still reachable. Your agent runs on its own computer that stays on, so the bot answers at 3am the same as at noon, and a message wakes a sleeping agent in a few seconds. The connect Telegram tutorial has the step-by-step version and explains what the Skip button does.

A worked example: a founder's first week on Telegram

Maya is building a booking app for dog groomers and still has a day job. She connected Telegram so the agent could reach her on her lunch break and she could reach it from the bus. Here's what she set up, one job at a time, in the same order we'd suggest to anyone.

  1. Day 1Connect and testBot made, token pasted, "hi" sent. Asked it to confirm what it can see.
  2. Day 2Set the house rulesShort replies on Telegram, nothing sent in her name.
  3. Day 3Morning brief on her phoneWaitlist sign-ups and new emails at 7am.
  4. Day 5Capture ideas on the goQuick notes and links from the bus, filed for later.
  5. Day 7Reply from her phoneDone when she clears the brief in five minutes without opening a laptop.

The first message she sent wasn't a task. It was a check that the bot really is her agent, with its memory and files, not a blank chatbot.

Telegram is a small screen, and agents write long answers by default. Day 2 was about making it readable on a phone and making the limits clear.

The morning brief is where Telegram earns its place: the agent does the reading at 7am, and Maya gets one message she can act on before work.

By day 5 she was sending it half-formed ideas: a two-line note about a feature, a competitor's pricing link, a screenshot of a groomer's complaint. The agent saved each one to an ideas file with the date. On day 7 she could read the brief, answer "draft a reply to the second one", check the draft, and send it herself from Gmail. The agent drafts; Maya decides what goes out.

For exact-time jobs like the 7am brief, see scheduled tasks. For more jobs worth running this way, OpenClaw use cases sorts the community's real setups by how often they pay off.

Why isn't my OpenClaw Telegram bot replying?

Most cases are one of five things.

  • The token is wrong. On a self-hosted agent the logs say getMe returned 401. Copy the token again from BotFather; send /token there to see it.
  • The gateway isn't running (self-hosted). Telegram only works while it runs. Start it with openclaw gateway start and check openclaw channels status --probe.
  • You're not approved. With the default pairing setting, your message waits until you approve the code, and an unapproved code expires after an hour. On Heyron, if someone else wrote to the bot first, use Connect a different bot.
  • Two copies are polling. A 409 conflict means the same token runs in two places, often an old test server. Stop one.
  • It's in a group. Groups are ignored until allowed, and then the bot needs an @mention.

On Heyron, also check the agent's status. If it's stopped, start it and send another message; if it's sleeping, the first message wakes it in a few seconds. Agent not responding covers the rest.

Where to run it

The self-hosted route works, and plenty of people run it on a spare machine. The cost is the upkeep: a computer that must stay on, a model provider to pay, and the terminal steps again whenever something changes. Running OpenClaw yourself vs Heyron lays out the trade honestly.

With managed OpenClaw hosting on Heyron, your agent comes with its own always-on computer, monthly AI usage, 1,000+ app connections and Telegram or WhatsApp set up from the dashboard. Members also get the Solo Software Studio community, a place to post your weekly updates, see what's working for other solo founders and work toward a first paying customer together. See what's included.

Frequently asked questions

Is OpenClaw on Telegram free?

Telegram bots are free to create and use, and OpenClaw is free, open-source software. What costs money is the computer it runs on, which must stay on for the bot to answer, and the AI model it calls for every reply.

Can other people use my OpenClaw Telegram bot?

Only if you let them. With the default pairing setting, strangers get a code you'd have to approve; with an allowlist, only the user IDs you list get answers. On Heyron, the bot answers only the person who sent the first message.

Does OpenClaw need a webhook for Telegram?

No. It uses long polling by default, so it works from a home computer with no public address. Webhook mode is optional, set with channels.telegram.webhookUrl and webhookSecret.

Is my Telegram chat the same conversation as the web chat?

It's the same agent with the same memory and files, but a separate conversation. Tell it something worth keeping in either place and ask it to save it to its notes, and it will know in both.

Can I connect WhatsApp as well as Telegram?

Yes. One agent can be on both, and on Heyron both are under Apps and messaging. See connect WhatsApp for what it needs.