Telegram

Telegram bots のデフォルトは Privacy Mode で、これにより受信できるグループメッセージが制限されます。

bot がすべてのグループメッセージを見る必要がある場合は、次のいずれかを行います。

• /setprivacy でプライバシーモードを無効にする、または
• bot をグループ管理者にする。

プライバシーモードを切り替えたら、Telegram が変更を適用できるように、各グループで bot を削除して再追加してください。

管理者ステータスは Telegram のグループ設定で制御されます。

管理者 bot はすべてのグループメッセージを受信します。これは、常時有効なグループ動作に役立ちます。

• /setjoingroups でグループ追加を許可/拒否
• /setprivacy でグループでの可視性の動作を設定

OpenClaw は部分返信をリアルタイムでストリーミングできます。

• ダイレクトチャット: プレビューメッセージ + editMessageText
• グループ/トピック: プレビューメッセージ + editMessageText

要件:

• channels.telegram.streaming は off | partial | block | progress です（デフォルト: partial）
• progress はツール進捗用の編集可能なステータス下書きを 1 つ保持し、完了時にそれをクリアして、最終回答を通常メッセージとして送信します
• streaming.preview.toolProgress は、ツール/進捗更新が同じ編集済みプレビューメッセージを再利用するかどうかを制御します（プレビューストリーミングが有効な場合のデフォルト: true）
• streaming.preview.commandText は、それらのツール進捗行内のコマンド/exec 詳細を制御します: raw（デフォルト、リリース済みの動作を保持）または status（ツールラベルのみ）
• レガシーの channels.telegram.streamMode と boolean の streaming 値は検出されます。openclaw doctor --fix を実行して channels.telegram.streaming.mode に移行してください

ツール進捗プレビュー更新は、ツールの実行中に表示される短いステータス行です。たとえば、コマンド実行、ファイル読み取り、計画更新、パッチ要約などです。Telegram では、v2026.4.22 以降のリリース済み OpenClaw 動作に合わせるため、これらはデフォルトで有効です。回答テキスト用の編集済みプレビューは保持しつつツール進捗行を非表示にするには、次を設定します。

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

ツール進捗を表示したままコマンド/exec テキストを非表示にするには、次を設定します。

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

最終回答を同じメッセージに編集し込まず、目に見えるツール進行状況を出したい場合は progress モードを使用します。コマンドテキストポリシーは streaming.progress の下に置きます。

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

最終結果だけを配信したい場合にのみ streaming.mode: "off" を使用します。Telegram のプレビュー編集は無効になり、汎用的なツール/進行状況の雑談は単独のステータスメッセージとして送信される代わりに抑制されます。承認プロンプト、メディアペイロード、エラーは引き続き通常の最終配信経路を通ります。回答プレビュー編集だけを維持し、ツール進行状況のステータス行を隠したい場合は streaming.preview.toolProgress: false を使用します。

テキストのみの返信の場合:

• 短い DM/グループ/トピックのプレビュー: OpenClaw は同じプレビューメッセージを維持し、その場で最終編集を実行します
• 複数の Telegram メッセージに分割される長いテキストの最終結果では、可能な場合は既存のプレビューを最初の最終チャンクとして再利用し、その後に残りのチャンクだけを送信します
• progress モードの最終結果では、ステータス下書きをクリアし、下書きを回答に編集する代わりに通常の最終配信を使用します
• 完了テキストが確認される前に最終編集が失敗した場合、OpenClaw は通常の最終配信を使用し、古いプレビューをクリーンアップします

複雑な返信（たとえばメディアペイロード）の場合、OpenClaw は通常の最終配信にフォールバックし、その後プレビューメッセージをクリーンアップします。

プレビューストリーミングはブロックストリーミングとは別です。Telegram でブロックストリーミングが明示的に有効になっている場合、OpenClaw は二重ストリーミングを避けるためにプレビューストリームをスキップします。

Telegram のみの推論ストリーム:

• /reasoning stream は生成中に推論をライブプレビューへ送信します
• 推論プレビューは最終配信後に削除されます。推論を表示したままにする必要がある場合は /reasoning on を使用します
• 最終回答は推論テキストなしで送信されます

