On this page
On this page
Mainstream messaging
Telegram
This page connects a Telegram bot to OpenClaw and sets who is allowed to message it.
Telegram is production-ready for bot DMs and groups via grammY. Long polling is the default transport. Webhook mode is optional.
Default DM policy for Telegram is pairing.
Cross-channel diagnostics and repair playbooks.
Full channel config patterns and examples.
What each page covers
- Telegram setup — install the bot, set the token, approve the first DM, and add the bot to a group.
- Telegram access control — DM policy, group allowlists, mention gating, and per-chat tool policy.
- Telegram message behavior — runtime model, stream previews, native commands, reply tags, and send limits.
- Telegram threads and sessions — forum topic session keys, per-topic agents, and ACP bindings.
- Telegram rich messages and approvals — Bot API 10.3 rich messages, inline buttons, message actions, and exec approvals.
- Telegram media and attachments — photo albums, voice and video notes, locations, venues, and stickers.
- Telegram events and operations — reaction notifications, config writes, and error reply policy.
- Telegram transports — long polling and webhook mode compared.
- Telegram Control UI Mini App — open the Control UI inside Telegram with
/controlui. - Telegram troubleshooting — silent groups, missing commands, rejected tokens, and unstable polling.
Where each section moved
Every section heading from the previous single-page version keeps its anchor here, so an existing link such as /channels/telegram#troubleshooting still resolves. Each entry points at the page that now holds the content.
- Quick setup
- Telegram side settings
- Control UI Mini App
- Access control and activation
- Group bot identity
- Finding your Telegram user ID
- Runtime behavior
- Feature reference
- Device pairing commands (
device-pairplugin) - Photo albums
- Audio messages
- Video messages
- Locations and venues
- Stickers
- Error reply controls
- Troubleshooting
- Device pairing commands (
device-pairplugin) - Create the bot token in BotFather
- Configure token and DM policy
- Verify the channel
- Approve your first DM
- Add the bot to a group
- Privacy mode and group visibility
- Group permissions
- Helpful BotFather toggles
- DM policy
- Group policy and allowlists
- Mention behavior
- Live stream preview (message edits)
- Rich message formatting
- Native commands and custom commands
- Inline buttons
- Telegram message actions for agents and automation
- Reply threading tags
- Forum topics and thread behavior
- Photo albums, audio, video, and stickers
- Reaction notifications
- Ack reactions
- Config writes from Telegram events and commands
- Long polling vs webhook
- Limits and CLI targets
- Exec approvals in Telegram
- Bot does not respond to non mention group messages
- Bot not seeing group messages at all
- Commands work partially or not at all
- Startup reports unauthorized token
- Polling or network instability
Configuration reference
Primary reference: Configuration reference - Telegram.
openclaw doctor --fix removes retired tuning settings (timeoutSeconds, mediaGroupFlushMs, pollingStallThresholdMs, retry, and errorCooldownMs) from their former configuration scopes. Account names and sender-specific tool-policy keys are preserved, even when they match a retired setting name.
High-signal Telegram fields
- startup/auth:
enabled,botToken,tokenFile(must be a regular file; symlinks are rejected),accounts.* - access control:
dmPolicy,allowFrom,direct.*.tools,direct.*.toolsBySender,groupPolicy,groupAllowFrom,groups,groups.*.topics.*, top-levelbindings[](type: "acp") - group introductions:
joinIntro,accounts.*.joinIntro(default:true) - topic defaults:
groups.<chatId>.topics."*"applies to unmatched forum topics; exact topic IDs override it - exec approvals:
execApprovals,accounts.*.execApprovals - command/menu:
commands.native,commands.nativeSkills,customCommands - threading/replies:
replyToMode,threadBindings - streaming:
streaming(modesoff | partial | block | progress),streaming.preview.toolProgress - formatting/delivery:
textChunkLimit,streaming.chunkMode,richMessages,markdown.tables(off | bullets | code | block),linkPreview,responsePrefix - media/network:
mediaMaxMb,network.autoSelectFamily,network.dangerouslyAllowPrivateNetwork,proxy - custom API root:
apiRoot(Bot API root only; do not include/bot<TOKEN>),trustedLocalFileRoots(self-hosted Bot API absolutefile_pathroots) - webhook:
webhookUrl,webhookSecret,webhookPath,webhookCertPath,legacyWebhook(optional explicit forwarding endpoint; omitted orfalseuses only the Gateway port) - actions/capabilities:
capabilities.inlineButtons,actions.sendMessage|editMessage|deleteMessage|reactions|sticker|createForumTopic|editForumTopic - reactions:
reactionNotifications,reactionLevel - errors:
errorPolicy,silentErrorReplies - writes/history:
configWrites,historyLimit,dmHistoryLimit,dms.*.historyLimit
Multi-agent account ownership
Each Telegram account needs a resolvable agent owner. To bind the default account
to main, add this entry to the top-level bindings array:
Use the configured agent and account IDs for your Gateway. A missing owner leaves that account blocked with the exact binding remediation in channel status; other accounts keep running. Add the binding and restart the Gateway.
When upgrading a legacy agents.list config, Doctor preserves the previous
implicit account owner in a binding before saving explicit ownership. Doctor
requires the original roster and never promotes a narrower conversation route
to account-wide ownership. Missing historical ownership requires an operator
choice; Doctor reports the exact binding to add without changing existing routes.
See migration repairs.
Related
Pair a Telegram user to the gateway.
Emoji reaction semantics for the message tool.
Group and topic allowlist behavior.
Route inbound messages to agents.
Threat model and hardening.
Map groups and topics to agents.
Cross-channel diagnostics.
