Telegram

Telegram ボットではデフォルトで Privacy Mode が有効になっており、受信できるグループメッセージが制限されます。

すべてのグループメッセージを受信するには、次のいずれかを行います。

• /setprivacy でプライバシーモードを無効にする
• ボットをグループ管理者にする

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

管理者ステータスは Telegram のグループ設定で制御します。管理者ボットはすべてのグループメッセージを受信するため、常時稼働するグループ動作に役立ちます。

• /setjoingroups — グループへの追加を許可または拒否
• /setprivacy — グループでの可視性の動作

チャットコマンドより UI を使用したい場合は、同じ設定を BotFather の Web アプリでも利用できます。

OpenClaw は、ダイレクトチャット、グループ、トピックで部分的な返信をリアルタイムにストリーミングします。まずプレビューメッセージを送信し、editMessageText を繰り返し実行して、その場で最終状態にします。

• channels.telegram.streaming は off | partial | block | progress です（デフォルト: partial）
• 短い初期回答のプレビューはデバウンスされ、実行がまだアクティブであれば、上限付きの遅延後に具体化されます
• progress はツール進捗用に編集可能なステータス下書きを 1 つ維持し、ツール進捗より先に回答処理が始まった場合は安定したステータスラベルを表示し、完了時に消去して、最終回答を通常のメッセージとして送信します
• streaming.preview.toolProgress は、ツール／進捗の更新で同じ編集済みプレビューメッセージを再利用するかどうかを制御します（プレビューストリーミングが有効な場合のデフォルト: true）
• streaming.preview.commandText は、それらの行に含めるコマンド／実行の詳細を制御します。raw（デフォルト）または status（ツールラベルのみ）です
• streaming.progress.commentary（デフォルト: false）を有効にすると、一時的な進捗下書きにアシスタントの解説／前置きテキストが含まれます
• 旧形式の channels.telegram.streamMode、真偽値の streaming、廃止されたネイティブ下書きプレビューキーは検出されます。移行するには openclaw doctor --fix を実行してください

ツール進捗行とは、ツールの実行中に表示される短いステータス更新です（コマンド実行、ファイル読み取り、計画の更新、パッチの要約、app-server モードでの Codex の前置き／解説）。Telegram ではデフォルトで有効です（v2026.4.22 以降のリリース済み動作と一致します）。

回答プレビューの編集を維持しつつ、ツール進捗行を非表示にするには、次のようにします。

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

ツール進捗を表示したまま、コマンド／実行テキストを非表示にするには、次のようにします。

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

progress モードでは、最終回答をそのメッセージに編集して組み込まずにツール進捗を表示します。コマンドテキストのポリシーは streaming.progress の下に配置します。

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

streaming.mode: "off" は、プレビュー編集を無効にし、一般的なツール／進捗メッセージを個別のステータスメッセージとして送信せず抑制します。承認プロンプト、メディア、エラーは引き続き通常の最終配信経路で送られます。streaming.preview.toolProgress: false は、回答プレビューの編集のみを維持します。

テキストのみの返信の場合、短いプレビューはその場で最終編集されます。複数のメッセージに分割される長い最終回答では、プレビューを最初のチャンクとして再利用し、残りの部分だけを送信します。progress モードの最終回答ではステータス下書きを消去し、通常の最終配信を使用します。完了が確認される前に最終編集が失敗した場合、OpenClaw は通常の最終配信にフォールバックし、古いプレビューをクリーンアップします。複雑な返信（メディアペイロード）の場合、OpenClaw は常に通常の最終配信にフォールバックし、プレビューをクリーンアップします。

プレビューストリーミングとブロックストリーミングは同時に使用できません。ブロックストリーミングが明示的に有効な場合、OpenClaw は二重ストリーミングを避けるためプレビューストリームをスキップします。

推論: /reasoning stream は生成中に推論をライブプレビューへストリーミングし、最終配信後に推論プレビューを削除します（表示したままにするには /reasoning on を使用します）。最終回答は推論テキストなしで送信されます。

送信テキストはデフォルトで標準の Telegram HTML メッセージを使用し、現在の各クライアントで読み取れます。太字、斜体、リンク、コード、スポイラー、引用に対応しますが、Bot API 10.1 のリッチ専用ブロック（ネイティブテーブル、詳細、リッチメディア、数式）は使用しません。

