Telegram

Production-ready for bot DMs and groups via grammY. Long polling is the default mode; webhook mode is optional.

Pairing

Default DM policy for Telegram is pairing.

Channel troubleshooting

Cross-channel diagnostics and repair playbooks.

Gateway configuration

Full channel config patterns and examples.

Quick setup

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.

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.

Start gateway and approve first DM

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

Pairing codes expire after 1 hour.

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

Privacy mode and group visibility

Telegram bots default to Privacy Mode, which limits what group messages they receive.If the bot must see all group messages, either:

disable privacy mode via /setprivacy, or
make the bot a group admin.

When toggling privacy mode, remove + re-add the bot in each group so Telegram applies the change.

Group permissions

Admin status is controlled in Telegram group settings.Admin bots receive all group messages, which is useful for always-on group behavior.

Helpful BotFather toggles

/setjoingroups to allow/deny group adds
/setprivacy for group visibility behavior

Access control and activation

DM policy
Group policy and allowlists
Mention behavior

channels.telegram.dmPolicy controls direct message access:

pairing (default)
allowlist (requires at least one sender ID in allowFrom)
open (requires allowFrom to include "*")
disabled

dmPolicy: "open" with allowFrom: ["*"] lets any Telegram account that finds or guesses the bot username command the bot. Use it only for intentionally public bots with tightly restricted tools; one-owner bots should use allowlist with numeric user IDs.channels.telegram.allowFrom accepts numeric Telegram user IDs. telegram: / tg: prefixes are accepted and normalized. In multi-account configs, a restrictive top-level channels.telegram.allowFrom is treated as a safety boundary: account-level allowFrom: ["*"] entries do not make that account public unless the effective account allowlist still contains an explicit wildcard after merging. dmPolicy: "allowlist" with empty allowFrom blocks all DMs and is rejected by config validation. Setup asks for numeric user IDs only. If you upgraded and your config contains @username allowlist entries, run openclaw doctor --fix to resolve them (best-effort; requires a Telegram bot token). If you previously relied on pairing-store allowlist files, openclaw doctor --fix can recover entries into channels.telegram.allowFrom in allowlist flows (for example when dmPolicy: "allowlist" has no explicit IDs yet).For one-owner bots, prefer dmPolicy: "allowlist" with explicit numeric allowFrom IDs to keep access policy durable in config (instead of depending on previous pairing approvals).Common confusion: DM pairing approval does not mean “this sender is authorized everywhere”. Pairing grants DM access. If no command owner exists yet, the first approved pairing also sets commands.ownerAllowFrom so owner-only commands and exec approvals have an explicit operator account. Group sender authorization still comes from explicit config allowlists. If you want “I am authorized once and both DMs and group commands work”, put your numeric Telegram user ID in channels.telegram.allowFrom; for owner-only commands, make sure commands.ownerAllowFrom contains telegram:<your user id>.

Finding your Telegram user ID

Safer (no third-party bot):

DM your bot.
Run openclaw logs --follow.
Read from.id.

Official Bot API method:

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

Third-party method (less private): @userinfobot or @getidsbot.

Two controls apply together:

Which groups are allowed (channels.telegram.groups)
- no groups config:
  - with groupPolicy: "open": any group can pass group-ID checks
  - with groupPolicy: "allowlist" (default): groups are blocked until you add groups entries (or "*")
- groups configured: acts as allowlist (explicit IDs or "*")
Which senders are allowed in groups (channels.telegram.groupPolicy)
- open
- allowlist (default)
- disabled

groupAllowFrom is used for group sender filtering. If not set, Telegram falls back to allowFrom. groupAllowFrom entries should be numeric Telegram user IDs (telegram: / tg: prefixes are normalized). Do not put Telegram group or supergroup chat IDs in groupAllowFrom. Negative chat IDs belong under channels.telegram.groups. Non-numeric entries are ignored for sender authorization. Security boundary (2026.2.25+): group sender auth does not inherit DM pairing-store approvals. Pairing stays DM-only. For groups, set groupAllowFrom or per-group/per-topic allowFrom. If groupAllowFrom is unset, Telegram falls back to config allowFrom, not the pairing store. Practical pattern for one-owner bots: set your user ID in channels.telegram.allowFrom, leave groupAllowFrom unset, and allow the target groups under channels.telegram.groups. Runtime note: if channels.telegram is completely missing, runtime defaults to fail-closed groupPolicy="allowlist" unless channels.defaults.groupPolicy is explicitly set.Example: allow any member in one specific group:

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

