Telegram

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

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

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

• channels.telegram.streaming は off | partial | block | progress です（既定: partial）
• progress はツールの進行状況用に編集可能なステータス下書きを1つ保持し、完了時にそれを消去して、最終回答を通常のメッセージとして送信します
• streaming.preview.toolProgress は、ツール/進行状況の更新で同じ編集済みプレビューメッセージを再利用するかどうかを制御します（既定: プレビューストリーミングが有効な場合は true）
• streaming.preview.commandText は、それらのツール進行状況行内のコマンド/実行詳細を制御します: raw（既定、リリース済みの挙動を保持）または status（ツールラベルのみ）
• レガシーの channels.telegram.streamMode と boolean の 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 メッセージに分割される長い最終テキストでは、可能な場合は既存のプレビューを最初の最終チャンクとして再利用し、その後は残りのチャンクだけを送信します
• progress モードの最終結果では、ステータス下書きを消去し、その下書きを回答へ編集する代わりに通常の最終配信を使用します
• 完了済みテキストが確認される前に最終編集が失敗した場合、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 が拒否したことを意味します。現在の BotFather トークンで botToken、tokenFile、または TELEGRAM_BOT_TOKEN を更新してください。OpenClaw はポーリング前に停止するため、これは Webhook クリーンアップ失敗としては報告されません。
• setMyCommands failed とネットワーク/fetch エラーが表示される場合は、通常 api.telegram.org への送信 DNS/HTTPS がブロックされていることを意味します。

​

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

1. /pair がセットアップコードを生成します
2. iOS アプリにコードを貼り付けます
3. /pair pending が保留中のリクエストを一覧表示します（role/scopes を含む）
4. リクエストを承認します:
   • 明示的な承認には /pair approve <requestId>
   • 保留中のリクエストが1つだけの場合は /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
          }
        }
      }
    }
  }
}

​

音声メッセージ

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

{
  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
• エージェント ID 絵文字へのフォールバック（agents.list[].identity.emoji、なければ ”👀”）

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

• channels.telegram.groups を更新するグループ移行イベント（migrate_to_chat_id）
• /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）は、OpenClaw が Telegram のアルバム/メディアグループを 1 つの受信メッセージとしてディスパッチする前にバッファリングする時間を制御します。アルバムの各部分が遅れて届く場合は増やし、アルバム返信のレイテンシを減らすには減らします。
• channels.telegram.timeoutSeconds は Telegram API クライアントのタイムアウトを上書きします（未設定の場合は grammY のデフォルトが適用されます）。bot クライアントは、設定値が 60 秒の送信テキスト/タイピングリクエストガードを下回る場合にその値をクランプし、OpenClaw のトランスポートガードとフォールバックが実行できる前に grammY が可視の返信配信を中断しないようにします。ロングポーリングでは引き続き 45 秒の getUpdates リクエストガードを使用し、アイドル状態のポーリングが無期限に放棄されないようにします。
• channels.telegram.pollingStallThresholdMs のデフォルトは 120000 です。ポーリング停止の誤検知による再起動の場合にのみ、30000 から 600000 の間で調整してください。
• グループコンテキスト履歴は channels.telegram.historyLimit または messages.groupChat.historyLimit（デフォルト 50）を使用します。0 は無効にします。
• 返信/引用/転送の補足コンテキストは、Gateway が親メッセージを観測している場合、選択された 1 つの会話コンテキストウィンドウに正規化されます。観測済みメッセージキャッシュはセッションストアの横に永続化されます。Telegram は更新内に浅い reply_to_message を 1 つだけ含めるため、キャッシュより古いチェーンは Telegram の現在の更新ペイロードに制限されます。
• Telegram の許可リストは主に、誰がエージェントをトリガーできるかを制御するものであり、完全な補足コンテキストの墨消し境界ではありません。
• DM 履歴制御:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• channels.telegram.retry 設定は、回復可能な送信 API エラーに対する Telegram 送信ヘルパー（CLI/ツール/アクション）に適用されます。受信の最終返信配信でも、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
• bot がそのチャットで固定できる場合に固定配信をリクエストする --pin または --delivery '{"pin":true}'
• 送信画像、GIF、動画を、圧縮写真、アニメーションメディア、動画アップロードではなくドキュメントとして送信する --force-document

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

• channels.telegram.execApprovals.enabled（少なくとも 1 人の承認者を解決できる場合に自動有効化）
• 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、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 の間のプロキシ、DNS、IPv6、または TLS の外向き通信の問題を示します。
• Telegram は Bot API トランスポートについて、HTTP_PROXY、HTTPS_PROXY、ALL_PROXY とそれらの小文字バリアントを含むプロセスのプロキシ環境変数も尊重します。NO_PROXY / no_proxy は引き続き api.telegram.org をバイパスできます。
• サービス環境で OpenClaw 管理プロキシが OPENCLAW_PROXY_URL を通じて設定されており、標準のプロキシ環境変数が存在しない場合、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 または透過プロキシが、メディアダウンロード中に api.telegram.org を他のプライベート/内部/特殊用途アドレスへ書き換える場合、Telegram 専用バイパスにオプトインできます。

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• 同じオプトインは、アカウントごとに channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork でも利用できます。
• プロキシが 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