OpenClaw Telegram Setup — BotFather to Production

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.

Useful BotFather Commands

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.

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