Telegram

Status: production-ready for bot DMs + groups via grammY. Long polling is the default mode; webhook mode is optional.

Quick setup

Step 1: Create the bot token in BotFather

Open Telegram and chat with @BotFather (confirm the handle is exactly @BotFather).Run /newbot, follow prompts, and save the token.

Step 2: Configure token and DM policy

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}

Env fallback: TELEGRAM_BOT_TOKEN=... (default account only). Telegram does not use openclaw channels login telegram; configure token in config/env, then start gateway.

Step 3: Start gateway and approve first DM

openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

Pairing codes expire after 1 hour.

Step 4: Add the bot to a group

Add the bot to your group, then set channels.telegram.groups and groupPolicy to match your access model.

ℹ️ Token resolution order is account-aware. In practice, config values win over env fallback, and TELEGRAM_BOT_TOKEN only applies to the default account.

Telegram side settings

Access control and activation

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

Runtime behavior

• Telegram is owned by the gateway process.
• Routing is deterministic: Telegram inbound replies back to Telegram (the model does not pick channels).
• Inbound messages normalize into the shared channel envelope with reply metadata and media placeholders.
• Group sessions are isolated by group ID. Forum topics append :topic:<threadId> to keep topics isolated.
• DM messages can carry message_thread_id; OpenClaw routes them with thread-aware session keys and preserves thread ID for replies.
• Long polling uses grammY runner with per-chat/per-thread sequencing. Overall runner sink concurrency uses agents.defaults.maxConcurrent.
• Telegram Bot API has no read-receipt support (sendReadReceipts does not apply).

Feature reference

Troubleshooting

More help: Channel troubleshooting.

Telegram config reference pointers

Primary reference:

• channels.telegram.enabled: enable/disable channel startup.
• channels.telegram.botToken: bot token (BotFather).
• channels.telegram.tokenFile: read token from file path.
• channels.telegram.dmPolicy: pairing | allowlist | open | disabled (default: pairing).
• channels.telegram.allowFrom: DM allowlist (numeric Telegram user IDs). allowlist requires at least one sender ID. open requires "*". openclaw doctor --fix can resolve legacy @username entries to IDs and can recover allowlist entries from pairing-store files in allowlist migration flows.
• channels.telegram.actions.poll: enable or disable Telegram poll creation (default: enabled; still requires sendMessage).
• channels.telegram.defaultTo: default Telegram target used by CLI --deliver when no explicit --reply-to is provided.
• channels.telegram.groupPolicy: open | allowlist | disabled (default: allowlist).
• channels.telegram.groupAllowFrom: group sender allowlist (numeric Telegram user IDs). openclaw doctor --fix can resolve legacy @username entries to IDs. Non-numeric entries are ignored at auth time. Group auth does not use DM pairing-store fallback (2026.2.25+).
• Multi-account precedence:
  • When two or more account IDs are configured, set channels.telegram.defaultAccount (or include channels.telegram.accounts.default) to make default routing explicit.
  • If neither is set, OpenClaw falls back to the first normalized account ID and openclaw doctor warns.
  • channels.telegram.accounts.default.allowFrom and channels.telegram.accounts.default.groupAllowFrom apply only to the default account.
  • Named accounts inherit channels.telegram.allowFrom and channels.telegram.groupAllowFrom when account-level values are unset.
  • Named accounts do not inherit channels.telegram.accounts.default.allowFrom / groupAllowFrom.
• channels.telegram.groups: per-group defaults + allowlist (use "*" for global defaults).
  • channels.telegram.groups.<id>.groupPolicy: per-group override for groupPolicy (open | allowlist | disabled).
  • channels.telegram.groups.<id>.requireMention: mention gating default.
  • channels.telegram.groups.<id>.skills: skill filter (omit = all skills, empty = none).
  • channels.telegram.groups.<id>.allowFrom: per-group sender allowlist override.
  • channels.telegram.groups.<id>.systemPrompt: extra system prompt for the group.
  • channels.telegram.groups.<id>.enabled: disable the group when false.
  • channels.telegram.groups.<id>.topics.<threadId>.*: per-topic overrides (group fields + topic-only agentId).
  • channels.telegram.groups.<id>.topics.<threadId>.agentId: route this topic to a specific agent (overrides group-level and binding routing).
  • channels.telegram.groups.<id>.topics.<threadId>.groupPolicy: per-topic override for groupPolicy (open | allowlist | disabled).
  • channels.telegram.groups.<id>.topics.<threadId>.requireMention: per-topic mention gating override.
  • top-level bindings[] with type: "acp" and canonical topic id chatId:topic:topicId in match.peer.id: persistent ACP topic binding fields (see ACP Agents).
  • channels.telegram.direct.<id>.topics.<threadId>.agentId: route DM topics to a specific agent (same behavior as forum topics).
