How to Set Up OpenClaw with Telegram (So Your AI Can Text You Back)

The Moment I Realized I Had a Problem

It was 11 PM. I was in bed. I had a stupid bug in my head that I couldn't shake.

My laptop was on the desk, charging. The desk was five feet away. Five. Feet.

I did not get up.

Instead I spent forty minutes thinking about the bug, failed to solve it, and went to sleep frustrated.

The next morning I fixed it in thirty seconds at my desk.

You know what would've helped? Being able to just message my AI assistant from my phone without opening a laptop. Just pull up Telegram, shoot a quick message, and get an answer.

That's exactly what OpenClaw does.

(Narrator: He immediately found ten other things to complain about after setting it up. But the 11 PM bug situation? Genuinely solved.)

What Even Is OpenClaw?

OpenClaw is an open-source, self-hosted gateway that connects your favorite chat apps — Telegram, WhatsApp, Discord, iMessage, and more — to AI coding agents.

Think of it as a router for your AI conversations. Instead of always needing to open a browser tab or fire up the CLI, you can just message your bot like you'd message a friend.

Except this friend:

• Never gets tired
• Never judges your 11 PM "quick question"
• Has read every Stack Overflow post ever written
• Still somehow gets confused by your codebase just like the rest of us

It's MIT-licensed, runs on your machine, and you keep full control of your data. For those of us who are slightly paranoid about where our code questions end up — that's a feature, not a footnote.

Why Telegram, Specifically?

Look, I know there are plenty of options. WhatsApp, Discord, iMessage — OpenClaw supports them all. But Telegram is the move for developers and here's why:

• Bot API is dead simple. Creating a bot takes literally two minutes.
• No phone number required to create a bot (looking at you, WhatsApp).
• Works on every platform. Desktop, mobile, web, even command line.
• Fast. Telegram's servers aren't running on a hamster wheel.

Plus, Telegram bots already have a whole culture around them. Your users/friends won't be weirded out by a bot username. It's just... normal in Telegram.

So. Telegram it is.

What You'll Need Before We Start

Let's not kid ourselves — prerequisites exist and ignoring them causes pain. Here's the checklist:

• Node 22 or higher — Run node --version to check. If you're on anything older, go update it first.
• A Telegram account — If you don't have one, download the app and sign up. It's free. It takes two minutes.
• An AI API key — OpenClaw needs to talk to an AI model. Claude, GPT-4, whatever you're vibing with. Have the API key handy.
• Terminal access — If you're a developer reading a developer blog, I'll assume this is fine.

That's it. No Docker required (unless you want it). No Kubernetes cluster (unless you're that person). No cloud account. Just your machine, Node, and a terminal.

Let's go.

Step 1: Install OpenClaw

The fastest path is the installer script. It detects your Node setup, installs the CLI globally, and launches the onboarding wizard all in one shot.

On macOS / Linux / WSL2:

curl -fsSL https://openclaw.ai/install.sh | bash

On Windows (PowerShell):

iwr -useb https://openclaw.ai/install.ps1 | iex

Windows users: OpenClaw strongly recommends running under WSL2. If you're on native Windows and things go sideways, WSL2 is your first troubleshooting step.

The installer:

1. Checks if Node 22+ is present
2. Installs OpenClaw globally via npm
3. Launches the onboarding wizard automatically

If it doesn't launch onboarding automatically, or you skipped it, just run:

openclaw onboard --install-daemon

The --install-daemon flag tells OpenClaw to also set up the background service so the gateway starts automatically. You want this. Trust me. You don't want to manually start it every time you reboot.

Troubleshooting: openclaw not found after install

If you see command not found: openclaw after installing, your npm global bin directory isn't in your PATH. Fix it:

# Check where npm puts global bins
npm prefix -g
 
# Add to your ~/.zshrc or ~/.bashrc
export PATH="$(npm prefix -g)/bin:$PATH"
 
