Telegram

• 透過 /setprivacy 停用隱私模式，或
• 將機器人設為群組管理員。

• /setjoingroups 用於允許/拒絕加入群組
• /setprivacy 用於群組可見性行為

• 直接聊天：預覽訊息 + editMessageText
• 群組/主題：預覽訊息 + editMessageText

• channels.telegram.streaming 是 off | partial | block | progress（預設：partial）
• progress 會為工具進度保留一則可編輯的狀態草稿，在完成時清除它，並以一般訊息傳送最終回答
• streaming.preview.toolProgress 控制工具/進度更新是否重複使用同一則已編輯的預覽訊息（預設：預覽串流啟用時為 true）
• streaming.preview.commandText 控制這些工具進度行內的命令/執行細節：raw（預設，保留已發布行為）或 status（僅工具標籤）
• 會偵測舊版 channels.telegram.streamMode 和布林值 streaming 值；執行 openclaw doctor --fix 可將它們遷移到 channels.telegram.streaming.mode

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

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "partial",
        "preview": {
          "commandText": "status"
        }
      }
    }
  }
}

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "progress",
        "progress": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}

• 簡短的 DM/群組/主題預覽：OpenClaw 會保留同一則預覽訊息，並就地執行最終編輯
• 會拆分成多則 Telegram 訊息的長文字最終結果，會在可能時將現有預覽重用為第一個最終區塊，然後只傳送剩餘區塊
• 進度模式的最終結果會清除狀態草稿，並使用一般最終傳送，而不是將草稿編輯成回答
• 如果在確認完成文字之前最終編輯失敗，OpenClaw 會使用一般最終傳送並清理過時的預覽

• /reasoning stream 會在產生期間將推理傳送到即時預覽
• 推理預覽會在最終傳送後刪除；當推理應保持可見時，請使用 /reasoning on
• 最終回答會在不含推理文字的情況下傳送

• 類 Markdown 文字會轉譯為 Telegram 安全的 HTML。
• 受支援的 Telegram HTML 標籤會保留；不受支援的 HTML 會被逸出。
• 如果 Telegram 拒絕已解析的 HTML，OpenClaw 會以純文字重試。

• 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 選單中，輸入時仍可運作

• setMyCommands failed 搭配 BOT_COMMANDS_TOO_MUCH 表示 Telegram 選單在裁剪後仍然溢出；請減少 Plugin/skill/自訂命令，或停用 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 權杖。請使用目前的 BotFather 權杖更新 botToken、tokenFile 或 TELEGRAM_BOT_TOKEN；OpenClaw 會在輪詢前停止，因此這不會被回報為 Webhook 清理失敗。
• setMyCommands failed 搭配網路/擷取錯誤，通常表示到 api.telegram.org 的傳出 DNS/HTTPS 被封鎖。

​

裝置配對命令（device-pair Plugin）

1. /pair 產生設定碼
2. 在 iOS 應用程式中貼上程式碼
3. /pair pending 列出待處理要求（包含角色/範圍）
4. 核准要求：
   • /pair approve <requestId> 用於明確核准
   • /pair approve 用於只有一個待處理要求時
   • /pair approve latest 用於最近的要求

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

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

• off
• dm
• group
• all
• allowlist（預設）

{
  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" }],
  ],
}

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

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

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

• off（預設）
• first
• all

• 主題工作階段鍵會附加 :topic:<threadId>
• 回覆和輸入狀態會指向主題討論串
• 主題設定路徑： channels.telegram.groups.<chatId>.topics.<threadId>

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

{
  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
          }
        }
      }
    }
  }
}

​

音訊訊息

• 預設：音訊檔案行為
• 在 agent 回覆中加入標記 [[audio_as_voice]] 可強制以語音訊息傳送
• 傳入語音訊息的逐字稿會在 agent 內容中被框定為機器產生、 不受信任的文字；提及偵測仍會使用原始逐字稿， 因此受提及閘控的語音訊息會繼續運作。

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

​

影片訊息

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

​

貼圖

• 靜態 WEBP：已下載並處理（預留位置 <media:sticker>）
• 動態 TGS：已略過
• 影片 WEBM：已略過

• 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 reaction added: 👍 by Alice (@alice) on msg 42

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

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

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

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

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

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

