Telegram

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

• /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 バックアップ" },
        { command: "generate", description: "画像を作成" },
      ],
    },
  },
}

• トリムの再試行後に BOT_COMMANDS_TOO_MUCH を伴う setMyCommands failed が発生する場合、メニューがまだ上限を超えています。Plugin、Skills、カスタムコマンドを減らすか、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 のクリーンアップ失敗としては報告されません。
• ネットワークやフェッチのエラーを伴う 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,
}

​

位置情報と会場

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  location: {
    latitude: 48.858844,
    longitude: 2.294351,
    accuracy: 12,
    name: "エッフェル塔",
    address: "シャン・ド・マルス、パリ",
  },
}

​

ステッカー

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

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

{
  action: "sticker-search",
  channel: "telegram",
  query: "手を振る猫",
  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.entries.*.identity.emoji、なければ「👀」）

• channels.telegram.textChunkLimit のデフォルトは 4000 です。streaming.chunkMode="newline" は、長さで分割する前に段落境界（空行）を優先します。
• channels.telegram.mediaMaxMb（デフォルト 100）は、受信および送信メディアのサイズを制限します。
• グループコンテキスト履歴では channels.telegram.historyLimit または messages.groupChat.historyLimit（デフォルト 50）を使用します。0 で無効化します。
• 返信、引用、転送の補足コンテキストは、Gateway が親メッセージを観測済みの場合、選択された単一の会話コンテキストウィンドウに正規化されます。観測済みメッセージのキャッシュは OpenClaw SQLite Plugin 状態に保存され、openclaw doctor --fix が従来のサイドカーをインポートします。Telegram は更新ごとに浅い reply_to_message を 1 つだけ含めるため、キャッシュより古いチェーンはそのペイロードに制限されます。
• Telegram の許可リストは主に、エージェントをトリガーできるユーザーを制限するものであり、補足コンテキスト全体の秘匿化境界ではありません。
• DM 履歴: channels.telegram.dmHistoryLimit、channels.telegram.dms["<user_id>"].historyLimit。

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、Skills、カスタムコマンドを減らすか、ネイティブメニューを無効にしてください。
• 起動時の deleteMyCommands / setMyCommands 呼び出しと sendChatAction の入力中通知呼び出しには制限があり、リクエストがタイムアウトした場合は Telegram のトランスポートフォールバック経由で 1 回再試行されます。ネットワーク／fetch エラーが継続する場合、通常は 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／プロキシを使用する 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 のクリーンアップを再試行します。
• ログの Polling stall detected は、デフォルトではロングポーリングの稼働確認が 120 秒間完了しなかったため、OpenClaw がポーリングを再起動し、トランスポートを再構築したことを意味します。
• openclaw channels status --probe と openclaw doctor は、実行中のポーリングアカウントが起動猶予期間後も getUpdates を完了していない場合、実行中の Webhook アカウントが起動猶予期間後も setWebhook を完了していない場合、または最後に成功したポーリングトランスポートのアクティビティが古くなっている場合に警告します。
• 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 A
dig +short api.telegram.org AAAA