Example: allow only specific users inside one specific group:

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          requireMention: true,
          allowFrom: ["8734062810", "745123456"],
        },
      },
    },
  },
}

Common mistake: groupAllowFrom is not a Telegram group allowlist.

Put negative Telegram group or supergroup chat IDs like -1001234567890 under channels.telegram.groups.
Put Telegram user IDs like 8734062810 under groupAllowFrom when you want to limit which people inside an allowed group can trigger the bot.
Use groupAllowFrom: ["*"] only when you want any member of an allowed group to be able to talk to the bot.

Group replies require mention by default.Mention can come from:

native @botusername mention, or
mention patterns in:
- agents.list[].groupChat.mentionPatterns
- messages.groupChat.mentionPatterns

Session-level command toggles:

/activation always
/activation mention

These update session state only. Use config for persistence.Persistent config example:

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: false },
      },
    },
  },
}

Getting the group chat ID:

forward a group message to @userinfobot / @getidsbot
or read chat.id from openclaw logs --follow
or inspect Bot API 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.
Long polling is guarded inside each gateway process so only one active poller can use a bot token at a time. If you still see getUpdates 409 conflicts, another OpenClaw gateway, script, or external poller is likely using the same token.
Long-polling watchdog restarts trigger after 120 seconds without completed getUpdates liveness by default. Increase channels.telegram.pollingStallThresholdMs only if your deployment still sees false polling-stall restarts during long-running work. The value is in milliseconds and is allowed from 30000 to 600000; per-account overrides are supported.
Telegram Bot API has no read-receipt support (sendReadReceipts does not apply).

Feature reference

Live stream preview (message edits)

OpenClaw can stream partial replies in real time:

direct chats: preview message + editMessageText
groups/topics: preview message + editMessageText

Requirement:

channels.telegram.streaming is off | partial | block | progress (default: partial)
progress maps to partial on Telegram (compat with cross-channel naming)
streaming.preview.toolProgress controls whether tool/progress updates reuse the same edited preview message (default: true when preview streaming is active)
legacy channels.telegram.streamMode and boolean streaming values are detected; run openclaw doctor --fix to migrate them to channels.telegram.streaming.mode

Tool-progress preview updates are the short “Working…” lines shown while tools run, for example command execution, file reads, planning updates, or patch summaries. Telegram keeps these enabled by default to match released OpenClaw behavior from v2026.4.22 and later. To keep the edited preview for answer text but hide tool-progress lines, set:

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "partial",
        "preview": {
          "toolProgress": false
        }
      }
    }
  }
}

Use streaming.mode: "off" only when you want final-only delivery: Telegram preview edits are disabled and generic tool/progress chatter is suppressed instead of being sent as standalone “Working…” messages. Approval prompts, media payloads, and errors still route through normal final delivery. Use streaming.preview.toolProgress: false when you only want to keep answer preview edits while hiding the tool-progress status lines.For text-only replies:

簡短的私訊/群組/主題預覽：OpenClaw 會保留相同的預覽訊息，並在原處執行最終編輯
超過約一分鐘的預覽：OpenClaw 會將完成的回覆作為新的最終訊息送出，然後清理預覽，因此 Telegram 可見的時間戳會反映完成時間，而不是預覽建立時間

對於複雜回覆（例如媒體 payload），OpenClaw 會退回一般最終傳遞，然後清理預覽訊息。預覽串流與區塊串流是分開的。當 Telegram 明確啟用區塊串流時，OpenClaw 會略過預覽串流，以避免雙重串流。如果原生草稿傳輸不可用/遭拒，OpenClaw 會自動退回 sendMessage + editMessageText。僅限 Telegram 的 reasoning 串流：

/reasoning stream 會在生成時將 reasoning 傳送到即時預覽
最終答案會在不含 reasoning 文字的情況下送出

格式化與 HTML 退回

對外文字使用 Telegram parse_mode: "HTML"。

類似 Markdown 的文字會轉譯為 Telegram 安全的 HTML。
原始模型 HTML 會被逸出，以減少 Telegram 解析失敗。
如果 Telegram 拒絕已解析的 HTML，OpenClaw 會以純文字重試。