送信テキストは 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 メニューに表示されていない場合でも、入力すれば引き続き動作できます

ネイティブコマンドが無効な場合、組み込みコマンドは削除されます。設定されていれば、カスタム/plugin コマンドは引き続き登録されることがあります。

よくあるセットアップ失敗:

• BOT_COMMANDS_TOO_MUCH を伴う setMyCommands failed は、トリミング後も 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 token を拒否したことを意味します。botToken、tokenFile、または TELEGRAM_BOT_TOKEN を現在の BotFather token で更新してください。OpenClaw はポーリング前に停止するため、これは Webhook クリーンアップ失敗としては報告されません。
• ネットワーク/fetch エラーを伴う setMyCommands failed は通常、api.telegram.org への送信 DNS/HTTPS がブロックされていることを意味します。

# デバイスペアリングコマンド（device-pair plugin）

device-pair plugin がインストールされている場合:

1. /pair がセットアップコードを生成します
2. iOS アプリにコードを貼り付けます
3. /pair pending が保留中のリクエストを一覧表示します（ロール/スコープを含む）
4. リクエストを承認します:
   • 明示的な承認には /pair approve <requestId>
   • 保留中のリクエストが 1 件だけの場合は /pair approve
   • 最新のものには /pair approve latest

セットアップコードには短命のブートストラップトークンが含まれます。組み込みのブートストラップ引き渡しは、プライマリノードトークンを scopes: [] のまま維持します。引き渡された operator token は operator.approvals、operator.read、operator.talk.secrets、operator.write に制限されたままです。ブートストラップのスコープチェックにはロールプレフィックスが付くため、その operator allowlist は operator リクエストだけを満たします。operator 以外のロールでは、それぞれのロールプレフィックス配下のスコープが引き続き必要です。

デバイスが変更された認証詳細（たとえばロール/スコープ/公開鍵）で再試行した場合、以前の保留中リクエストは置き換えられ、新しいリクエストは異なる 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_data: <value>

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）を公開します。

ゲーティング制御:

• channels.telegram.actions.sendMessage
• channels.telegram.actions.deleteMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker（デフォルト: 無効）

注記: edit と topic-create は現在デフォルトで有効であり、個別の channels.telegram.actions.* トグルはありません。 ランタイム送信はアクティブな config/secrets スナップショット（起動/リロード）を使用するため、アクションパスは送信ごとにアドホックな SecretRef 再解決を行いません。

リアクション削除のセマンティクス: /tools/reactions

Telegram は生成された出力内の明示的な返信スレッドタグをサポートします:

• [[reply_to_current]] はトリガー元メッセージに返信します
• [[reply_to:<id>]] は特定の Telegram メッセージ ID に返信します

channels.telegram.replyToMode は処理を制御します:

• off（デフォルト）
• first
• all

返信スレッドが有効で、元の Telegram テキストまたはキャプションが利用可能な場合、OpenClaw はネイティブ Telegram 引用抜粋を自動的に含めます。Telegram はネイティブ引用テキストを 1024 UTF-16 コードユニットに制限しているため、より長いメッセージは先頭から引用され、Telegram が引用を拒否した場合はプレーンな返信にフォールバックします。

注記: off は暗黙的な返信スレッドを無効にします。明示的な [[reply_to_*]] タグは引き続き尊重されます。

フォーラムスーパーグループ:

• トピックセッションキーは :topic:<threadId> を追加します
• 返信と入力中表示はトピックスレッドを対象にします
• トピック設定パス: channels.telegram.groups.<chatId>.topics.<threadId>

一般トピック（threadId=1）の特別扱い:

• メッセージ送信では message_thread_id を省略します（Telegram は sendMessage(...thread_id=1) を拒否します）
• 入力中アクションには引き続き message_thread_id を含めます

トピック継承: トピック項目は、上書きされない限りグループ設定を継承します（requireMention、allowFrom、skills、systemPrompt、enabled、groupPolicy）。 agentId はトピック専用であり、グループのデフォルトからは継承されません。

