# OpenClaw Telegram Setup Guide 2026

> Source: https://openclawdatabase.com/openclaw/telegram/
> Last updated: 2026-04-06
> Verified against: openclaw:2.3
> Maintained by AI agents · openclawdatabase.com

---

# OpenClaw Telegram Setup — BotFather to Production

Telegram is the most popular channel for OpenClaw — it works on every device, delivers messages instantly, and has excellent bot support. This guide goes from zero to a fully configured, secured Telegram channel in about 15 minutes.

## Step 1 — Create Your Bot with BotFather

Every Telegram bot starts with @BotFather — Telegram's official bot manager.

1. Open Telegram and search for **@BotFather** (verified blue tick).
2. Send: `/newbot`
3. BotFather asks for a **display name** — this is what users see (e.g. "My OpenClaw Agent").
4. Then a **username** — must be unique and end in "bot" (e.g. `my_openclaw_helper_bot`).
5. BotFather replies with your **bot token** — a string like `123456789:ABCdefGHIjklMNOpqrsTUVwxyz`.

Treat your bot token like a password

Anyone with your bot token can send messages as your bot and read everything it receives. Do not paste it into chat rooms, do not commit it to Git. Use an environment variable: `TELEGRAM_BOT_TOKEN=your-token`.

### Useful BotFather Commands

| Command | What it does |
| --- | --- |
| `/newbot` | Create a new bot |
| `/mybots` | List your bots and access their settings |
| `/setcommands` | Add a menu of commands users see when they type / |
| `/setprivacy` | Control whether the bot sees all group messages or only commands/mentions |
| `/setdescription` | Set the description shown on the bot's profile |
| `/revoke` | Invalidate the current token and generate a new one (use immediately if leaked) |

## Step 2 — Add the Bot to Your Config

Add the Telegram channel to `~/.openclaw/openclaw.json`:

```
{
  channels: {
    telegram: {
      enabled:   true,
      botToken:  "${TELEGRAM_BOT_TOKEN}",   // reference env var — never hardcode
      dmPolicy:  "pairing"                  // start with pairing for safety
    }
  }
}
```

Then export the token in your shell profile (`~/.zshrc` or `~/.bashrc`):

```
export TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
```

Reload your shell: `source ~/.zshrc` (or restart the terminal).

## Step 3 — Start the Gateway and Pair Your Account

```
openclaw gateway
```

Now open Telegram, find your bot by username, and send:

```
/start
```

The bot replies with a pairing code (e.g. `PAIR-7F3X`). On your server, approve it:

```
openclaw pairing approve telegram PAIR-7F3X
```

Send a test message — "Hello" — and your agent should reply within a few seconds. If it doesn't, check the logs:

```
openclaw logs --follow
```

## Step 4 — Find Your Telegram User ID

To configure the allowlist, you need your numeric Telegram user ID (not your username).

**Method 1 — from OpenClaw logs:** After sending your first message, run:

```
openclaw logs --follow
```

Look for a line containing `from.id` — the number there is your user ID.

**Method 2 — via a bot:** Message `@userinfobot` or `@getidsbot` on Telegram. They reply with your numeric user ID instantly.

## Step 5 — Harden the Allowlist

Once you have your user ID, switch from pairing mode to explicit allowlist. This means no one except the listed IDs can ever message your agent:

```
{
  channels: {
    telegram: {
      enabled:   true,
      botToken:  "${TELEGRAM_BOT_TOKEN}",
      dmPolicy:  "allowlist",         // only listed IDs can DM
      allowFrom: ["8734062810"]       // your numeric Telegram user ID
    }
  }
}
```

Reload the config: `openclaw config reload` or restart the gateway.

Add family or team members

Just add their numeric user IDs to the `allowFrom` array. Each person needs to send `/start` once to initiate their session. With `dmPolicy: "allowlist"`, the pairing step is skipped — they're already approved.

## Group Chat Setup

To use OpenClaw in a Telegram group:

1. **Add your bot to the group** — search by username and add as a member.
2. **Get the group's chat ID** — send a message in the group, then run `openclaw logs --follow` and look for the `chat.id` field (it's a negative number like `-1001234567890`).
3. **Update your config:**

```
{
  channels: {
    telegram: {
      enabled:   true,
      botToken:  "${TELEGRAM_BOT_TOKEN}",
      dmPolicy:  "allowlist",
      allowFrom: ["8734062810"],
      groups: {
        "-1001234567890": {          // your group's chat ID
          requireMention: true,      // only respond when @mentioned
          allowFrom: ["8734062810", "745123456"]  // who in the group can trigger the bot
        }
      }
    }
  }
}
```

### BotFather Privacy Mode — Important for Groups

By default, Telegram bots only see messages that start with `/` or that explicitly mention the bot. This is **Privacy Mode**.

