Telegram + OpenClaw: Setup, Group Controls, and Common Pitfalls

What this guide helps you finish

By the end of this guide, you should have a Telegram bot connected to OpenClaw, locked down with the right DM/group rules, and verified in both direct messages and the group pattern you actually plan to use.

Who this is for (and not for)

This guide is for first-time Telegram operators who want one stable bot path with clear access control.

It is not the best page if your Telegram bot is already installed and you only need a narrow symptom fix.

Before you start: collect these four facts

Before you configure Telegram, decide:

1. whether the bot should serve only DMs, only groups, or both,
2. whether unknown DM senders should pair or be blocked outright,
3. whether groups should be mention-only or always-on,
4. whether your host has reliable outbound access to api.telegram.org.

Those four choices prevent most “Telegram is flaky” misdiagnoses later.

Why Telegram is a great first channel

Telegram is a clean “day-0” channel for OpenClaw:

• Bot tokens are simple (no browser QR login).
• DMs and groups both work well.
• You get strong routing control: group sessions stay isolated by default.

Official references:

• OpenClaw Telegram channel docs: https://docs.openclaw.ai/channels/telegram
• OpenClaw FAQ (Telegram + dashboard auth gotchas): https://docs.openclaw.ai/help/faq
• BotFather /setprivacy reference: https://telegram.me/s/BotFther

If you’re still getting comfortable with openclaw.json (paths, env vars, allowlists, model refs), see:

• /guides/openclaw-configuration

Step 1: Create the bot token (BotFather)

In Telegram, open @BotFather:

1. Run /newbot
2. Choose a name and a username (must end in bot)
3. Copy the token

Optional BotFather settings that matter for OpenClaw:

• /setjoingroups: whether the bot can be added to groups at all.
• /setprivacy: whether the bot receives all group messages or only mentions/replies.

Step 2: Minimal OpenClaw config (safe defaults)

Edit ~/.openclaw/openclaw.json (JSON5 is allowed; comments and trailing commas are OK):

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",

      // Secure by default: unknown senders must be approved
      dmPolicy: "pairing",

      // Optional hardening: block Telegram-initiated config writes (advanced).
      // This prevents things like supergroup ID migration writes and /config set|unset.
      // configWrites: false,
    },
  },
}

Then restart the gateway:

openclaw gateway restart

Open the dashboard:

openclaw dashboard

Step 3: DM access control (pairing vs allowlist)

Option A (recommended for most users): pairing

Pairing is the safest default for DMs. On first contact, the user receives a pairing code and the bot ignores messages until you approve it. Approvals are written into credentials state.

Commands:

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

Option B: allowlist

If you already know exactly who should be able to DM the bot, use an allowlist:

{
  channels: {
    telegram: {
      dmPolicy: "allowlist",
      // Use Telegram numeric user IDs when possible (more reliable than usernames).
      // Prefix with `tg:` to make the identity explicit.
      allowFrom: ["tg:123456789"],
    },
  },
}

How to get your Telegram user ID without using third-party bots:

1. Start the gateway and DM your bot once.
2. Run openclaw logs --follow on the gateway host and look for from.id.

Step 4: Groups (the #1 “why is it ignoring us?” source)

There are two separate layers to understand:

1. Telegram-side message visibility (privacy mode / admin rights)
2. OpenClaw-side group access controls (which groups, who can speak, and whether mentions are required)

4.1 Telegram-side: Privacy Mode vs Admin

Telegram bots default to privacy mode ON, which means the bot often only sees:

• mentions, commands, and replies to the bot

If you want the bot to see all messages in a group:

• BotFather: /setprivacy -> Disable
• Then remove + re-add the bot to the group (Telegram requirement)

Alternatively, make the bot a group admin (admin bots can see all messages regardless of privacy mode).

4.2 OpenClaw-side: group allowlist + mention rules

OpenClaw group behavior is intentionally explicit and has 3 knobs:

1. Which groups are allowed: channels.telegram.groups (allowlist when present)
2. Which senders are allowed inside groups: channels.telegram.groupPolicy + groupAllowFrom
3. Whether the bot should require mentions: groups.*.requireMention

• If you set channels.telegram.groups, it becomes a group allowlist.
• If a group is not in the allowlist, messages are ignored.

Default behavior for group replies is “mention-only”. A good starting configuration is:

{
  channels: {
    telegram: {
      // Allow any group (still keep mention-only)
      groups: {
        "*": { requireMention: true },
      },

      // IMPORTANT: by default, groupPolicy is allowlist (blocked unless you allow senders).
      // If you want the bot to respond to everyone in allowed groups, set:
      groupPolicy: "open",
    },
  },
}

If you want a specific group to be always-on (no mention required):

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

      // Safer default than "open": restrict group senders (example: only you).
      // groupPolicy: "allowlist",
      // groupAllowFrom: ["tg:123456789"],
    },
  },
}