# Reload your shell
source ~/.zshrc  # or ~/.bashrc

Then try openclaw --version again.

Step 2: Run the Onboarding Wizard

The onboarding wizard is where the actual setup happens. It's a guided, interactive flow that asks you for your API key, sets up the gateway config, and optionally walks you through connecting a channel.

openclaw onboard --install-daemon

The wizard will ask you for:

1. Your AI provider and API key — Paste in your key when prompted. This is what makes the actual AI part work.
2. Gateway settings — Port, whether to run as a daemon, etc. The defaults are fine for most people.
3. Channels — You can connect Telegram here, or skip and do it manually (which we're about to do anyway).

Go through it. It's short. It's pleasant. It has nice prompts.

(Narrator: He said the defaults are fine and then spent forty-five minutes tweaking the config anyway.)

Step 3: Create Your Telegram Bot via BotFather

This is the fun part. No code, no config files — just chatting with a bot to create a bot. Very meta.

Open Telegram and search for @BotFather. Make sure it has the blue verification checkmark. There are impostors. The real one is verified.

Start a chat and send /newbot.

BotFather will ask you two things:

1. A name for your bot — This is the display name. Something like "My AI Assistant" or "DevBot" or "The Oracle" if you're feeling dramatic.
2. A username for your bot — Must end in bot. Like myassistant_bot or devhelper_bot. Must be unique across all of Telegram.

Once you pick a valid username, BotFather will congratulate you and hand you a bot token. It looks like this:

7294810234:AAFxyz1234abcDEFghijKLMNOPqrstuvwxyz

Copy this token and keep it somewhere safe. Not in your repo. Not in a public Gist. Treat it like a password because it is one — anyone with this token controls your bot.

Step 4: Add the Bot Token to OpenClaw Config

Now we wire the bot to OpenClaw. The config file lives at ~/.openclaw/config.json5 by default (or wherever OPENCLAW_CONFIG_PATH points if you've overridden it).

Open it in your editor and add the Telegram channel config:

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

Replace YOUR_TOKEN_HERE with the actual token BotFather gave you.

Let's talk about dmPolicy for a second because it matters for security:

For a personal setup, pairing is the sweet spot. Your bot isn't public, random people can't spam it, but you can pair your own Telegram account in 30 seconds.

If you want to be extra locked down, allowlist with your own Telegram user ID is the way. If you want to share it with friends, pairing lets you approve them one by one.

Don't use open unless you've thought hard about rate limits and who you want accessing your AI.

Step 5: Start the Gateway

Time to fire it up.

openclaw gateway

If you installed the daemon during onboarding, the gateway might already be running. Either way, you can check:

openclaw gateway status

You should see confirmation that the Telegram channel is active and the bot is polling for messages. If you see errors about the bot token, double-check that you pasted it correctly (no extra spaces, no truncation).

Step 6: Pair Your Telegram Account

This is the handshake step. You're going to DM your own bot in Telegram, and then approve yourself on the OpenClaw side.

First, DM your bot in Telegram. Search for the bot username you created (the one ending in bot) and send it any message. "Hello", "hey", "test", whatever. It doesn't matter what you say.

Your bot won't respond yet — that's expected. OpenClaw has logged the request and is waiting for you to approve it.

Now, approve the pairing:

# See who's requesting access
openclaw pairing list telegram

You'll see your Telegram account in the list with a pairing code. Approve it:

openclaw pairing approve telegram <CODE>

Replace CODE with the actual code from the list. Do this within an hour — the pairing code expires.

Step 7: Say Hello to Your AI (For Real This Time)

Go back to Telegram. Send a message to your bot.

And it should respond.

That's it. That's the whole setup. You can now:

• Ask your AI coding questions from your phone while you're on the couch
• Fire off a quick "what does this error mean?" when you're away from your desk
• Message at 11 PM from bed and actually get an answer without getting up

(Narrator: He immediately tested it by asking something about async JavaScript and spent the next hour down a rabbit hole. The original bug from 11 PM was forgotten entirely.)

Verify Everything Works

Before you declare victory, run the doctor command. It catches common config issues:

openclaw doctor

And check the dashboard — it's a web UI that shows connected channels, active sessions, and logs:

openclaw dashboard

This opens at http://127.0.0.1:18789/ by default. Green across the board? You're done. Go enjoy your newly omnipresent AI assistant.

Optional: Privacy Mode and Group Chats

If you want to add your bot to a group chat (say, a dev team chat or a shared project channel), there's one Telegram-side thing you need to handle: Privacy Mode.

By default, Telegram bots in groups only receive messages that mention them by name. If you want your bot to see everything (or respond to all messages without being @mentioned), you have two options:

Option A: Disable Privacy Mode via BotFather

In BotFather, send /setprivacy, select your bot, and choose Disable.

Then remove and re-add the bot to your group — Telegram only applies the privacy mode change to new memberships, not existing ones.

Option B: Make the Bot a Group Admin

Admin bots automatically receive all group messages. If you want it to see everything, just promote it to admin in your group settings.

Once you've handled that, update your OpenClaw config to allow the group:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "YOUR_TOKEN_HERE",
      dmPolicy: "pairing",
      groups: {
        "*": {
          requireMention: true,
          groupPolicy: "open",
        },
      },
    },
  },
}