• channels.telegram.capabilities.inlineButtons: off | dm | group | all | allowlist (default: allowlist).
• channels.telegram.accounts.<account>.capabilities.inlineButtons: per-account override.
• channels.telegram.commands.nativeSkills: enable/disable Telegram native skills commands.
• channels.telegram.replyToMode: off | first | all (default: off).
• channels.telegram.textChunkLimit: outbound chunk size (chars).
• channels.telegram.chunkMode: length (default) or newline to split on blank lines (paragraph boundaries) before length chunking.
• channels.telegram.linkPreview: toggle link previews for outbound messages (default: true).
• channels.telegram.streaming: off | partial | block | progress (live stream preview; default: partial; progress maps to partial; block is legacy preview mode compatibility). In DMs, partial uses native sendMessageDraft when available.
• channels.telegram.mediaMaxMb: inbound/outbound Telegram media cap (MB, default: 100).
• channels.telegram.retry: retry policy for Telegram send helpers (CLI/tools/actions) on recoverable outbound API errors (attempts, minDelayMs, maxDelayMs, jitter).
• channels.telegram.network.autoSelectFamily: override Node autoSelectFamily (true=enable, false=disable). Defaults to enabled on Node 22+, with WSL2 defaulting to disabled.
• channels.telegram.network.dnsResultOrder: override DNS result order (ipv4first or verbatim). Defaults to ipv4first on Node 22+.
• channels.telegram.proxy: proxy URL for Bot API calls (SOCKS/HTTP).
• channels.telegram.webhookUrl: enable webhook mode (requires channels.telegram.webhookSecret).
• channels.telegram.webhookSecret: webhook secret (required when webhookUrl is set).
• channels.telegram.webhookPath: local webhook path (default /telegram-webhook).
• channels.telegram.webhookHost: local webhook bind host (default 127.0.0.1).
• channels.telegram.webhookPort: local webhook bind port (default 8787).
• channels.telegram.actions.reactions: gate Telegram tool reactions.
• channels.telegram.actions.sendMessage: gate Telegram tool message sends.
• channels.telegram.actions.deleteMessage: gate Telegram tool message deletes.
• channels.telegram.actions.sticker: gate Telegram sticker actions — send and search (default: false).
• channels.telegram.reactionNotifications: off | own | all — control which reactions trigger system events (default: own when not set).
• channels.telegram.reactionLevel: off | ack | minimal | extensive — control agent’s reaction capability (default: minimal when not set).
• Configuration reference - Telegram

Telegram-specific high-signal fields:

• startup/auth: enabled, botToken, tokenFile, accounts.*
• access control: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups, groups.*.topics.*, top-level bindings[] (type: "acp")
• command/menu: commands.native, commands.nativeSkills, customCommands
• threading/replies: replyToMode
• streaming: streaming (preview), blockStreaming
• formatting/delivery: textChunkLimit, chunkMode, linkPreview, responsePrefix
• media/network: mediaMaxMb, timeoutSeconds, retry, network.autoSelectFamily, proxy
• webhook: webhookUrl, webhookSecret, webhookPath, webhookHost
• actions/capabilities: capabilities.inlineButtons, actions.sendMessage|editMessage|deleteMessage|reactions|sticker
• reactions: reactionNotifications, reactionLevel
• writes/history: configWrites, historyLimit, dmHistoryLimit, dms.*.historyLimit

Related

• Pairing
• Channel routing
• Multi-agent routing
• Troubleshooting

SlackTlon