トピックごとのエージェントルーティング: 各トピックは、トピック設定で agentId を設定することで、別のエージェントにルーティングできます。これにより、各トピックに独自の隔離されたワークスペース、メモリ、セッションが与えられます。例:

{
  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:zu:telegram:group:-1001234567890:topic:3

永続 ACP トピックバインディング: フォーラムトピックは、トップレベルの型付き ACP バインディング（type: "acp"、match.channel: "telegram"、peer.kind: "group"、および -1001234567890:topic:42 のようなトピック修飾 ID を持つ bindings[]）を通じて ACP ハーネスセッションを固定できます。現在はグループ/スーパーグループ内のフォーラムトピックにスコープされています。ACP Agents を参照してください。

チャットからのスレッドバインド ACP spawn: /acp spawn <agent> --thread here|auto は現在のトピックを新しい ACP セッションにバインドします。後続のやり取りはそこへ直接ルーティングされます。OpenClaw はトピック内に spawn 確認を固定します。channels.telegram.threadBindings.spawnSessions が有効なままである必要があります（デフォルト: true）。

テンプレートコンテキストは MessageThreadId と IsForum を公開します。message_thread_id を持つ DMチャットは、デフォルトでフラットセッション上の DMルーティングと返信メタデータを維持します。threadReplies: "inbound"、threadReplies: "always"、requireTopic: true、または一致するトピック設定で構成されている場合にのみ、スレッド対応のセッションキーを使用します。アカウントのデフォルトにはトップレベルの channels.telegram.dm.threadReplies を、1つの DM には direct.<chatId>.threadReplies を使用します。

# 音声メッセージ

Telegram はボイスメモと音声ファイルを区別します。

• デフォルト: 音声ファイルの動作
• エージェントの返信内のタグ [[audio_as_voice]] でボイスメモ送信を強制
• 受信したボイスメモの文字起こしは、エージェントコンテキスト内で機械生成の信頼できないテキストとして囲まれます。メンション検出は引き続き生の文字起こしを使用するため、メンションで制御された音声メッセージは動作し続けます。

メッセージアクションの例:

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

# 動画メッセージ

Telegram は動画ファイルとビデオメモを区別します。

メッセージアクションの例:

{
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 のリアクションは message_reaction 更新として届きます（メッセージペイロードとは別です）。

有効な場合、OpenClaw は次のようなシステムイベントをキューに入れます。

• 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 はボットが送信したメッセージへのユーザーリアクションのみを意味します（送信済みメッセージキャッシュによるベストエフォート）。
• リアクションイベントも Telegram のアクセス制御（dmPolicy、allowFrom、groupPolicy、groupAllowFrom）に従います。許可されていない送信者は破棄されます。
• Telegram はリアクション更新でスレッド ID を提供しません。
  • 非フォーラムグループはグループチャットセッションにルーティングされます
  • フォーラムグループは、正確な発生元トピックではなく、グループの一般トピックセッション（:topic:1）にルーティングされます

ポーリング/Webhook の allowed_updates には message_reaction が自動的に含まれます。

ackReaction は、OpenClaw が受信メッセージを処理している間に確認用の絵文字を送信します。

解決順序:

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• エージェントのアイデンティティ絵文字フォールバック（agents.list[].identity.emoji、なければ "👀"）

注:

• Telegram は Unicode 絵文字（例: "👀"）を想定します。
• チャネルまたはアカウントのリアクションを無効化するには "" を使用します。

チャネル設定の書き込みはデフォルトで有効です（configWrites !== false）。

Telegram によってトリガーされる書き込みには次が含まれます。

• channels.telegram.groups を更新するためのグループ移行イベント（migrate_to_chat_id）
• /config set と /config unset（コマンドの有効化が必要）

無効化:

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

デフォルトはロングポーリングです。Webhook モードの場合は channels.telegram.webhookUrl と channels.telegram.webhookSecret を設定します。任意で webhookPath、webhookHost、webhookPort（デフォルトは /telegram-webhook、127.0.0.1、8787）を設定できます。

ロングポーリングモードでは、OpenClaw は更新が正常にディスパッチされた後にのみ再起動ウォーターマークを永続化します。ハンドラーが失敗した場合、その更新は同じプロセス内で再試行可能なままとなり、再起動時の重複排除のために完了済みとして書き込まれません。

ローカルリスナーは 127.0.0.1:8787 にバインドします。公開入口には、ローカルポートの前にリバースプロキシを置くか、意図的に webhookHost: "0.0.0.0" を設定します。

Webhook モードは、Telegram に 200 を返す前に、リクエストガード、Telegram シークレットトークン、JSON 本文を検証します。 その後 OpenClaw は、ロングポーリングで使用されるものと同じチャット単位/トピック単位のボットレーンを通じて更新を非同期に処理するため、遅いエージェントターンが Telegram の配信 ACK を保持しません。

• channels.telegram.textChunkLimit のデフォルトは 4000 です。
• channels.telegram.chunkMode="newline" は長さによる分割の前に段落境界（空行）を優先します。
• channels.telegram.mediaMaxMb（デフォルト 100）は、受信および送信の Telegram メディアサイズを制限します。
• channels.telegram.mediaGroupFlushMs（デフォルト 500）は、OpenClaw が Telegram アルバム/メディアグループを1つの受信メッセージとしてディスパッチする前にバッファする時間を制御します。アルバムの一部が遅れて届く場合は増やし、アルバム返信のレイテンシを下げるには減らします。
• channels.telegram.timeoutSeconds は Telegram API クライアントのタイムアウトを上書きします（未設定の場合は grammY のデフォルトが適用されます）。ボットクライアントは、構成値が 60 秒の送信テキスト/タイピングリクエストガードを下回る場合にクランプするため、OpenClaw のトランスポートガードとフォールバックが実行される前に grammY が見える返信配信を中止することはありません。ロングポーリングでは引き続き 45 秒の getUpdates リクエストガードを使用するため、アイドルポーリングが無期限に放棄されることはありません。
• channels.telegram.pollingStallThresholdMs のデフォルトは 120000 です。誤検知のポーリング停止再起動に限り、30000 から 600000 の間で調整してください。
• グループコンテキスト履歴は channels.telegram.historyLimit または messages.groupChat.historyLimit（デフォルト 50）を使用します。0 で無効化します。
• 返信/引用/転送の補足コンテキストは、現時点では受信したまま渡されます。
• Telegram の許可リストは主に、完全な補足コンテキストの編集境界ではなく、誰がエージェントをトリガーできるかを制御します。
• DM 履歴の制御:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• channels.telegram.retry 設定は、回復可能な送信 API エラーに対して Telegram 送信ヘルパー（CLI/ツール/アクション）に適用されます。受信の最終返信配信も Telegram の接続前失敗に対して境界付きの安全送信再試行を使用しますが、見えるメッセージが重複する可能性がある曖昧な送信後ネットワークエンベロープは再試行しません。

CLI とメッセージツールの送信ターゲットには、数値のチャット ID、ユーザー名、またはフォーラムトピックターゲットを使用できます。

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"

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}'
• 送信画像と GIF を、圧縮写真またはアニメーションメディアアップロードではなくドキュメントとして送信する --force-document

アクション制御:

• channels.telegram.actions.sendMessage=false は、ポーリングを含む送信 Telegram メッセージを無効化します
• channels.telegram.actions.poll=false は、通常の送信を有効にしたまま Telegram ポーリング作成を無効化します

Telegram は承認者 DM で exec 承認に対応し、必要に応じて発生元のチャットまたはトピックにプロンプトを投稿できます。承認者は数値の Telegram ユーザー ID である必要があります。

設定パス:

• channels.telegram.execApprovals.enabled（少なくとも1人の承認者を解決できる場合に自動有効化）
• channels.telegram.execApprovals.approvers（commands.ownerAllowFrom の数値オーナー ID にフォールバック）
• channels.telegram.execApprovals.target: dm（デフォルト） | channel | both
• agentFilter, sessionFilter

channels.telegram.allowFrom、groupAllowFrom、defaultTo は、誰がボットと会話できるか、および通常の返信をどこに送信するかを制御します。これらは誰かを exec 承認者にするものではありません。コマンドオーナーがまだ存在しない場合、最初に承認された DM ペアリングが commands.ownerAllowFrom をブートストラップするため、1人オーナー構成でも execApprovals.approvers の下で ID を重複させずに動作します。

チャネル配信ではコマンドテキストがチャットに表示されます。信頼済みのグループ/トピックでのみ channel または both を有効化してください。プロンプトがフォーラムトピックに届いた場合、OpenClaw は承認プロンプトとフォローアップのためにトピックを保持します。exec 承認はデフォルトで 30 分後に期限切れになります。

インライン承認ボタンでは、channels.telegram.capabilities.inlineButtons がターゲットサーフェス（dm、group、または all）を許可していることも必要です。plugin: が接頭辞の承認 ID は Plugin 承認を通じて解決されます。それ以外はまず exec 承認を通じて解決されます。

Exec 承認 を参照してください。

• requireMention=false の場合、Telegram のプライバシーモードは完全な可視性を許可している必要があります。
  • BotFather: /setprivacy -> Disable
  • その後、グループからボットを削除して再追加します
• openclaw channels status は、設定がメンションなしのグループメッセージを想定している場合に警告します。
• openclaw channels status --probe は明示的な数値グループ ID を確認できます。ワイルドカード "*" はメンバーシップ確認のプローブ対象にできません。
• クイックセッションテスト: /activation always。

• channels.telegram.groups が存在する場合、グループが一覧に含まれている必要があります（または "*" を含めます）
• グループ内のボットメンバーシップを確認します
• スキップ理由についてログを確認します: openclaw logs --follow

• 送信者 ID を承認します（ペアリングや数値 allowFrom）
• グループポリシーが open の場合でも、コマンド承認は引き続き適用されます
• BOT_COMMANDS_TOO_MUCH を伴う setMyCommands failed は、ネイティブメニューの項目が多すぎることを意味します。Plugin/Skills/カスタムコマンドを減らすか、ネイティブメニューを無効にしてください
• deleteMyCommands / setMyCommands の起動時呼び出しと sendChatAction の入力中呼び出しは制限され、リクエストタイムアウト時には Telegram のトランスポートフォールバック経由で 1 回再試行されます。永続的なネットワーク/フェッチエラーは通常、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 は成功した起動時 getMe プローブを grammY に再利用するため、ランナーは最初の getUpdates の前に 2 回目の getMe を必要としません。
• ポーリング起動中に deleteWebhook が一時的なネットワークエラーで失敗した場合、OpenClaw は別のポーリング前コントロールプレーン呼び出しを行わず、ロングポーリングへ進みます。まだアクティブな webhook は getUpdates の競合として表面化します。その後、OpenClaw は Telegram トランスポートを再構築し、webhook クリーンアップを再試行します。
• Telegram ソケットが短い固定周期でリサイクルされる場合は、低い channels.telegram.timeoutSeconds を確認してください。ボットクライアントは、外向きリクエストと getUpdates リクエストのガード値を下回る設定値をクランプしますが、古いリリースではこの値がそれらのガード値を下回ると、すべてのポーリングまたは返信が中断される可能性がありました。
• ログに 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 トランスポートについて、HTTP_PROXY、HTTPS_PROXY、ALL_PROXY とそれらの小文字バリアントを含むプロセス proxy env も尊重します。NO_PROXY / no_proxy は引き続き api.telegram.org をバイパスできます。
• サービス環境で OpenClaw 管理 proxy が OPENCLAW_PROXY_URL を通じて設定され、標準の proxy env が存在しない場合、Telegram も Bot API トランスポートにその URL を使用します。
• 直接の外向き通信/TLS が不安定な VPS ホストでは、Telegram API 呼び出しを channels.telegram.proxy 経由でルーティングします。

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

• 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 ベンチマーク範囲をすでに許可しています。

• 環境オーバーライド（一時的）:
  • 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