Or for a specific group (replace the ID with your actual group ID — you can find it by sending a message to the group and checking openclaw logs --follow for the chat.id field):

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          requireMention: false,
          groupPolicy: "open",
        },
      },
    },
  },
}

requireMention: false means the bot responds to every message in the group, not just @mentions. Handy if your group IS the AI chat. Less handy if your group is a mix of human conversation and occasional AI questions.

Optional: Live Streaming Replies

One of my favorite OpenClaw features: instead of waiting for the full response before it appears in Telegram, you can have the bot edit its message in real-time as the tokens stream in. It feels exactly like typing indicators but for AI.

{
  channels: {
    telegram: {
      streamMode: "partial",
      draftChunk: {
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph"
      }
    },
  },
}

streamMode: "partial" sends frequent updates as text arrives. If you find it too chatty, streamMode: "block" does chunkier updates using the draftChunk settings instead.

Do's and Don'ts

Before you go clicking around and setting things on fire, here's a quick cheat sheet from people who have already done exactly that.

✅ Do's

Do use dmPolicy: "pairing" for personal setups. It's the right default. Your bot stays private, you can still approve friends, and random strangers don't get to burn through your API quota at 3 AM.

Do store your bot token in the config file, not as an env variable. TELEGRAM_BOT_TOKEN as an env var only applies to the default account and can behave unexpectedly in multi-account setups. Config file wins — use it.

Do treat ~/.openclaw like it contains secrets. Because it does. Session transcripts, credentials, API keys — it's all in there. Restrict file permissions, and if you're on a shared machine, encrypt the directory.

Do bind the gateway to 127.0.0.1, not 0.0.0.0. 0.0.0.0 means anyone on your network can hit the gateway. Unless you have a very specific reason to expose it, keep it local. If you need remote access, use Tailscale or a private tunnel.

Do set groupPolicy: "disabled" unless you actually need groups. If you're just using DMs, there's no reason to leave the door open. Disable it.

Do run openclaw doctor after every config change. It's fast, it catches stupid mistakes, and it will save you ten minutes of debugging something that was just a typo.

❌ Don'ts

Don't put your bot token under plugins.entries. Telegram is a built-in channel in OpenClaw, not a plugin. Putting it under plugins.entries gives you a cryptic "plugin not found: telegram" error that will confuse you for longer than you'd like to admit.

Don't run two gateways against the same bot token. Telegram only allows one polling connection per bot at a time. If you accidentally start a second gateway (old terminal session, leftover daemon, whatever), you'll get Conflict: terminated by other getUpdates request and both instances will fight each other. One bot, one gateway. Always.