Bot API 10.1 のリッチメッセージを有効にするには、次のようにします。

{channels: {telegram: {  richMessages: true,},},}

有効にすると、このボット／アカウントでリッチメッセージが利用可能であることがエージェントに通知されます。Markdown テキストは OpenClaw の Markdown IR を介して Telegram のリッチ HTML としてレンダリングされます。明示的なリッチ HTML ペイロードでは、Bot API 10.1 がサポートするタグ（見出し、テーブル、詳細、リッチメディア、数式）が維持されます。メディアキャプションでは引き続き Telegram HTML キャプションが使用されます（リッチメッセージはキャプションを置き換えず、キャプションの上限は 1024 文字です）。

これにより、モデルのテキストが Telegram のリッチ Markdown 記号から分離されるため、$400-600K のような金額が数式として解析されません。長いリッチテキストは Telegram の制限に合わせて自動的に分割されます。20 列の上限を超えるテーブルはコードブロックにフォールバックします。

デフォルトはオフです。これはクライアント互換性のためであり、現在の一部の Desktop、Web、Android、およびサードパーティ製クライアントでは、受理されたリッチメッセージが未対応としてレンダリングされます。ボットで使用するすべてのクライアントがレンダリングできる場合を除き、オフのままにしてください。/status では、現在のセッションでリッチメッセージがオンかオフかを確認できます。

リンクプレビューはデフォルトで有効です。channels.telegram.linkPreview: false は、リッチテキストのエンティティ自動検出を無効にします。

Telegram のコマンドメニューは、起動時に setMyCommands で登録されます。commands.native: "auto" は Telegram のネイティブコマンドを有効にします。

カスタムコマンドのメニュー項目を追加するには、次のようにします。

{channels: {telegram: {  customCommands: [    { command: "backup", description: "Git バックアップ" },    { command: "generate", description: "画像を作成" },  ],},},}

ルール: 名前は正規化されます（先頭の / を削除し、小文字化）。有効なパターンは a-z、0-9、_、長さは 1-32 です。カスタムコマンドでネイティブコマンドを上書きすることはできません。競合／重複はスキップされ、ログに記録されます。

カスタムコマンドはメニュー項目にすぎず、動作を自動実装するものではありません。Plugin／skill コマンドは Telegram メニューに表示されていなくても、入力すれば引き続き動作できます。ネイティブコマンドが無効な場合、組み込みコマンドは削除されます。カスタム／Plugin コマンドは、設定されていれば引き続き登録される場合があります。

一般的なセットアップ失敗:

• トリム後の再試行でも BOT_COMMANDS_TOO_MUCH を伴って setMyCommands failed となる場合、メニューがまだ上限を超えています。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 が設定済みのボットトークンを拒否したことを意味します。botToken、tokenFile、または TELEGRAM_BOT_TOKEN（デフォルトアカウント）を現在の BotFather トークンで更新してください。OpenClaw はポーリング前に停止するため、これは Webhook のクリーンアップ失敗として報告されません。
• ネットワーク／fetch エラーを伴う setMyCommands failed は通常、api.telegram.org への送信 DNS／HTTPS がブロックされていることを意味します。

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

インストールされている場合:

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

デバイスが変更された認証情報（ロール、スコープ、公開鍵）で再試行すると、以前の保留中リクエストは新しい requestId を持つリクエストに置き換えられます。承認前に /pair pending を再実行してください。

詳細: ペアリング。

インラインキーボードのスコープを設定します。

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

アカウント単位の上書き:

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

スコープ: off、dm、group、all、allowlist（デフォルト）。旧形式の capabilities: ["inlineButtons"] は "all" にマッピングされます。

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

{action: "send",channel: "telegram",to: "123456789",message: "オプションを選択してください:",buttons: [[  { text: "はい", callback_data: "yes" },  { text: "いいえ", callback_data: "no" },],[{ text: "キャンセル", callback_data: "cancel" }],],}

Mini App ボタンの例:

{action: "send",channel: "telegram",to: "123456789",message: "アプリを開く:",presentation: {blocks: [  {    type: "buttons",    buttons: [{ label: "起動", web_app: { url: "https://example.com/app" } }],  },],},}

web_app ボタンは、ユーザーとボット間のプライベートチャットでのみ機能します。

登録済みの Plugin インタラクティブハンドラーによって処理されなかったコールバッククリックは、callback_data: <value> というテキストとしてエージェントに渡されます。

アクション:

• sendMessage（to、content、任意の mediaUrl、replyToMessageId、messageThreadId）
• react（chatId、messageId、emoji）
• deleteMessage（chatId、messageId）
• editMessage（chatId、messageId、content または caption、任意の presentation インラインボタン。ボタンのみの編集では返信マークアップを更新）
• createForumTopic（chatId、name、任意の iconColor、iconCustomEmojiId）

使いやすいエイリアス: send、react、delete、edit、sticker、sticker-search、topic-create。

制御設定: channels.telegram.actions.sendMessage、deleteMessage、reactions、sticker（デフォルト: 無効）。edit、createForumTopic、editForumTopic は専用の切り替え設定なしでデフォルトで有効です。 ランタイムからの送信では、起動時または再読み込み時の有効な設定とシークレットのスナップショットを使用するため、アクションパスは送信ごとに SecretRef の値を再解決しません。

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

生成される出力内で返信スレッドを明示するタグ:

• [[reply_to_current]] — トリガーとなったメッセージに返信
• [[reply_to:<id>]] — 特定のメッセージ ID に返信

channels.telegram.replyToMode: off（デフォルト）、first、all。

返信スレッドが有効で、元のテキストまたはキャプションを利用できる場合、OpenClaw はネイティブ引用の抜粋を自動的に追加します。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) を「thread not found」で拒否します）が、入力中アクションには引き続き message_thread_id を含めます（入力中インジケーターを表示するために必要であることが実証されています）。

トピックのエントリは、上書きされない限りグループ設定（requireMention、allowFrom、skills、systemPrompt、enabled、groupPolicy）を継承します。agentId はトピック専用であり、グループのデフォルトから継承されません。topics."*" は、そのグループ内のすべてのトピックに対するデフォルトを設定します。完全一致するトピック ID は引き続き "*" より優先されます。

トピックごとのエージェントルーティング: 各トピックは、トピック設定の agentId を介して異なるエージェントにルーティングでき、それぞれ独自のワークスペース、メモリ、セッションを持たせられます。