Note: if you set requireMention: false, Telegram privacy mode must be disabled (or the bot must be a group admin), otherwise the bot will not receive unmentioned messages.

Important: if you set a specific numeric group ID, but you forget "*" and you later add the bot to other groups, it will ignore them (because you turned on the allowlist).

4.3 Getting the group chat ID (safe options)

Safer (no third-party bots):

1. Add the bot to the group.
2. Send any message that the bot can see (mention it if privacy mode is on).
3. On the gateway host: openclaw logs --follow and read chat.id.

Official Bot API method (also safe):

curl "https://api.telegram.org/bot<bot_token>/getUpdates"

Look for message.chat.id in the JSON.

Step 5: Common pitfalls and fixes

Pitfall: “Bot sees mentions but not normal messages”

• Telegram privacy mode is still ON, or the bot is not an admin.
• Fix: disable privacy mode (and re-add the bot) or grant admin.

Pitfall: “Bot is in the group but never responds”

Most common OpenClaw-side causes:

• You set channels.telegram.groups but did not include this group ID (and did not include "*").
• The group requires mentions (requireMention: true) but you are not mentioning the bot.

Quick test:

• In the group, try mention the bot: @your_bot ...

Pitfall: “Telegram configured but (plugin disabled)” / “plugin not available”

If you configured the token but the gateway reports something like:

• configured (plugin disabled)
• plugin not available

It usually means OpenClaw saw your Telegram config, but the channel is not actually enabled/loaded in the running gateway process.

Start with these checks (on the gateway host):

openclaw config get channels.telegram.enabled
openclaw config get channels.telegram.botToken
openclaw doctor

Then:

1. Ensure channels.telegram.enabled: true is set in the config file the gateway is actually reading.
2. Restart the gateway to force the channel to reinitialize:

openclaw gateway restart

If this started after an update, see the updating guide (and consider temporarily pinning a known-good version):

• /guides/updating-and-migration

Dedicated fix page:

• /troubleshooting/solutions/telegram-plugin-configured-but-disabled

Pitfall: “TTS arrives as an audio file” / “Telegram sends two outputs”

If Telegram TTS sends a normal audio file instead of a round voice bubble, or one turn produces both audio and a second narrative reply, the problem is usually one of these:

• Edge TTS output format is not ideal for Telegram voice-note UX
• /tts local prefs are overriding the main config
• auto-TTS mode is too aggressive for the workflow

Dedicated fix page:

• /troubleshooting/solutions/telegram-tts-audio-file-instead-of-voice-bubble

Pitfall: “setMyCommands failed / sendMessage failures”

This usually means the gateway host cannot reliably reach api.telegram.org:

• outbound HTTPS blocked (firewall / corporate proxy)
• DNS issues
• IPv6 issues (host resolves AAAA first but IPv6 egress is broken)

Debug checklist:

openclaw channels status
openclaw channels status --probe
openclaw channels logs --channel telegram
openclaw logs --follow

On a VPS, also check DNS and IPv6:

dig +short api.telegram.org A
dig +short api.telegram.org AAAA

If AAAA exists but your server has no IPv6 egress, fix IPv6 routing or prefer IPv4 at the OS layer.

Verification checklist after first setup

Before you call the setup done, verify:

• the bot responds in DM from one approved/allowed sender
• the bot behaves in groups exactly the way you intended (mention-only or not)
• you can identify the group ID and sender IDs without guesswork
• one restart of the gateway does not change the access behavior

What to tighten first if Telegram feels risky

If the channel feels too open or noisy, tighten in this order:

1. DM policy
2. group allowlist / sender policy
3. mention requirements
4. host egress reliability and logging visibility

Optional: webhook mode (when you actually need it)

Long-polling is easiest and works well on most machines.

Use webhooks only when:

• you must run behind an HTTPS endpoint and cannot keep long-polling alive, or
• your environment requires inbound-only traffic (rare)

If you go down the webhook route, plan for:

• a stable public HTTPS URL
• network egress to Telegram
• secret management for tokens

Suggested next guides

• WhatsApp setup: /guides/whatsapp-setup
• Docker gateway setup: /guides/docker-deployment
• Control UI auth/pairing: /guides/control-ui-auth-and-pairing
• Tool allowlists and sandbox policy: /guides/custom-tools