Don't commit your bot token to git. Not in your config file, not in a .env, not in a comment, not anywhere. Once it's in git history, it's basically public even if you delete it. Rotate the token from BotFather if this happens.

Don't skip removing and re-adding the bot after changing privacy mode. This is the #1 reason bots mysteriously don't respond in groups. Telegram only applies privacy mode changes to new bot memberships. Old memberships keep the old behavior. Remove, re-add, done.

Don't enable shell execution skills unless you know exactly what you're doing. Letting an AI run shell commands on your machine is powerful and also how you give yourself a very bad day. Only enable this if you've read the docs and trust your setup.

Don't ignore IPv6 if your bot stops responding randomly. Some systems resolve api.telegram.org to IPv6 first, and if your IPv6 egress is broken, you'll get intermittent failures that look totally random. Add network: { autoSelectFamily: false } to your Telegram config to force IPv4.

Troubleshooting: The Things That Will Go Wrong

Bot doesn't respond to group messages

1. Check requireMention in your config — if it's true, you need to @mention the bot
2. Check privacy mode in BotFather (/setprivacy)
3. Remove and re-add the bot to the group after changing privacy settings
4. Run openclaw channels status for config warnings

openclaw: command not found

Your npm global bin isn't in PATH. See the fix in Step 1.

Bot token errors on startup

You probably have an extra space or missing character in the token. BotFather's tokens are long and annoying to copy — use the copy button, not manual selection.

Pairing request not showing up in openclaw pairing list

Make sure the gateway is running (openclaw gateway status). If it's not running, requests won't be logged. Also check that you actually sent a message to the bot in Telegram — just opening the chat isn't enough.

sharp build errors during npm install

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

This is a known issue with the sharp image library on some systems. That env variable tells it to skip the local libvips check.

The Full Config Reference (For Power Users)

In case you want to see everything in one place before going down the rabbit hole:

{
  channels: {
    telegram: {
      // The essentials
      enabled: true,
      botToken: "123:abc",
 
      // Who can DM
      dmPolicy: "pairing",         // pairing | allowlist | open | disabled
      allowFrom: ["123456789"],    // for allowlist mode
 
      // Group settings
      groupPolicy: "allowlist",
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          groupPolicy: "open",
          requireMention: false,
        },
      },
 
      // Response streaming
      streamMode: "partial",       // off | partial | block
 
      // Reply threading
      replyToMode: "first",        // off | first | all
 
      // Reactions when processing
      ackReaction: "👀",
    },
  },
}

The ackReaction one is underrated — your bot will react to your message with 👀 while it's thinking, so you know it received the message and is working on a response. Small thing, big UX improvement.

So, Was This Worth It?

Let me do the math:

Time to set up OpenClaw + Telegram: ~15 minutes Time saved on my first late-night bug query: 40 minutes of lying awake frustrated ROI: Immediately positive

Unlike my $8K developer setup (which I've written about before), this one actually pays off fast. There's no diminishing returns plateau. You're either able to ask your AI a question from your phone or you're not. With OpenClaw, you are.

The setup is small, the config is minimal, and the payoff is real. That's genuinely rare in the world of developer tools.

Go try it. You have the tutorial, you have no excuses. Your 11 PM self will thank you.

(Unless you're the type who stays up until 3 AM setting up the advanced group configs and custom command menus instead of sleeping. In which case — same. I see you. We're the same person.)

P.S. — The pairing code expires after 1 hour. Learn from my mistakes: don't start the setup, get distracted by a YouTube video, and come back an hour later wondering why it's not working.

P.P.S. — If you're on Windows and this guide didn't work for you, open WSL2, start over from Step 1. You'll thank me.

P.P.P.S. — Yes, you can set the ackReaction to any emoji. No, I'm not telling you what mine is. Yes, it's embarrassing. No, I'm not changing it.