OpenClaw Telegram access control

A Telegram bot is reachable by anyone who guesses its username, so the access rules are the first thing to get right, and the docs give them more room than any other part of the channel. Here is the DM side, the two group controls that have to be read together, the mention rule, and the identifiers you need to fill them in. Changes to the DM policy, the allowlists and the group policy apply to new admissions without reconnecting Telegram, at the channel root and per account, while an already admitted turn keeps its captured settings.

Direct messages

• The DM policy has four values: pairing, the default, allowlist, which requires at least one sender ID, open, which requires the allowlist to include the wildcard, and disabled; an open policy with a wildcard lets any Telegram account that finds or guesses the bot username command the bot, so the docs reserve it for intentionally public bots with tightly restricted tools and tell one-owner bots to use an allowlist of numeric user IDs.
• The allowlist accepts numeric Telegram user IDs, with the telegram and tg prefixes normalised; an allowlist policy with an empty list blocks all DMs and is rejected by config validation; older setups with username entries can be resolved to numeric IDs by the doctor command with its fix flag, best-effort and requiring a bot token; and in multi-account configs a restrictive top-level allowlist is a safety boundary that an account-level wildcard does not override unless the merged effective list still contains an explicit wildcard.
• Pairing grants DM access only: an approved pairing does not authorise a sender everywhere, and group sender authorisation still comes from explicit config allowlists; if no command owner exists yet, the first approved pairing also sets the owner allowlist that owner-only commands and exec approvals use, and to be authorised for both DMs and group commands with one identity you put your numeric ID in the channel allowlist and make sure the owner list contains it with the telegram prefix.
• Per-DM tool policy lives under the direct map keyed by chat ID, with a wildcard entry for the rest; a sender-specific entry keyed by a typed sender key replaces the tools entry for that DM, an exact chat entry replaces the whole wildcard entry without inheriting its fields, an account-level direct map replaces the root map when present, and the selected direct policy, the global policy, the per-agent policy and the sender maps apply as intersecting layers where a deny in any layer still blocks the tool.

Common mistake: groupAllowFrom is not a group allowlist.

Groups: two controls that apply together

The first control is which groups are allowed, under the groups map: with no groups config and an open group policy any group passes the group-ID check, with no groups config and the default allowlist policy every group is blocked until you add entries or a wildcard, and once groups are configured the map acts as an allowlist of explicit IDs or the wildcard. The second control is which senders are allowed inside those groups, the group policy with its open, allowlist and disabled values, filtered by the group sender list; when that list is unset Telegram falls back to the channel allowlist, not to the pairing store, and group sender authorisation never inherits DM pairing approvals, a security boundary since the 2026.2.25 release. The entries must be numeric user IDs, non-numeric entries are ignored, and negative group or supergroup chat IDs belong under the groups map, never in the sender list. In multi-account configs the root groups map is the shared default for accounts that omit it, an account-level map replaces the root map rather than deep-merging, and an explicit empty account map keeps that account isolated from the shared groups. If the whole Telegram block is missing from the config, the runtime defaults to a fail-closed allowlist group policy unless the channel defaults say otherwise. The practical one-owner pattern is your user ID in the channel allowlist, the group sender list left unset, and the target groups listed under groups with the mention requirement on; you test it from the group by mentioning the bot with ping, and plain group messages do not trigger it while that requirement holds. A single group can be opened to every member with an open group policy and no mention requirement, or restricted to specific users with its own allowlist.

Mentions, history and identifiers

• Group replies require a mention by default, either a native mention of the bot username or a pattern from the agent or the global mention patterns; the activation commands switch a session between always and mention as state only, and persistence comes from the groups config, for instance a wildcard group entry that turns the requirement off.
• Group history context is always on and bounded by the history limit; setting the channel history limit to zero disables the window, and the doctor fix removes the retired include-group-history key.
• The safer way to find your user ID with no third-party bot is to DM the bot under the pairing policy and read the ID in its pairing reply, or to follow the logs and read the sender ID in the pairing request entry, both taken from the incoming message; use your numeric user ID, not a phone number, a username, a chat ID or the bot ID, do not broaden access just to discover it, and for a group chat ID forward a message to an ID bot, read the chat ID from the logs or the Bot API updates, or, once the group is allowed, run the whoami command addressed to the bot.

OpenClaw on Telegram is the channel post these rules belong to, and OpenClaw group chats the cross-channel behaviour of an agent inside a group.

Where the layers meet

The DM allowlist, the groups map, the group sender list and the per-chat tool policy are four separate answers to four separate questions, and most silent bots come from filling one of them with the answer to another. OpenClaw access groups shows how access groups generalise the same idea across channels, and OpenClaw channel routing how an admitted message then picks its agent.

On Diali

Telegram is one of the channels Diali connects; the connection is made from the dashboard and the runtime config is generated from it and replaced at each release, so these keys are the vocabulary behind that screen rather than a file to hand-edit. Telegram on Diali describes the channel on Diali and Diali security the boundary every connected channel shares.

• Numeric user IDs in the allowlist; negative chat IDs under groups.
• Pairing opens DMs only; groups need explicit config.
• Mention required by default; a wildcard group entry turns it off.