Telegram

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

• /setjoingroups — グループ追加を許可/拒否する
• /setprivacy — グループ可視性の動作

• 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 を実行してください

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

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

• トリム再試行後に setMyCommands failed と BOT_COMMANDS_TOO_MUCH が出る場合、メニューがまだあふれています。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 が設定済みボットトークンを拒否したことを意味します。現在の 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（保留中リクエストが 1 件のみ）、または /pair approve latest

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

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

​

音声メッセージ

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

​

ステッカー

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

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

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

• channels.telegram.reactionNotifications: off | own | all (デフォルト: own)
• channels.telegram.reactionLevel: off | ack | minimal | extensive (デフォルト: minimal)

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

• channels.telegram.textChunkLimit のデフォルトは 4000 です。chunkMode="newline" は長さ分割の前に段落境界 (空行) を優先します。
• channels.telegram.mediaMaxMb (デフォルト 100) は受信および送信メディアサイズを制限します。
• channels.telegram.mediaGroupFlushMs (デフォルト 500、範囲 10-60000) は、アルバム/メディアグループを OpenClaw が 1 つの受信メッセージとしてディスパッチする前にバッファリングする時間を制御します。アルバムの一部が遅れて到着する場合は増やし、アルバム返信レイテンシを減らす場合は減らしてください。
• channels.telegram.timeoutSeconds は API クライアントのタイムアウトを上書きします (未設定の場合は grammY のデフォルトが適用されます)。ボットクライアントは、OpenClaw のトランスポートガードとフォールバックが実行できる前に grammY が表示される返信配信を中止しないように、設定値を 60 秒の送信テキスト/入力中リクエストガード未満に制限します。ロングポーリングでは引き続き 45 秒の getUpdates リクエストガードを使用するため、アイドル状態のポーリングが無期限に放棄されることはありません。
• channels.telegram.pollingStallThresholdMs のデフォルトは 120000 です。誤検知のポーリング停止再起動の場合にのみ、30000 から 600000 の間で調整してください。
• グループコンテキスト履歴は channels.telegram.historyLimit または messages.groupChat.historyLimit (デフォルト 50) を使用します。0 は無効化します。
• 返信/引用/転送の補足コンテキストは、Gateway が親メッセージを観測している場合、選択された 1 つの会話コンテキストウィンドウへ正規化されます。観測済みメッセージキャッシュは OpenClaw SQLite プラグイン状態に保存され、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/ツール/アクション) に適用されます。受信の最終返信配信では、接続前の失敗に対して境界付きのセーフ送信再試行を使用しますが、表示メッセージが重複する可能性のある送信後の曖昧なネットワークエンベロープは再試行しません。

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

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

• 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/skill/カスタムコマンドを減らすか、ネイティブメニューを無効にしてください。
• 起動時の deleteMyCommands / setMyCommands 呼び出しと、sendChatAction の入力中表示呼び出しは、リクエストタイムアウト時に制限付きで Telegram のトランスポートフォールバックを通じて 1 回再試行されます。永続的なネットワーク/フェッチエラーは通常、api.telegram.org への DNS/HTTPS が到達不能であることを意味します。

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

• カスタム fetch/proxy を使う 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 は別のポーリング前コントロールプレーン呼び出しを行わず、long polling に進みます。まだ有効な Webhook がある場合は getUpdates の競合として表面化します。OpenClaw はトランスポートを再構築し、Webhook クリーンアップを再試行します。
• Telegram ソケットが短い固定周期で再利用される場合は、低い channels.telegram.timeoutSeconds を確認してください。ボットクライアントは送信リクエストおよび getUpdates リクエストのガードを下回る設定値をクランプしますが、古いリリースではこの値がそれらのガード未満に設定されると、すべてのポーリングまたは返信が中断されることがありました。
• ログの Polling stall detected は、デフォルトで 120 秒間、完了した long-poll ライブネスがない場合に、OpenClaw がポーリングを再起動し、トランスポートを再構築することを意味します。
• 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 が設定され、標準 proxy 環境変数が存在しない場合、Telegram もその URL を Bot API トランスポートに使用します。
• 直接の送信経路/TLS が不安定な VPS ホストでは、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

• RFC 2544 ベンチマーク範囲の応答（198.18.0.0/15）は、Telegram メディアダウンロードでデフォルトですでに許可されています。信頼できる fake-IP または透過 proxy が、メディアダウンロード中に api.telegram.org を他の private/internal/special-use アドレスへ書き換える場合は、Telegram 専用バイパスにオプトインしてください。

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• 同じオプトインは、channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork でアカウント単位でも利用できます。
• proxy が Telegram メディアホストを 198.18.x.x に解決する場合は、まず dangerous フラグをオフのままにしてください。この範囲はデフォルトですでに許可されています。

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