• channels.telegram.textChunkLimit 預設值為 4000。
• channels.telegram.chunkMode="newline" 會在依長度分割之前優先使用段落邊界（空白行）。
• channels.telegram.mediaMaxMb（預設值 100）會限制傳入和傳出 Telegram 媒體大小。
• channels.telegram.mediaGroupFlushMs（預設值 500）控制 Telegram 相簿/媒體群組在 OpenClaw 將其作為一則傳入訊息分派之前的緩衝時間。如果相簿部分抵達較晚，請增加此值；若要降低相簿回覆延遲，請減少此值。
• channels.telegram.timeoutSeconds 會覆寫 Telegram API 用戶端逾時（若未設定，則套用 grammY 預設值）。Bot 用戶端會將低於 60 秒傳出文字/輸入請求防護的設定值箝制，以免 grammY 在 OpenClaw 的傳輸防護和備援能執行前中止可見回覆傳遞。長輪詢仍會使用 45 秒的 getUpdates 請求防護，因此閒置輪詢不會無限期遭到放棄。
• channels.telegram.pollingStallThresholdMs 預設為 120000；只有在輪詢停滯重新啟動出現誤判時，才在 30000 到 600000 之間調整。
• 群組內容歷史使用 channels.telegram.historyLimit 或 messages.groupChat.historyLimit（預設值 50）；0 會停用。
• 當 Gateway 已觀察到父訊息時，回覆/引用/轉寄的補充內容會正規化為一個選定的對話內容視窗；已觀察訊息快取會持久保存於工作階段儲存旁。Telegram 在更新中只包含一層淺層的 reply_to_message，因此早於快取的鏈結會受限於 Telegram 目前的更新承載資料。
• Telegram 允許清單主要控管誰可以觸發 agent，而不是完整的補充內容遮罩邊界。
• DM 歷史控制：
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• channels.telegram.retry 設定適用於 Telegram 傳送輔助程式（CLI/tools/actions），用於可復原的傳出 API 錯誤。傳入最終回覆傳遞也會針對 Telegram 預連線失敗使用有界限的安全傳送重試，但不會重試可能重複可見訊息的模糊傳送後網路封包。

openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"
openclaw message send --channel telegram --target -1001234567890:topic:42 --message "hi topic"

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

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

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

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

• channels.telegram.execApprovals.enabled（至少有一位核准者可解析時自動啟用）
• channels.telegram.execApprovals.approvers（備援為來自 commands.ownerAllowFrom 的數字擁有者 ID）
• channels.telegram.execApprovals.target：dm（預設）| channel | both
• agentFilter、sessionFilter

• 如果 requireMention=false，Telegram 隱私模式必須允許完整可見性。
  • BotFather：/setprivacy -> 停用
  • 然後將機器人從群組移除並重新加入
• 當設定預期接收未提及的群組訊息時，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 啟動呼叫和 sendChatAction 輸入狀態呼叫都有界限，且在請求逾時時會透過 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 呼叫。

• Node 22+ 搭配自訂 fetch/proxy 時，如果 AbortSignal 型別不相符，可能會觸發立即中止行為。
• 某些主機會先將 api.telegram.org 解析為 IPv6；損壞的 IPv6 輸出可能導致間歇性 Telegram API 失敗。
• 如果日誌包含 TypeError: fetch failed 或 Network request for 'getUpdates' failed!，OpenClaw 現在會將這些錯誤當作可復原的網路錯誤重試。
• 輪詢啟動期間，OpenClaw 會為 grammY 重用成功的啟動 getMe 探測，因此執行器在第一次 getUpdates 前不需要第二次 getMe。
• 如果 deleteWebhook 在輪詢啟動期間因暫時性網路錯誤而失敗，OpenClaw 會繼續進入長輪詢，而不是再進行另一個輪詢前控制平面呼叫。仍啟用的 Webhook 會以 getUpdates 衝突呈現；OpenClaw 接著會重建 Telegram 傳輸並重試 Webhook 清理。
• 如果 Telegram socket 以短固定週期回收，請檢查 channels.telegram.timeoutSeconds 是否偏低；機器人用戶端會將低於輸出和 getUpdates 請求防護值的設定值夾制，但較舊版本在此值低於這些防護值時，可能會在每次輪詢或回覆時中止。
• 如果日誌包含 Polling stall detected，OpenClaw 預設會在 120 秒內沒有完成的長輪詢存活訊號後，重新啟動輪詢並重建 Telegram 傳輸。
• 當正在執行的輪詢帳號在啟動寬限期後尚未完成 getUpdates、正在執行的 Webhook 帳號在啟動寬限期後尚未完成 setWebhook，或最後一次成功的輪詢傳輸活動已過期時，openclaw channels status --probe 和 openclaw doctor 會發出警告。
• 只有在長時間執行的 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 是透過服務環境的 OPENCLAW_PROXY_URL 設定，且沒有標準 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 除外）。Telegram DNS 結果順序會依序遵循 OPENCLAW_TELEGRAM_DNS_RESULT_ORDER、channels.telegram.network.dnsResultOrder，再到程序預設值，例如 NODE_OPTIONS=--dns-result-order=ipv4first；如果都不適用，Node 22+ 會退回 ipv4first。
• 如果你的主機是 WSL2，或明確在僅 IPv4 行為下運作較佳，請強制家族選擇：

channels:
  telegram:
    network:
      autoSelectFamily: false

• 預設已允許 Telegram 媒體下載使用 RFC 2544 基準測試範圍答案（198.18.0.0/15）。如果受信任的 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 基準測試範圍。

• 環境覆寫（暫時）：
  • 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