連結預覽預設啟用，可透過 channels.telegram.linkPreview: false 停用。

原生命令與自訂命令

Telegram 命令選單註冊會在啟動時透過 setMyCommands 處理。原生命令預設值：

commands.native: "auto" 會為 Telegram 啟用原生命令

新增自訂命令選單項目：

{
  channels: {
    telegram: {
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
    },
  },
}

規則：

名稱會正規化（移除開頭的 /、轉為小寫）
有效模式：a-z、0-9、_，長度 1..32
自訂命令不能覆寫原生命令
衝突/重複項目會被略過並記錄

注意：

自訂命令只是選單項目；它們不會自動實作行為
plugin/skill 命令即使未顯示在 Telegram 選單中，輸入時仍可運作

如果停用原生命令，內建命令會被移除。Custom/plugin 命令若已設定，仍可能註冊。常見設定失敗：

setMyCommands failed 搭配 BOT_COMMANDS_TOO_MUCH 表示 Telegram 選單在修剪後仍然超出限制；請減少 plugin/skill/custom 命令，或停用 channels.telegram.commands.native。
當直接使用 Bot API curl 命令可運作，但 deleteWebhook、deleteMyCommands 或 setMyCommands 因 404: Not Found 失敗時，可能表示 channels.telegram.apiRoot 被設定為完整的 /bot<TOKEN> 端點。apiRoot 必須只包含 Bot API 根路徑，而 openclaw doctor --fix 會移除意外尾隨的 /bot<TOKEN>。
getMe returned 401 表示 Telegram 拒絕已設定的 bot token。請使用目前的 BotFather token 更新 botToken、tokenFile 或 TELEGRAM_BOT_TOKEN；OpenClaw 會在輪詢前停止，因此這不會被回報為 Webhook 清理失敗。
setMyCommands failed 搭配網路/fetch 錯誤，通常表示對 api.telegram.org 的對外 DNS/HTTPS 被封鎖。

裝置配對命令（`device-pair` plugin）

安裝 device-pair plugin 時：

/pair 產生設定程式碼
將程式碼貼到 iOS app
/pair pending 列出待處理請求（包含角色/scopes）
核准請求：
- /pair approve <requestId> 用於明確核准
- /pair approve 用於只有一個待處理請求時
- /pair approve latest 用於最近一筆

設定程式碼帶有短效 bootstrap token。內建 bootstrap 交接會將主要 node token 維持在 scopes: []；任何已交接的 operator token 都會限制在 operator.approvals、operator.read、operator.talk.secrets 和 operator.write。Bootstrap scope 檢查會加上角色前綴，因此該 operator allowlist 只滿足 operator 請求；非 operator 角色仍需要其自身角色前綴下的 scopes。如果裝置以變更後的驗證詳細資料重試（例如角色/scopes/公開金鑰），先前的待處理請求會被取代，新請求會使用不同的 requestId。核准前請重新執行 /pair pending。更多詳細資訊：配對。

行內按鈕

設定行內鍵盤範圍：

{
  channels: {
    telegram: {
      capabilities: {
        inlineButtons: "allowlist",
      },
    },
  },
}

每個帳號覆寫：

{
  channels: {
    telegram: {
      accounts: {
        main: {
          capabilities: {
            inlineButtons: "allowlist",
          },
        },
      },
    },
  },
}

範圍：

off
dm
group
all
allowlist（預設）

舊版 capabilities: ["inlineButtons"] 會對應到 inlineButtons: "all"。訊息動作範例：

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "Choose an option:",
  buttons: [
    [
      { text: "Yes", callback_data: "yes" },
      { text: "No", callback_data: "no" },
    ],
    [{ text: "Cancel", callback_data: "cancel" }],
  ],
}

Callback 點擊會作為文字傳給 agent： callback_data: <value>

供 agent 與自動化使用的 Telegram 訊息動作

Telegram 工具動作包含：

sendMessage（to、content、選用 mediaUrl、replyToMessageId、messageThreadId）
react（chatId、messageId、emoji）
deleteMessage（chatId、messageId）
editMessage（chatId、messageId、content）
createForumTopic（chatId、name、選用 iconColor、iconCustomEmojiId）

頻道訊息動作提供符合人體工學的別名（send、react、delete、edit、sticker、sticker-search、topic-create）。Gate 控制：