{  channels: {    telegram: {      groups: {        "-1001234567890": {          topics: {            "1": { agentId: "main" },      // 一般トピック -> main エージェント            "3": { agentId: "zu" },        // 開発トピック -> zu エージェント            "5": { agentId: "coder" }      // コードレビュー -> coder エージェント          }        }      }    }  }}

これにより、各トピックには独自のセッションキーが割り当てられます。例: agent:zu:telegram:group:-1001234567890:topic:3。

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

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

テンプレートコンテキストでは MessageThreadId と IsForum を利用できます。message_thread_id を持つ DM チャットでは返信メタデータを保持しますが、Telegram の getMe が has_topics_enabled: true を返す場合にのみ、スレッド対応のセッションキーを使用します。 廃止された dm.threadReplies および direct.*.threadReplies の上書き設定は削除されました。BotFather のスレッドモードが唯一の信頼できる情報源です。古い設定キーを削除するには openclaw doctor --fix を実行してください。

音声メッセージ

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

位置情報と会場

1 つの独立した location オブジェクトとともに、既存の send アクションを使用します。座標を指定するとネイティブのピンが送信され、name と address の両方を追加するとネイティブの会場カードが送信されます。位置情報の送信をメッセージテキストやメディアと組み合わせることはできません。

{action: "send",channel: "telegram",to: "123456789",location: {latitude: 48.858844,longitude: 2.294351,accuracy: 12,name: "Eiffel Tower",address: "Champ de Mars, Paris",},}

ステッカー

受信時: 静的 WEBP はダウンロードされて処理されます（プレースホルダー <media:sticker>）。アニメーション TGS と動画 WEBM はスキップされます。

ステッカーのコンテキストフィールド: Sticker.emoji、Sticker.setName、Sticker.fileId、Sticker.fileUniqueId、Sticker.cachedDescription。説明は、ビジョン呼び出しの繰り返しを減らすため、OpenClaw SQLite Plugin状態にキャッシュされます。

ステッカーアクションを有効化:

{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が受信メッセージを処理している間に確認用の絵文字を送信します。messages.ackReactionScopeは、それを送信するタイミングを決定します。

絵文字の解決順序:

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

TelegramではUnicode絵文字（例:「👀」）が必要です。チャンネルまたはアカウントでリアクションを無効にするには""を使用します。

スコープ（messages.ackReactionScope、デフォルトは"group-mentions"。現在、TelegramアカウントまたはTelegramチャンネルによるオーバーライドはありません）:

all（DM + グループ。アンビエントルームイベントを含む）、direct（DMのみ）、group-all（アンビエントルームイベントを除くすべてのグループメッセージ。DMは対象外）、group-mentions（ボットがメンションされたグループ。DMは対象外 — デフォルト）、off / none（無効）。

チャンネル設定の書き込みはデフォルトで有効です（configWrites !== false）。Telegramによってトリガーされる書き込みには、グループ移行イベント（migrate_to_chat_id、channels.telegram.groupsを更新）と、/config set / /config unset（コマンドの有効化が必要）が含まれます。

無効化:

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

デフォルトはロングポーリングです。Webhookモードでは、channels.telegram.webhookUrlとchannels.telegram.webhookSecretを設定します。オプションとして、webhookPath（デフォルトは/telegram-webhook）、webhookHost（デフォルトは127.0.0.1）、webhookPort（デフォルトは8787）、webhookCertPath（直接IPまたはドメインなしのセットアップ用の自己署名証明書PEM）を設定できます。

ロングポーリングモードでは、OpenClawは更新のディスパッチに成功した後にのみ再起動ウォーターマークを永続化します。ハンドラーが失敗した場合、その更新を完了済みとしてマークせず、同じプロセス内で再試行可能な状態に保ちます。

ローカルリスナーは、デフォルトで127.0.0.1:8787にバインドします。公開イングレスには、ローカルポートの前段にリバースプロキシを配置するか、意図的にwebhookHost: "0.0.0.0"を設定します。

Webhookモードでは、リクエストガード、Telegramのシークレットトークン、JSON本文を検証し、空の200を返す前に更新を永続イングレスキューへコミットします。永続的な受け入れに成功した場合はx-openclaw-delivery-accepted: durableが含まれます。ヘルス、ルーティング、認証、検証、ストレージエラーのレスポンスでは、このヘッダーは省略されます。リバースプロキシやホストコントローラーは、レスポンスのタイミングから受け入れを推測することなく、OpenClawによる受け入れと一般的な空の200を区別するために、このヘッダーを必須にできます。

その後、OpenClawはロングポーリングと同じチャット単位/トピック単位のボットレーンを通じて更新を非同期に処理するため、エージェントの処理に時間がかかってもTelegramの配信ACKを保留しません。

• channels.telegram.textChunkLimit のデフォルトは 4000。streaming.chunkMode="newline" は、長さで分割する前に段落境界（空行）を優先します。
• channels.telegram.mediaMaxMb（デフォルト 100）は、受信および送信メディアのサイズを制限します。
• channels.telegram.mediaGroupFlushMs（デフォルト 500、範囲 10-60000）は、OpenClaw がアルバム／メディアグループを 1 件の受信メッセージとしてディスパッチするまでにバッファリングする時間を制御します。アルバムの一部が遅れて届く場合は増やし、アルバムへの返信遅延を減らす場合は減らしてください。
• channels.telegram.timeoutSeconds は API クライアントのタイムアウトを上書きします（未設定の場合は grammY のデフォルトが適用されます）。Bot クライアントは、設定値が 60 秒の送信テキスト／入力中リクエストガードを下回る場合、そのガード未満にならないよう制限します。これにより、OpenClaw のトランスポートガードとフォールバックが実行される前に、grammY がユーザーに表示される返信の配信を中止することを防ぎます。ロングポーリングでは引き続き 45 秒の getUpdates リクエストガードを使用し、アイドル状態のポーリングが無期限に放棄されないようにします。
• channels.telegram.pollingStallThresholdMs のデフォルトは 120000 です。ポーリング停止の誤検知による再起動に対してのみ、30000 から 600000 の範囲で調整してください。
• グループコンテキスト履歴では channels.telegram.historyLimit または messages.groupChat.historyLimit（デフォルト 50）を使用します。0 で無効になります。
• Gateway が親メッセージを観測済みの場合、返信／引用／転送の補足コンテキストは、選択された 1 つの会話コンテキストウィンドウに正規化されます。観測済みメッセージのキャッシュは OpenClaw SQLite Plugin 状態に保存され、openclaw doctor --fix が従来のサイドカーファイルをインポートします。Telegram は更新ごとに浅い reply_to_message を 1 つしか含めないため、キャッシュより古いチェーンはそのペイロードの範囲に制限されます。
• Telegram の許可リストは、主に誰がエージェントをトリガーできるかを制限するものであり、補足コンテキスト全体の秘匿化境界ではありません。
• DM 履歴：channels.telegram.dmHistoryLimit、channels.telegram.dms["<user_id>"].historyLimit。
• channels.telegram.retry は、回復可能な送信 API エラーに対する Telegram 送信ヘルパー（CLI／ツール／アクション）に適用されます。受信メッセージへの最終返信の配信では、接続前の失敗に対して回数制限付きの安全な送信再試行を使用しますが、表示されるメッセージが重複する可能性のある、送信後の曖昧なネットワークエンベロープは再試行しません。

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

openclaw message send --channel telegram --target 123456789 --message "こんにちは"openclaw message send --channel telegram --target @name --message "こんにちは"openclaw message send --channel telegram --target -1001234567890:topic:42 --message "トピックへのこんにちは"

投票では openclaw message poll を使用し、フォーラムトピックにも対応しています。

openclaw message poll --channel telegram --target 123456789 \--poll-question "リリースしますか？" --poll-option "はい" --poll-option "いいえ"openclaw message poll --channel telegram --target -1001234567890:topic:42 \--poll-question "時間を選択" --poll-option "午前10時" --poll-option "午後2時" \--poll-duration-seconds 300 --poll-public

Telegram 専用の投票フラグ：--poll-duration-seconds（5-600）、--poll-anonymous、--poll-public、--thread-id（または :topic: ターゲット）。--poll-option は 2-12 回繰り返します（Telegram の選択肢上限）。

Telegram 送信では、インラインキーボード用の buttons ブロックを含む --presentation（channels.telegram.capabilities.inlineButtons で許可されている場合）、Bot がそのチャットでピン留めできる場合にピン留め配信を要求する --pin または --delivery '{"pin":true}'、および送信画像、GIF、動画を圧縮画像／アニメーション／動画としてではなくドキュメントとして送信する --force-document もサポートしています。

アクションの制限：channels.telegram.actions.sendMessage=false は投票を含むすべての送信メッセージを無効にします。channels.telegram.actions.poll=false は通常の送信を有効のままにして、投票の作成を無効にします。

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

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

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

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

インライン承認ボタンを使用するには、channels.telegram.capabilities.inlineButtons で対象サーフェス（dm、group、または all）が許可されている必要もあります。plugin: で始まる承認 ID は Plugin 承認によって解決され、それ以外は最初に実行承認によって解決されます。

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

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

• channels.telegram.groups が存在する場合、グループを一覧に含める必要があります（または "*" を含めます）。
• Bot がグループのメンバーであることを確認してください。
• スキップ理由について openclaw logs --follow を確認してください。

• 送信者のアイデンティティを許可してください（ペアリングおよび／または数値の allowFrom）。グループポリシーが open の場合でも、コマンドの認可は引き続き適用されます。
• BOT_COMMANDS_TOO_MUCH を伴う setMyCommands failed は、ネイティブメニューの項目が多すぎることを意味します。Plugin／skill／カスタムコマンドを減らすか、ネイティブメニューを無効にしてください。
• 起動時の deleteMyCommands／setMyCommands 呼び出し、および sendChatAction の入力中呼び出しには時間制限があり、リクエストタイムアウト時に Telegram のトランスポートフォールバックを通じて 1 回再試行されます。ネットワーク／fetch エラーが継続する場合、通常は api.telegram.org への DNS／HTTPS が到達不能です。

• getMe returned 401 は、設定された Bot トークンに対する Telegram の認証失敗です。BotFather でトークンを再コピーまたは再生成してから、channels.telegram.botToken、tokenFile、accounts.<id>.botToken、または TELEGRAM_BOT_TOKEN（デフォルトアカウント）を更新してください。
• 起動時の deleteWebhook 401 Unauthorized も認証失敗です。これを「Webhook が存在しない」として扱っても、同じ不正なトークンによる失敗が後続の API 呼び出しまで延期されるだけです。

• カスタム fetch／プロキシを使用する Node 22+ では、AbortSignal の型が一致しない場合、即時中止動作が発生する可能性があります。
• 一部のホストでは api.telegram.org が最初に IPv6 に解決されます。IPv6 の外向き通信に問題があると、断続的な API エラーが発生します。
• TypeError: fetch failed または Network request for 'getUpdates' failed! を含むログは、回復可能なネットワークエラーとして再試行されます。
• ポーリング起動時、OpenClaw は成功した起動時の getMe プローブを grammY に再利用するため、ランナーは最初の getUpdates の前に 2 回目の getMe を実行する必要がありません。
• ポーリング起動時に一時的なネットワークエラーで deleteWebhook が失敗した場合、OpenClaw はポーリング前に別のコントロールプレーン呼び出しを行わず、ロングポーリングへ進みます。Webhook がまだ有効な場合は getUpdates の競合として表面化し、OpenClaw はトランスポートを再構築して Webhook のクリーンアップを再試行します。
• Telegram ソケットが短い一定間隔で再作成される場合は、channels.telegram.timeoutSeconds が小さすぎないか確認してください。Bot クライアントは、送信および getUpdates のリクエストガードを下回る設定値をそのガード未満にならないよう制限しますが、古いリリースではこの値をガード未満に設定すると、すべてのポーリングまたは返信が中止される可能性がありました。
• ログの Polling stall detected は、完了したロングポーリングの生存確認がデフォルトで 120 秒間ないため、OpenClaw がポーリングを再起動してトランスポートを再構築したことを意味します。
• openclaw channels status --probe と openclaw doctor は、実行中のポーリングアカウントが起動猶予期間後も getUpdates を完了していない場合、実行中の Webhook アカウントが起動猶予期間後も setWebhook を完了していない場合、または最後に成功したポーリングトランスポートのアクティビティが古い場合に警告します。
• 長時間実行される getUpdates 呼び出しが正常であるにもかかわらず、ホストでポーリング停止の誤検知による再起動が報告される場合にのみ、channels.telegram.pollingStallThresholdMs を増やしてください。停止が継続する場合、通常は api.telegram.org へのプロキシ、DNS、IPv6、または TLS の外向き通信に問題があります。
• Telegram は Bot API トランスポートでプロセスのプロキシ環境変数を使用します：HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、およびそれぞれの小文字形式。NO_PROXY／no_proxy によって api.telegram.org が引き続きプロキシを迂回する場合があります。
• サービス環境で OPENCLAW_PROXY_URL が設定され、標準のプロキシ環境変数が存在しない場合、Telegram はその URL を Bot API トランスポートにも使用します。
• 直接の外向き通信／TLS が不安定な VPS ホストでは、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

• RFC 2544 ベンチマーク範囲の応答（198.18.0.0/15）は、Telegram のメディアダウンロードではデフォルトですでに許可されています。信頼できる fake-IP または透過プロキシが、メディアダウンロード中に api.telegram.org を別のプライベート／内部／特殊用途アドレスへ書き換える場合は、Telegram 専用のバイパスを明示的に有効化します。

channels:telegram:network:  dangerouslyAllowPrivateNetwork: true

• 同じ明示的な有効化は、アカウントごとに channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork でも設定できます。
• プロキシが Telegram のメディアホストを 198.18.x.x に解決する場合は、まず危険なフラグをオフのままにしてください。この範囲はデフォルトですでに許可されています。

• 一時的な環境変数による上書き：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 Adig +short api.telegram.org AAAA