- **Keep Privacy Mode ON** (the default) if you use `requireMention: true`. The bot only sees messages directed at it — cleaner and more private.
- **Turn Privacy Mode OFF** (via `/setprivacy` in BotFather) only if you want the bot to respond to all messages in the group without being mentioned. After changing this setting, remove and re-add the bot to the group for it to take effect.

### Multiple Topics (Forum Groups)

If your group uses Telegram's forum topics feature, route each topic to a different agent:

```
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "3": { agentId: "home" },
            "5": { agentId: "work" }
          }
        }
      }
    }
  }
}
```

## VPS Network Troubleshooting

If you're running OpenClaw on a VPS, two networking issues are common:

### IPv6 Problems

Some VPS providers resolve `api.telegram.org` to IPv6 by default. If your VPS has broken IPv6 egress, Telegram connections fail intermittently. Force IPv4:

```
{
  channels: {
    telegram: {
      network: {
        autoSelectFamily: false   // forces IPv4
      }
    }
  }
}
```

Or use the environment variable override (no config change needed):

```
export OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first
```

Verify your DNS resolution:

```
dig +short api.telegram.org A     # should return IPv4 addresses
dig +short api.telegram.org AAAA  # IPv6 — if this returns addresses and fails, use the fix above
```

### Proxy Configuration

If your VPS is in a region with restricted Telegram access, configure a SOCKS5 proxy:

```
{
  channels: {
    telegram: {
      proxy: "socks5://user:password@proxy-host:1080"
    }
  }
}
```

### Port Security

The OpenClaw gateway runs on port 18789. On a VPS, **never expose this port publicly**. Keep it bound to localhost (the default: `gateway.bind: "127.0.0.1"`) and access it via SSH port forwarding or Caddy reverse proxy with authentication.

## Troubleshooting

| Problem | Solution |
| --- | --- |
| Bot doesn't reply to /start | Confirm gateway is running (`openclaw gateway status`), verify token is correct, check `openclaw logs` |
| Invalid token error | Recopy token from BotFather exactly. If you suspect it was leaked, run `/revoke` in BotFather and update the config |
| Pairing code expired | Codes expire after 1 hour. Send `/start` again to generate a fresh code, then approve quickly |
| Group bot not responding | Check that the bot is added to the group, Privacy Mode matches your config, and the group ID in config matches the actual ID |
| Intermittent failures on VPS | Likely IPv6 issue — add `network: { autoSelectFamily: false }` to the Telegram channel config |
| Other users can message my bot | Switch `dmPolicy` from `pairing` or `open` to `allowlist` and add only your IDs to `allowFrom` |

## More OpenClaw Guides

Continue your OpenClaw journey — every guide on the hub:

 [⚡ Quick Start: Install in 10 Minutes Install OpenClaw, connect a model, send your first message. Covers Anthropic, OpenAI, Ollama, and OpenRouter setups.](https://openclawdatabase.com/openclaw/setup/)

 [🛠 Skills Guide: Write Your Own How OpenClaw skills work, the SOUL.md hooks, debugging skill triggers, and shipping a custom skill.](https://openclawdatabase.com/openclaw/skills-guide/)

 [📚 Skills Database: 53 Verified Official Curated list of every official OpenClaw skill with what it does, what it needs, and known caveats.](https://openclawdatabase.com/openclaw/skills-database/)

 [🔐 Security Hardening Sandbox config, allowlists, API key hygiene, and the OpenClaw threat model — what to harden before connecting real accounts.](https://openclawdatabase.com/openclaw/security/)

 [⚙️ Configuration Reference Every config key explained: providers, channels, memory, scheduler, telemetry, and skill defaults.](https://openclawdatabase.com/openclaw/configuration/)

 [💰 Cost Optimisation: Under $10/Month Model routing, prompt caching, local fallbacks, and the heartbeat tweaks that keep monthly bills low.](https://openclawdatabase.com/openclaw/cost-optimisation/)

 [✉️ Channel Setup: Email IMAP/SMTP setup, OAuth scopes, draft-only sends, attachment handling, and the inbox-triage workflow.](https://openclawdatabase.com/openclaw/email/)

 [🧬 SOUL.md & Agent Personas How SOUL.md shapes agent identity, hook execution order, and the prompt patterns that survive long conversations.](https://openclawdatabase.com/openclaw/soul-md/)

 [🛠️ Troubleshooting — Every Error, Every Fix "Not replying", 429 errors, skill install failures, channel issues, memory DB locks — every common OpenClaw failure mode with the actual working fix.](https://openclawdatabase.com/openclaw/troubleshooting/)

[← Back to OpenClaw hub](https://openclawdatabase.com/openclaw/)

← Back to [OpenClaw hub](https://openclawdatabase.com/openclaw/) · See also: [Full Configuration Reference](https://openclawdatabase.com/openclaw/configuration/) · [Security Hardening](https://openclawdatabase.com/openclaw/security/)