channels.telegram.actions.sendMessage
channels.telegram.actions.deleteMessage
channels.telegram.actions.reactions
channels.telegram.actions.sticker（預設：停用）

注意：edit 和 topic-create 目前預設啟用，且沒有個別的 channels.telegram.actions.* 切換。 Runtime 傳送會使用作用中的 config/secrets 快照（啟動/重新載入），因此動作路徑不會在每次傳送時執行臨時 SecretRef 重新解析。反應移除語意：/tools/reactions

回覆 threading 標籤

Telegram 支援在生成輸出中使用明確的回覆 threading 標籤：

[[reply_to_current]] 回覆觸發訊息
[[reply_to:<id>]] 回覆特定 Telegram 訊息 ID

channels.telegram.replyToMode 控制處理方式：

off（預設）
first
all

啟用回覆 threading 且原始 Telegram 文字或 caption 可用時，OpenClaw 會自動包含原生 Telegram 引言摘錄。Telegram 將原生引言文字限制為 1024 個 UTF-16 code units，因此較長訊息會從開頭開始引用，若 Telegram 拒絕引言，則退回純回覆。注意：off 會停用隱含回覆 threading。明確的 [[reply_to_*]] 標籤仍會被遵循。

論壇主題與 thread 行為

論壇 supergroups：

主題 session keys 會附加 :topic:<threadId>
回覆與 typing 會以主題 thread 為目標
主題 config 路徑： channels.telegram.groups.<chatId>.topics.<threadId>

一般主題（threadId=1）特殊情況：

訊息傳送會省略 message_thread_id（Telegram 會拒絕 sendMessage(...thread_id=1)）
typing 動作仍會包含 message_thread_id

主題繼承：主題項目會繼承群組設定，除非已覆寫（requireMention、allowFrom、skills、systemPrompt、enabled、groupPolicy）。 agentId 只屬於主題，不會從群組預設值繼承。每個主題的 agent 路由：每個主題都可以透過在主題 config 中設定 agentId 路由到不同的 agent。這讓每個主題都有自己的隔離工作區、記憶體和 session。範例：

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },      // General topic → main agent
            "3": { agentId: "zu" },        // Dev topic → zu agent
            "5": { agentId: "coder" }      // Code review → coder agent
          }
        }
      }
    }
  }
}

接著每個主題都有自己的 session key：agent:zu:telegram:group:-1001234567890:topic:3持久 ACP 主題綁定：論壇主題可透過頂層 typed ACP bindings（bindings[] 搭配 type: "acp"、match.channel: "telegram"、peer.kind: "group"，以及類似 -1001234567890:topic:42 的主題限定 id）釘選 ACP harness sessions。目前範圍限於 groups/supergroups 中的論壇主題。請參閱 ACP Agents。從聊天室產生 thread-bound ACP：/acp spawn <agent> --thread here|auto 會將目前主題綁定到新的 ACP session；後續訊息會直接路由至該處。OpenClaw 會將 spawn 確認釘選在主題內。需要 channels.telegram.threadBindings.spawnAcpSessions=true。Template context 會公開 MessageThreadId 和 IsForum。帶有 message_thread_id 的私訊聊天室會保留私訊路由，但使用 thread-aware session keys。

音訊、影片與貼圖

音訊訊息

Telegram 會區分語音備忘 vs 音訊檔案。

預設：音訊檔案行為
在 agent 回覆中加入標籤 [[audio_as_voice]] 以強制作為語音備忘傳送
內送語音備忘逐字稿會在 agent context 中被標示為機器生成、不受信任的文字；提及偵測仍會使用原始逐字稿，因此受提及 gate 控制的語音訊息仍可運作。

訊息動作範例：

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  media: "https://example.com/voice.ogg",
  asVoice: true,
}

影片訊息

Telegram 會區分影片檔案 vs 影片備忘。訊息動作範例：

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  media: "https://example.com/video.mp4",
  asVideoNote: true,
}

影片備忘不支援 caption；提供的訊息文字會另行傳送。

貼圖

內送貼圖處理：

靜態 WEBP：下載並處理（placeholder <media:sticker>）
動畫 TGS：略過
影片 WEBM：略過

貼圖 context 欄位：

Sticker.emoji
Sticker.setName
Sticker.fileId
Sticker.fileUniqueId
Sticker.cachedDescription

