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.

First-failure routing (use this before deep debugging)

When Telegram “doesn’t work”, classify the failure first:

1. Telegram never saw the message
   • Typical signs: no update reaches the bot in groups.
   • Usually Telegram-side visibility: privacy mode, missing admin rights, wrong group context.
2. Telegram saw the message, but OpenClaw ignored it
   • Typical signs: mentions work, normal group text does not; DM works but group does not.
   • Usually OpenClaw policy/routing: allowlist, groupPolicy, groups allowlist, requireMention.
3. Bot API requests fail
   • Typical signs: setMyCommands failed, sendMessage failures, probe failures.
   • Usually network path issues: DNS, IPv6 egress, proxy/firewall restrictions to api.telegram.org.

Fast deep links:

• Policy/routing sanity: /guides/openclaw-configuration
• Bot API network failures: /troubleshooting/solutions/telegram-setmycommands-failed

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 A: Telegram never saw the message (visibility layer)

Typical causes:

• Telegram privacy mode is still ON.
• The bot is not a group admin when your flow expects full group visibility.
• The bot was added/reconfigured but not re-added after privacy mode change.

Fix:

• Disable privacy mode and re-add the bot, or grant admin rights for the expected behavior.

Quick check:

• Mention the bot in-group (@your_bot ...). If mention works but plain text does not, move to Pitfall B.

Pitfall B: Telegram saw it, OpenClaw ignored it (policy/routing layer)

Most common OpenClaw-side causes:

• channels.telegram.groups is set, but this group ID is not included (and "*" is missing).
• requireMention: true is active while users send plain text.
• groupPolicy / groupAllowFrom is stricter than intended.

Quick test:

• In the same group, try mention the bot: @your_bot ...
• If mention works but normal text does not, your message-visibility path is fine and policy is the likely blocker.

Config deep link:

• /guides/openclaw-configuration

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 C: “setMyCommands failed / sendMessage failures” (network egress layer)

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.

Dedicated fix page:

• /troubleshooting/solutions/telegram-setmycommands-failed

Verification checklist after first setup

Before you call the setup done, verify:

• DM-first success: the bot responds in DM from one approved/allowed sender twice in a row.
• Group behavior is intentional: mention-only vs non-mention behavior matches your config.
• Failure boundary is clear: you can tell whether a miss is visibility, policy, or network without guessing.
• 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