貼圖快取檔案：

~/.openclaw/telegram/sticker-cache.json

貼圖會被描述一次（可行時）並快取，以減少重複的視覺呼叫。啟用貼圖動作：

{
  channels: {
    telegram: {
      actions: {
        sticker: true,
      },
    },
  },
}

傳送貼圖動作：

{
  action: "sticker",
  channel: "telegram",
  to: "123456789",
  fileId: "CAACAgIAAxkBAAI...",
}

搜尋快取的貼圖：

{
  action: "sticker-search",
  channel: "telegram",
  query: "cat waving",
  limit: 5,
}

反應通知

Telegram 反應會以 message_reaction updates 抵達（與訊息 payloads 分開）。啟用後，OpenClaw 會將如下系統事件排入佇列：

Telegram reaction added: 👍 by Alice (@alice) on msg 42

Config:

channels.telegram.reactionNotifications: off | own | all（預設：own）
channels.telegram.reactionLevel: off | ack | minimal | extensive（預設：minimal）

備註：

own 表示僅限使用者對機器人傳送訊息的反應（透過已傳送訊息快取盡力處理）。
反應事件仍會遵守 Telegram 存取控制（dmPolicy、allowFrom、groupPolicy、groupAllowFrom）；未授權的傳送者會被丟棄。
Telegram 不會在反應更新中提供對話串 ID。
- 非論壇群組會路由到群組聊天工作階段
- 論壇群組會路由到群組的一般主題工作階段（:topic:1），而不是確切的原始主題

輪詢/Webhook 的 allowed_updates 會自動包含 message_reaction。

Ack 反應

ackReaction 會在 OpenClaw 處理傳入訊息時傳送確認表情符號。解析順序：

channels.telegram.accounts.<accountId>.ackReaction
channels.telegram.ackReaction
messages.ackReaction
agent 身分表情符號後援（agents.list[].identity.emoji，否則為「👀」）

備註：

Telegram 預期使用 unicode 表情符號（例如「👀」）。
使用 "" 可停用某個頻道或帳號的反應。

來自 Telegram 事件和命令的設定寫入

頻道設定寫入預設啟用（configWrites !== false）。Telegram 觸發的寫入包含：

群組遷移事件（migrate_to_chat_id），用於更新 channels.telegram.groups
/config set 和 /config unset（需要啟用命令）

停用：

{
  channels: {
    telegram: {
      configWrites: false,
    },
  },
}

長輪詢與 Webhook

預設為長輪詢。若要使用 Webhook 模式，請設定 channels.telegram.webhookUrl 和 channels.telegram.webhookSecret；可選擇設定 webhookPath、webhookHost、webhookPort（預設為 /telegram-webhook、127.0.0.1、8787）。本機監聽器會繫結到 127.0.0.1:8787。若要使用公開入口，請在本機連接埠前方放置反向代理，或有意地設定 webhookHost: "0.0.0.0"。Webhook 模式會先驗證請求防護、Telegram 密鑰權杖和 JSON 本文，才向 Telegram 回傳 200。 OpenClaw 接著會透過與長輪詢相同的每聊天/每主題機器人通道非同步處理更新，因此緩慢的 agent 回合不會卡住 Telegram 的傳遞 ACK。

限制、重試與 CLI 目標

channels.telegram.textChunkLimit 預設為 4000。
channels.telegram.chunkMode="newline" 會在依長度分割前優先使用段落邊界（空白行）。
channels.telegram.mediaMaxMb（預設 100）會限制傳入和傳出的 Telegram 媒體大小。
channels.telegram.timeoutSeconds 會覆寫 Telegram API 用戶端逾時（若未設定，則套用 grammY 預設值）。
channels.telegram.pollingStallThresholdMs 預設為 120000；只有在輪詢停滯重新啟動出現誤判時，才在 30000 到 600000 之間調整。
群組上下文歷史記錄使用 channels.telegram.historyLimit 或 messages.groupChat.historyLimit（預設 50）；0 會停用。
回覆/引用/轉寄的補充上下文目前會依收到的內容傳遞。
Telegram 允許清單主要管控誰可以觸發 agent，而不是完整的補充上下文遮蔽邊界。
私訊歷史記錄控制：
- channels.telegram.dmHistoryLimit
- channels.telegram.dms["<user_id>"].historyLimit
channels.telegram.retry 設定會套用到 Telegram 傳送輔助工具（CLI/工具/動作），用於可復原的傳出 API 錯誤。傳入最終回覆傳遞也會針對 Telegram 預連線失敗使用有界限的安全傳送重試，但不會重試可能造成可見訊息重複的不明確傳送後網路封包。

CLI 傳送目標可以是數值聊天 ID 或使用者名稱：

openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"

Telegram 投票使用 openclaw message poll，並支援論壇主題：

openclaw message poll --channel telegram --target 123456789 \
  --poll-question "Ship it?" --poll-option "Yes" --poll-option "No"
openclaw message poll --channel telegram --target -1001234567890:topic:42 \
  --poll-question "Pick a time" --poll-option "10am" --poll-option "2pm" \
  --poll-duration-seconds 300 --poll-public

僅限 Telegram 的投票旗標：

--poll-duration-seconds（5-600）
--poll-anonymous
--poll-public
--thread-id 用於論壇主題（或使用 :topic: 目標）

Telegram 傳送也支援：

當 channels.telegram.capabilities.inlineButtons 允許時，搭配 buttons 區塊的 --presentation 可用於行內鍵盤
--pin 或 --delivery '{"pin":true}' 可在機器人能於該聊天中釘選時要求釘選傳遞
--force-document 會將傳出圖片和 GIF 作為文件傳送，而不是使用壓縮相片或動畫媒體上傳

動作管控：

channels.telegram.actions.sendMessage=false 會停用傳出的 Telegram 訊息，包括投票
channels.telegram.actions.poll=false 會停用 Telegram 投票建立，同時保留一般傳送啟用

Telegram 中的執行核准

Telegram 支援在核准者私訊中進行執行核准，也可以選擇在原始聊天或主題中發布提示。核准者必須是數值 Telegram 使用者 ID。設定路徑：

channels.telegram.execApprovals.enabled（至少可解析一位核准者時會自動啟用）
channels.telegram.execApprovals.approvers（後援為 commands.ownerAllowFrom 中的數值擁有者 ID）
channels.telegram.execApprovals.target: dm（預設）| channel | both
agentFilter, sessionFilter

channels.telegram.allowFrom、groupAllowFrom 和 defaultTo 控制誰可以和機器人對話，以及機器人將一般回覆傳送到哪裡。它們不會讓某人成為執行核准者。當尚未存在命令擁有者時，第一個核准的私訊配對會啟動 commands.ownerAllowFrom，因此單一擁有者設定仍可運作，而不必在 execApprovals.approvers 下重複 ID。頻道傳遞會在聊天中顯示命令文字；只有在受信任的群組/主題中才啟用 channel 或 both。當提示出現在論壇主題中時，OpenClaw 會為核准提示和後續訊息保留該主題。執行核准預設會在 30 分鐘後過期。行內核准按鈕也需要 channels.telegram.capabilities.inlineButtons 允許目標介面（dm、group 或 all）。以 plugin: 為前綴的核准 ID 會透過 Plugin 核准解析；其他 ID 會先透過執行核准解析。請參閱執行核准。

錯誤回覆控制

當 agent 遇到傳遞或提供者錯誤時，Telegram 可以回覆錯誤文字，或隱藏錯誤。這個行為由兩個設定鍵控制：

鍵	值	預設值	說明
`channels.telegram.errorPolicy`	`reply`, `silent`	`reply`	`reply` 會向聊天傳送友善的錯誤訊息。`silent` 會完全隱藏錯誤回覆。
`channels.telegram.errorCooldownMs`	number (ms)	`60000`	對同一聊天傳送錯誤回覆之間的最短時間。可防止中斷期間出現錯誤垃圾訊息。

支援每帳號、每群組和每主題覆寫（繼承方式與其他 Telegram 設定鍵相同）。

{
  channels: {
    telegram: {
      errorPolicy: "reply",
      errorCooldownMs: 120000,
      groups: {
        "-1001234567890": {
          errorPolicy: "silent", // suppress errors in this group
        },
      },
    },
  },
}

疑難排解

機器人未回應非提及群組訊息

如果 requireMention=false，Telegram 隱私模式必須允許完整可見性。
- BotFather：/setprivacy -> Disable
- 然後移除機器人並重新加入群組
當設定預期未提及的群組訊息時，openclaw channels status 會發出警告。
openclaw channels status --probe 可以檢查明確的數值群組 ID；萬用字元 "*" 無法探測成員資格。
快速工作階段測試：/activation always。

機器人完全看不到群組訊息

當 channels.telegram.groups 存在時，群組必須列在其中（或包含 "*"）
驗證機器人在群組中的成員資格
檢閱記錄：使用 openclaw logs --follow 查看略過原因

命令只能部分運作或完全無法運作

授權你的傳送者身分（配對和/或數值 allowFrom）
即使群組政策是 open，命令授權仍會套用
setMyCommands failed 且出現 BOT_COMMANDS_TOO_MUCH 表示原生命令選單有太多項目；請減少 Plugin/skill/自訂命令，或停用原生選單
deleteMyCommands / setMyCommands 啟動呼叫有界限，且在請求逾時時會透過 Telegram 的傳輸後援重試一次。持續性的網路/擷取錯誤通常表示對 api.telegram.org 的 DNS/HTTPS 可達性問題

啟動回報未授權權杖

getMe returned 401 是已設定機器人權杖的 Telegram 驗證失敗。
在 BotFather 中重新複製或重新產生機器人權杖，然後更新預設帳號的 channels.telegram.botToken、channels.telegram.tokenFile、channels.telegram.accounts.<id>.botToken 或 TELEGRAM_BOT_TOKEN。
啟動期間的 deleteWebhook 401 Unauthorized 也是驗證失敗；將其視為「不存在 Webhook」只會把同一個錯誤權杖失敗延後到後續 API 呼叫。
如果 deleteWebhook 在輪詢啟動期間因暫時性網路錯誤而失敗，OpenClaw 會檢查 getWebhookInfo；當 Telegram 回報空的 Webhook URL 時，輪詢會繼續，因為清理已經滿足。

輪詢或網路不穩定

Node 22+ + 自訂 fetch/proxy 可能會在 AbortSignal 型別不相符時觸發立即中止行為。
有些主機會先將 api.telegram.org 解析為 IPv6；損壞的 IPv6 對外連線可能導致間歇性的 Telegram API 失敗。
如果日誌包含 TypeError: fetch failed 或 Network request for 'getUpdates' failed!，OpenClaw 現在會將這些作為可復原的網路錯誤重試。
如果日誌包含 Polling stall detected，OpenClaw 預設會在 120 秒內沒有完成長輪詢活性後，重新啟動輪詢並重建 Telegram 傳輸。
openclaw channels status --probe 和 openclaw doctor 會在執行中的輪詢帳戶於啟動寬限期後尚未完成 getUpdates、執行中的 webhook 帳戶於啟動寬限期後尚未完成 setWebhook，或最後一次成功的輪詢傳輸活動已過舊時發出警告。
只有在長時間執行的 getUpdates 呼叫正常，但你的主機仍回報錯誤的輪詢停滯重新啟動時，才增加 channels.telegram.pollingStallThresholdMs。持續停滯通常表示主機與 api.telegram.org 之間存在 proxy、DNS、IPv6 或 TLS 對外連線問題。
Telegram 也會遵循 Bot API 傳輸的程序 proxy 環境變數，包括 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 以及它們的小寫變體。NO_PROXY / no_proxy 仍可繞過 api.telegram.org。
如果服務環境透過 OPENCLAW_PROXY_URL 設定了 OpenClaw 受管 proxy，且沒有標準 proxy 環境變數，Telegram 也會將該 URL 用於 Bot API 傳輸。
在直接對外連線/TLS 不穩定的 VPS 主機上，請透過 channels.telegram.proxy 路由 Telegram API 呼叫：

channels:
  telegram:
    proxy: socks5://<user>:<password>@proxy-host:1080

Node 22+ 預設為 autoSelectFamily=true（WSL2 除外）和 dnsResultOrder=ipv4first。
如果你的主機是 WSL2，或明確以僅 IPv4 行為運作得更好，請強制指定位址族選擇：

channels:
  telegram:
    network:
      autoSelectFamily: false

RFC 2544 基準測試範圍的答案（198.18.0.0/15）預設已允許用於 Telegram 媒體下載。如果受信任的 fake-IP 或透明 proxy 在媒體下載期間將 api.telegram.org 重寫為其他私有/內部/特殊用途位址，你可以選擇啟用僅限 Telegram 的繞過：

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

同樣的選擇啟用可在每個帳戶層級透過 channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork 使用。
如果你的 proxy 將 Telegram 媒體主機解析為 198.18.x.x，請先保持危險旗標關閉。Telegram 媒體預設已允許 RFC 2544 基準測試範圍。

channels.telegram.network.dangerouslyAllowPrivateNetwork 會削弱 Telegram 媒體 SSRF 防護。僅在受信任、由操作者控制的 proxy 環境中使用，例如 Clash、Mihomo 或 Surge fake-IP 路由，且它們會合成 RFC 2544 基準測試範圍之外的私有或特殊用途答案。一般公開網際網路 Telegram 存取請保持關閉。

環境覆寫（暫時）：
- OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1
- OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1
- OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first
驗證 DNS 答案：

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

更多協助：Channel 疑難排解。

設定參考

主要參考：設定參考 - Telegram。

高資訊量 Telegram 欄位

啟動/驗證：enabled、botToken、tokenFile、accounts.*（tokenFile 必須指向一般檔案；符號連結會被拒絕）
存取控制：dmPolicy、allowFrom、groupPolicy、groupAllowFrom、groups、groups.*.topics.*、頂層 bindings[]（type: "acp"）
exec 核准：execApprovals、accounts.*.execApprovals
指令/選單：commands.native、commands.nativeSkills、customCommands
執行緒/回覆：replyToMode
串流：streaming（預覽）、streaming.preview.toolProgress、blockStreaming
格式化/傳遞：textChunkLimit、chunkMode、linkPreview、responsePrefix
媒體/網路：mediaMaxMb、timeoutSeconds、pollingStallThresholdMs、retry、network.autoSelectFamily、network.dangerouslyAllowPrivateNetwork、proxy
自訂 API 根目錄：apiRoot（僅 Bot API 根目錄；不要包含 /bot<TOKEN>）
Webhook：webhookUrl、webhookSecret、webhookPath、webhookHost
動作/能力：capabilities.inlineButtons、actions.sendMessage|editMessage|deleteMessage|reactions|sticker
回應：reactionNotifications、reactionLevel
錯誤：errorPolicy、errorCooldownMs
寫入/歷史記錄：configWrites、historyLimit、dmHistoryLimit、dms.*.historyLimit

多帳戶優先順序：設定兩個或更多帳戶 ID 時，請設定 channels.telegram.defaultAccount（或包含 channels.telegram.accounts.default），以明確指定預設路由。否則 OpenClaw 會退回到第一個正規化的帳戶 ID，且 openclaw doctor 會發出警告。命名帳戶會繼承 channels.telegram.allowFrom / groupAllowFrom，但不會繼承 accounts.default.* 值。

配對

將 Telegram 使用者與 Gateway 配對。

群組

群組與主題允許清單行為。

Channel 路由

將傳入訊息路由到代理。

安全性

威脅模型與強化。

多代理路由

將群組與主題對應到代理。

疑難排解

跨 Channel 診斷。

Overview

Mainstream messaging

Developer and self-hosted

Regional platforms

Configuration

Pairing

Channel troubleshooting

Gateway configuration

Quick setup

Telegram side settings

Access control and activation

Finding your Telegram user ID

Runtime behavior

Feature reference

裝置配對命令（`device-pair` plugin）

音訊訊息

影片訊息

貼圖

錯誤回覆控制

疑難排解

設定參考

相關

配對

群組

Channel 路由

安全性

多代理路由

疑難排解

Overview

Mainstream messaging

Developer and self-hosted

Regional platforms

Configuration

Documentation Index

Pairing

Channel troubleshooting

Gateway configuration

​Quick setup

​Telegram side settings

​Access control and activation

​Finding your Telegram user ID

​Runtime behavior

​Feature reference

​裝置配對命令（device-pair plugin）

​音訊訊息

​影片訊息

​貼圖

​錯誤回覆控制

​疑難排解

​設定參考

​相關

配對

群組

Channel 路由

安全性

多代理路由

疑難排解

Quick setup

Telegram side settings

Access control and activation

Finding your Telegram user ID

Runtime behavior

Feature reference

裝置配對命令（`device-pair` plugin）

音訊訊息

影片訊息

貼圖

錯誤回覆控制

疑難排解

設定參考

相關