Telegram (Bot API)

ステータス：grammYを介したボットDM + グループで本番環境対応。デフォルトはロングポーリング。Webhookはオプション。

クイックセットアップ（初心者向け）

  1. @BotFatherでボットを作成し、トークンをコピーします。
  2. トークンを設定します：
    • 環境変数：TELEGRAM_BOT_TOKEN=...
    • または設定ファイル：channels.telegram.botToken: "..."
    • 両方設定された場合、設定ファイルが優先されます（環境変数フォールバックはデフォルトアカウントのみ）。
  3. ゲートウェイを起動します。
  4. DMアクセスはデフォルトでペアリング。初回コンタクト時にペアリングコードを承認してください。

最小限の設定：

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing"
    }
  }
}

これは何か

  • ゲートウェイが所有するTelegram Bot APIチャネル。
  • 決定論的ルーティング：返信はTelegramに戻る。モデルはチャネルを選択しません。
  • DMはエージェントのメインセッションを共有し、グループは分離されます（agent:<agentId>:telegram:group:<chatId>）。

セットアップ（高速パス）

1) ボットトークンの作成（BotFather）

  1. Telegramを開き、@BotFatherとチャットします。
  2. /newbotを実行し、プロンプトに従います（名前 + botで終わるユーザー名）。
  3. トークンをコピーして安全に保管します。

オプションのBotFather設定：

  • /setjoingroups — ボットのグループ追加の許可/拒否。
  • /setprivacy — ボットがすべてのグループメッセージを見るかどうかを制御。

2) トークンの設定（環境変数または設定ファイル）

例：

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } }
    }
  }
}

環境変数オプション：TELEGRAM_BOT_TOKEN=...（デフォルトアカウントで動作）。 設定ファイルと環境変数の両方が設定されている場合、設定ファイルが優先されます。

マルチアカウントサポート：アカウントごとのトークンとオプションのnameを持つchannels.telegram.accountsを使用します。共有パターンについては、gateway/configurationを参照してください。

  1. ゲートウェイを起動します。トークンが解決されると（設定ファイル優先、環境変数フォールバック）、Telegramが起動します。
  2. DMアクセスはデフォルトでペアリング。ボットに初めて連絡したときにコードを承認します。
  3. グループの場合：ボットを追加し、プライバシー/管理者の動作を決定し（下記）、channels.telegram.groupsを設定してメンション制御 + 許可リストを制御します。

トークン + プライバシー + 権限（Telegram側）

トークンの作成（BotFather）

  • /newbotでボットが作成され、トークンが返されます（秘密にしてください）。
  • トークンが漏洩した場合、@BotFatherで取り消し/再生成し、設定を更新します。

グループメッセージの可視性（プライバシーモード）

Telegramボットはデフォルトでプライバシーモードになっており、受信するグループメッセージが制限されます。 ボットがすべてのグループメッセージを見る必要がある場合、2つのオプションがあります：

  • /setprivacyでプライバシーモードを無効にする または
  • ボットをグループの管理者として追加する（管理者ボットはすべてのメッセージを受信します）。

注意： プライバシーモードを切り替えると、Telegramは変更を有効にするために各グループからボットを削除して再追加する必要があります。

グループ権限（管理者権限）

管理者ステータスはグループ内（Telegram UI）で設定されます。管理者ボットは常にすべてのグループメッセージを受信するため、完全な可視性が必要な場合は管理者を使用してください。

動作方法（ビヘイビア）

  • インバウンドメッセージは、返信コンテキストとメディアプレースホルダーを含む共有チャネルエンベロープに正規化されます。
  • グループ返信はデフォルトでメンションが必要です（ネイティブ@メンションまたはagents.list[].groupChat.mentionPatterns / messages.groupChat.mentionPatterns）。
  • マルチエージェント上書き：agents.list[].groupChat.mentionPatternsでエージェントごとのパターンを設定します。
  • 返信は常に同じTelegramチャットにルーティングされます。
  • ロングポーリングはgrammYランナーを使用し、チャットごとのシーケンシングを行います。全体の同時実行数はagents.defaults.maxConcurrentで制限されます。
  • Telegram Bot APIは既読通知をサポートしていません。sendReadReceiptsオプションはありません。

フォーマット（Telegram HTML）

  • アウトバウンドTelegramテキストはparse_mode: "HTML"を使用します（Telegramがサポートするタグのサブセット）。
  • Markdownのような入力はTelegram対応HTMLにレンダリングされます（太字/斜体/取り消し線/コード/リンク）。ブロック要素は改行/箇条書きを含むテキストに平坦化されます。
  • モデルからの生のHTMLはTelegramパースエラーを避けるためにエスケープされます。
  • TelegramがHTMLペイロードを拒否した場合、OpenClawは同じメッセージをプレーンテキストで再試行します。

コマンド（ネイティブ + カスタム）

OpenClawは起動時にネイティブコマンド（/status、/reset、/modelなど）をTelegramのボットメニューに登録します。 設定を介してカスタムコマンドをメニューに追加できます：

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

トラブルシューティング

  • ログにsetMyCommands failedが表示される場合、通常はapi.telegram.orgへのアウトバウンドHTTPS/DNSがブロックされています。
  • sendMessageまたはsendChatActionの失敗が表示される場合、IPv6ルーティングとDNSを確認してください。

詳細なヘルプ：チャネルトラブルシューティング。

注意：

  • カスタムコマンドはメニューエントリのみです。他の場所で処理しない限り、OpenClawは実装しません。
  • コマンド名は正規化されます（先頭の/を削除、小文字化）、a-z、0-9、_と一致する必要があります（1〜32文字）。
  • カスタムコマンドはネイティブコマンドを上書きできません。競合は無視され、ログに記録されます。
  • commands.nativeが無効の場合、カスタムコマンドのみが登録されます（なければクリアされます）。

制限

  • アウトバウンドテキストはchannels.telegram.textChunkLimit（デフォルト4000）にチャンク化されます。
  • オプションの改行チャンク化：channels.telegram.chunkMode="newline"を設定すると、長さチャンク化の前に空白行（段落境界）で分割します。
  • メディアのダウンロード/アップロードはchannels.telegram.mediaMaxMb（デフォルト5）で制限されます。
  • Telegram Bot APIリクエストはchannels.telegram.timeoutSeconds（grammY経由でデフォルト500）後にタイムアウトします。長いハングを避けるために低く設定します。
  • グループ履歴コンテキストはchannels.telegram.historyLimit（またはchannels.telegram.accounts.*.historyLimit）を使用し、messages.groupChat.historyLimitにフォールバックします。無効にするには0を設定します（デフォルト50）。
  • DM履歴はchannels.telegram.dmHistoryLimit（ユーザーターン）で制限できます。ユーザーごとの上書き：channels.telegram.dms["<user_id>"].historyLimit。

グループアクティベーションモード

デフォルトでは、ボットはグループ内のメンション（@botnameまたはagents.list[].groupChat.mentionPatternsのパターン）にのみ応答します。この動作を変更するには：

設定経由（推奨）

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": { requireMention: false }  // このグループでは常に応答
      }
    }
  }
}

重要： channels.telegram.groupsを設定すると許可リストが作成されます - リストされたグループ（または"*"）のみが受け入れられます。 フォーラムトピックは、channels.telegram.groups.<groupId>.topics.<topicId>でトピックごとの上書きを追加しない限り、親グループの設定（allowFrom、requireMention、skills、prompts）を継承します。

常に応答するすべてのグループを許可するには：

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: false }  // すべてのグループで常に応答
      }
    }
  }
}

すべてのグループでメンションのみを保持するには（デフォルトの動作）：

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: true }  // またはgroupsを完全に省略
      }
    }
  }
}

コマンド経由（セッションレベル）

グループで送信：

  • /activation always - すべてのメッセージに応答
  • /activation mention - メンションが必要（デフォルト）

注意： コマンドはセッション状態のみを更新します。再起動後も永続的な動作を得るには、設定を使用してください。

グループチャットIDの取得

グループからの任意のメッセージを@userinfobotまたは@getidsbotに転送して、チャットID（-1001234567890のような負の数）を確認します。

ヒント： 自分のユーザーIDを取得するには、ボットにDMすると、ユーザーID（ペアリングメッセージ）が返されます。またはコマンドが有効になったら/whoamiを使用します。

プライバシー注意： @userinfobotはサードパーティのボットです。好みに応じて、ボットをグループに追加し、メッセージを送信し、openclaw logs --followを使用してchat.idを読むか、Bot APIのgetUpdatesを使用してください。

設定の書き込み

デフォルトでは、Telegramはチャネルイベントまたは/config set|unsetによってトリガーされる設定更新を書き込むことが許可されています。

これは次の場合に発生します：

  • グループがスーパーグループにアップグレードされ、Telegramがmigrate_to_chat_idを発行する（チャットIDが変更される）。OpenClawはchannels.telegram.groupsを自動的に移行できます。
  • Telegramチャットで/config setまたは/config unsetを実行する（commands.config: trueが必要）。

無効にするには：

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

トピック（フォーラムスーパーグループ）

Telegramフォーラムトピックはメッセージごとにmessage_thread_idを含みます。OpenClawは：

  • Telegramグループセッションキーに:topic:<threadId>を追加するため、各トピックが分離されます。
  • タイピングインジケーターを送信し、message_thread_idで返信するため、応答はトピック内に留まります。
  • 一般トピック（スレッドID 1）は特別です：メッセージ送信はmessage_thread_idを省略します（Telegramは拒否します）が、タイピングインジケーターには引き続き含まれます。
  • ルーティング/テンプレート化のためのテンプレートコンテキストでMessageThreadId + IsForumを公開します。
  • トピック固有の設定はchannels.telegram.groups.<chatId>.topics.<threadId>で利用可能です（skills、allowlists、auto-reply、system prompts、disable）。
  • トピック設定は、トピックごとに上書きされない限り、グループ設定（requireMention、allowlists、skills、prompts、enabled）を継承します。

プライベートチャットは、一部のエッジケースでmessage_thread_idを含むことがあります。OpenClawはDMセッションキーを変更しませんが、存在する場合は返信/ドラフトストリーミングにスレッドIDを使用します。

インラインボタン

Telegramはコールバックボタンを持つインラインキーボードをサポートします。

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

アカウントごとの設定の場合：

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

スコープ：

  • off — インラインボタン無効
  • dm — DMのみ（グループターゲットはブロック）
  • group — グループのみ（DMターゲットはブロック）
  • all — DM + グループ
  • allowlist — DM + グループ、ただしallowFrom/groupAllowFromで許可された送信者のみ（制御コマンドと同じルール）

デフォルト：allowlist。 レガシー：capabilities: ["inlineButtons"] = inlineButtons: "all"。

ボタンの送信

buttonsパラメーターを持つメッセージツールを使用します：

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

ユーザーがボタンをクリックすると、コールバックデータが次の形式でエージェントにメッセージとして送り返されます： callback_data: value

設定オプション

Telegram機能は2つのレベルで設定できます（上記はオブジェクト形式。レガシー文字列配列もサポート）：

  • channels.telegram.capabilities：上書きされない限り、すべてのTelegramアカウントに適用されるグローバルデフォルト機能設定。
  • channels.telegram.accounts.<account>.capabilities：特定のアカウントのグローバルデフォルトを上書きするアカウントごとの機能。

すべてのTelegramボット/アカウントが同じように動作する場合は、グローバル設定を使用します。異なるボットが異なる動作を必要とする場合（例えば、1つのアカウントはDMのみを処理し、別のアカウントはグループで許可される）は、アカウントごとの設定を使用します。

アクセス制御（DM + グループ）

DMアクセス

  • デフォルト：channels.telegram.dmPolicy = "pairing"。不明な送信者はペアリングコードを受信し、承認されるまでメッセージは無視されます（コードは1時間後に期限切れ）。
  • 承認方法：
    • openclaw pairing list telegram
    • openclaw pairing approve telegram <CODE>
  • ペアリングはTelegram DMに使用されるデフォルトのトークン交換です。詳細：ペアリング
  • channels.telegram.allowFromは数値ユーザーID（推奨）または@usernameエントリを受け入れます。これはボットのユーザー名ではありません。人間の送信者のIDを使用してください。ウィザードは@usernameを受け入れ、可能な場合は数値IDに解決します。

TelegramユーザーIDの検索

より安全（サードパーティボットなし）：

  1. ゲートウェイを起動し、ボットにDMします。
  2. openclaw logs --followを実行し、from.idを探します。

代替（公式Bot API）：

  1. ボットにDMします。
  2. ボットトークンで更新を取得し、message.from.idを読みます： 
    curl "https://api.telegram.org/bot<bot_token>/getUpdates"

サードパーティ（プライバシーは低い）：

  • @userinfobotまたは@getidsbotにDMし、返されたユーザーIDを使用します。

グループアクセス

2つの独立した制御：

1. どのグループが許可されるか（channels.telegram.groups経由のグループ許可リスト）：

  • groups設定なし = すべてのグループが許可
  • groups設定あり = リストされたグループまたは"*"のみが許可
  • 例："groups": { "-1001234567890": {}, "*": {} }はすべてのグループを許可

2. どの送信者が許可されるか（channels.telegram.groupPolicy経由の送信者フィルタリング）：

  • "open" = 許可されたグループのすべての送信者がメッセージ可能
  • "allowlist" = channels.telegram.groupAllowFromの送信者のみがメッセージ可能
  • "disabled" = グループメッセージは一切受け付けない デフォルトはgroupPolicy: "allowlist"（groupAllowFromを追加しない限りブロック）。

ほとんどのユーザーが望むもの：groupPolicy: "allowlist" + groupAllowFrom + channels.telegram.groupsにリストされた特定のグループ

ロングポーリング vs Webhook

  • デフォルト：ロングポーリング（公開URLは不要）。
  • Webhookモード：channels.telegram.webhookUrlを設定（オプションでchannels.telegram.webhookSecret + channels.telegram.webhookPath）。
    • ローカルリスナーは0.0.0.0:8787にバインドし、デフォルトでPOST /telegram-webhookを提供します。
    • 公開URLが異なる場合は、リバースプロキシを使用し、channels.telegram.webhookUrlを公開エンドポイントに向けます。

返信スレッド

Telegramはタグを介したオプションのスレッド返信をサポートします：

  • [[reply_to_current]] -- トリガーメッセージへの返信。
  • [[reply_to:<id>]] -- 特定のメッセージIDへの返信。

channels.telegram.replyToModeで制御：

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

音声メッセージ（ボイス vs ファイル）

Telegramはボイスノート（丸いバブル）と音声ファイル（メタデータカード）を区別します。 OpenClawは後方互換性のためデフォルトで音声ファイルを使用します。

エージェントの返信でボイスノートバブルを強制するには、返信の任意の場所にこのタグを含めます：

  • [[audio_as_voice]] — 音声をファイルではなくボイスノートとして送信。

タグは配信されるテキストから削除されます。他のチャネルはこのタグを無視します。

メッセージツール送信の場合、ボイス対応音声media URLでasVoice: trueを設定します （メディアが存在する場合、messageはオプション）：

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

ステッカー

OpenClawはTelegramステッカーの受信と送信をインテリジェントキャッシングでサポートします。

ステッカーの受信

ユーザーがステッカーを送信すると、OpenClawはステッカータイプに基づいて処理します：

  • 静的ステッカー（WEBP）： ダウンロードされ、ビジョンを通じて処理されます。ステッカーはメッセージコンテンツで<media:sticker>プレースホルダーとして表示されます。
  • アニメーションステッカー（TGS）： スキップ（Lottie形式は処理用にサポートされていません）。
  • ビデオステッカー（WEBM）： スキップ（ビデオ形式は処理用にサポートされていません）。

ステッカー受信時に利用可能なテンプレートコンテキストフィールド：

  • Sticker — 以下を含むオブジェクト：
    • emoji — ステッカーに関連付けられた絵文字
    • setName — ステッカーセットの名前
    • fileId — Telegram ファイルID（同じステッカーを送り返す）
    • fileUniqueId — キャッシュ検索用の安定したID
    • cachedDescription — 利用可能な場合のキャッシュされたビジョン説明

ステッカーキャッシュ

ステッカーはAIのビジョン機能を通じて処理され、説明が生成されます。同じステッカーが繰り返し送信されることが多いため、OpenClawは冗長なAPI呼び出しを避けるためにこれらの説明をキャッシュします。

仕組み：

  1. 初回遭遇： ステッカー画像がビジョン分析のためAIに送信されます。AIが説明を生成します（例：「熱心に手を振っている漫画の猫」）。
  2. キャッシュストレージ： 説明はステッカーのファイルID、絵文字、セット名とともに保存されます。
  3. 後続の遭遇： 同じステッカーが再び見られると、キャッシュされた説明が直接使用されます。画像はAIに送信されません。

キャッシュの場所： ~/.openclaw/telegram/sticker-cache.json

キャッシュエントリ形式：

{
  "fileId": "CAACAgIAAxkBAAI...",
  "fileUniqueId": "AgADBAADb6cxG2Y",
  "emoji": "👋",
  "setName": "CoolCats",
  "description": "熱心に手を振っている漫画の猫",
  "cachedAt": "2026-01-15T10:30:00.000Z"
}

メリット：

  • 同じステッカーに対する繰り返しのビジョン呼び出しを避けることでAPIコストを削減
  • キャッシュされたステッカーのレスポンス時間の高速化（ビジョン処理遅延なし）
  • キャッシュされた説明に基づくステッカー検索機能を有効化

キャッシュはステッカーが受信されると自動的に入力されます。手動のキャッシュ管理は不要です。

ステッカーの送信

エージェントはstickerおよびsticker-searchアクションを使用してステッカーを送信および検索できます。これらはデフォルトで無効になっており、設定で有効にする必要があります：

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

ステッカーを送信：

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

パラメーター：

  • fileId（必須） — ステッカーのTelegram ファイルID。ステッカー受信時にSticker.fileIdから取得するか、sticker-search結果から取得します。
  • replyTo（オプション） — 返信先メッセージID。
  • threadId（オプション） — フォーラムトピック用のメッセージスレッドID。

ステッカーを検索：

エージェントは、説明、絵文字、またはセット名でキャッシュされたステッカーを検索できます：

{
  "action": "sticker-search",
  "channel": "telegram",
  "query": "手を振っている猫",
  "limit": 5
}

キャッシュから一致するステッカーを返します：

{
  "ok": true,
  "count": 2,
  "stickers": [
    {
      "fileId": "CAACAgIAAxkBAAI...",
      "emoji": "👋",
      "description": "熱心に手を振っている漫画の猫",
      "setName": "CoolCats"
    }
  ]
}

検索は、説明テキスト、絵文字文字、セット名全体でファジーマッチングを使用します。

スレッド付きの例：

{
  "action": "sticker",
  "channel": "telegram",
  "to": "-1001234567890",
  "fileId": "CAACAgIAAxkBAAI...",
  "replyTo": 42,
  "threadId": 123
}

ストリーミング（ドラフト）

Telegramは、エージェントが応答を生成している間、ドラフトバブルをストリーミングできます。 OpenClawはBot APIのsendMessageDraft（実際のメッセージではない）を使用し、最終的な返信を通常のメッセージとして送信します。

要件（Telegram Bot API 9.3+）：

  • トピックが有効なプライベートチャット（ボットのフォーラムトピックモード）。
  • 受信メッセージにはmessage_thread_idが含まれている必要があります（プライベートトピックスレッド）。
  • グループ/スーパーグループ/チャネルではストリーミングは無視されます。

設定：

  • channels.telegram.streamMode: "off" | "partial" | "block"（デフォルト：partial）
    • partial：最新のストリーミングテキストでドラフトバブルを更新。
    • block：より大きなブロック（チャンク化）でドラフトバブルを更新。
    • off：ドラフトストリーミングを無効化。
  • オプション（streamMode: "block"のみ）：
    • channels.telegram.draftChunk: { minChars?, maxChars?, breakPreference? }
      • デフォルト：minChars: 200、maxChars: 800、breakPreference: "paragraph"（channels.telegram.textChunkLimitにクランプ）。

注意：ドラフトストリーミングはブロックストリーミング（チャネルメッセージ）とは別です。 ブロックストリーミングはデフォルトでオフで、ドラフト更新の代わりに早期Telegramメッセージが必要な場合はchannels.telegram.blockStreaming: trueが必要です。

推論ストリーム（Telegramのみ）：

  • /reasoning streamは、返信が生成されている間、ドラフトバブルに推論をストリーミングし、推論なしで最終的な回答を送信します。
  • channels.telegram.streamModeがoffの場合、推論ストリームは無効です。 詳細：ストリーミング + チャンク化。

再試行ポリシー

アウトバウンドTelegram API呼び出しは、一時的なネットワーク/429エラーで指数バックオフとジッターで再試行します。channels.telegram.retryで設定します。再試行ポリシーを参照してください。

エージェントツール（メッセージ + リアクション）

  • ツール：sendMessageアクション（to、content、オプションのmediaUrl、replyToMessageId、messageThreadId）を持つtelegram。
  • ツール：reactアクション（chatId、messageId、emoji）を持つtelegram。
  • ツール：deleteMessageアクション（chatId、messageId）を持つtelegram。
  • リアクション削除セマンティクス：/tools/reactionsを参照。
  • ツールゲート：channels.telegram.actions.reactions、channels.telegram.actions.sendMessage、channels.telegram.actions.deleteMessage（デフォルト：有効）、およびchannels.telegram.actions.sticker（デフォルト：無効）。

リアクション通知

リアクションの仕組み： Telegramリアクションは、メッセージペイロードのプロパティではなく、別個のmessage_reactionイベントとして到着します。ユーザーがリアクションを追加すると、OpenClawは：

  1. Telegram APIからmessage_reaction更新を受信
  2. 次の形式のシステムイベントに変換："Telegram reaction added: {emoji} by {user} on msg {id}"
  3. 通常のメッセージと同じセッションキーを使用してシステムイベントをエンキュー
  4. その会話に次のメッセージが到着すると、システムイベントがドレインされ、エージェントのコンテキストに前置きされます

エージェントは、メッセージメタデータではなく、会話履歴のシステム通知としてリアクションを見ます。

設定：

  • channels.telegram.reactionNotifications：どのリアクションが通知をトリガーするかを制御

    • "off" — すべてのリアクションを無視
    • "own" — ユーザーがボットメッセージにリアクションしたときに通知（ベストエフォート。インメモリ）（デフォルト）
    • "all" — すべてのリアクションを通知

  • channels.telegram.reactionLevel：エージェントのリアクション機能を制御

    • "off" — エージェントはメッセージにリアクションできない
    • "ack" — ボットは確認リアクション（処理中は👀）を送信（デフォルト）
    • "minimal" — エージェントは控えめにリアクション可能（ガイドライン：5〜10回の交換ごとに1回）
    • "extensive" — エージェントは適切な場合に自由にリアクション可能

フォーラムグループ： フォーラムグループのリアクションにはmessage_thread_idが含まれ、agent:main:telegram:group:{chatId}:topic:{threadId}のようなセッションキーを使用します。これにより、同じトピック内のリアクションとメッセージが一緒に保たれます。

設定例：

{
  channels: {
    telegram: {
      reactionNotifications: "all",  // すべてのリアクションを見る
      reactionLevel: "minimal"        // エージェントは控えめにリアクション可能
    }
  }
}

要件：

  • Telegramボットはallowed_updatesでmessage_reactionを明示的に要求する必要があります（OpenClawによって自動的に設定）
  • Webhookモードの場合、リアクションはWebhook allowed_updatesに含まれます
  • ポーリングモードの場合、リアクションはgetUpdates allowed_updatesに含まれます

配信ターゲット（CLI/cron）

  • チャットID（123456789）またはユーザー名（@name）をターゲットとして使用します。
  • 例：openclaw message send --channel telegram --target 123456789 --message "こんにちは"。

トラブルシューティング

ボットがグループ内の非メンションメッセージに応答しない：

  • channels.telegram.groups.*.requireMention=falseを設定した場合、Telegramの Bot API プライバシーモードを無効にする必要があります。
    • BotFather：/setprivacy → 無効（その後、グループからボットを削除して再追加）
  • openclaw channels statusは、設定がメンションされていないグループメッセージを期待している場合に警告を表示します。
  • openclaw channels status --probeは、明示的な数値グループIDのメンバーシップを追加でチェックできます（ワイルドカード"*"ルールは監査できません）。
  • クイックテスト：/activation always（セッションのみ。永続性には設定を使用）

ボットがグループメッセージをまったく見ない：

  • channels.telegram.groupsが設定されている場合、グループがリストされているか、"*"を使用する必要があります
  • @BotFatherのプライバシー設定を確認 → 「グループプライバシー」をオフにする必要があります
  • ボットが実際にメンバーであることを確認（読み取りアクセスのない管理者だけではない）
  • ゲートウェイログを確認：openclaw logs --follow（「グループメッセージをスキップ」を探す）

ボットはメンションには応答するが/activation alwaysには応答しない：

  • /activationコマンドはセッション状態を更新しますが、設定に永続化しません
  • 永続的な動作を得るには、requireMention: falseでグループをchannels.telegram.groupsに追加します

/statusなどのコマンドが機能しない：

  • TelegramユーザーIDが承認されていることを確認してください（ペアリングまたはchannels.telegram.allowFrom経由）
  • コマンドはgroupPolicy: "open"のグループでも承認が必要です

Node 22+でロングポーリングがすぐに中止される（多くの場合、プロキシ/カスタムフェッチを使用）：

  • Node 22+はAbortSignalインスタンスについてより厳格です。外部シグナルはfetch呼び出しをすぐに中止できます。
  • アボートシグナルを正規化するOpenClawビルドにアップグレードするか、アップグレードできるまでNode 20でゲートウェイを実行してください。

ボットが起動した後、静かに応答を停止する（またはログにHttpError: Network request ... failed）：

  • 一部のホストはapi.telegram.orgを最初にIPv6に解決します。サーバーが機能するIPv6エグレスを持っていない場合、grammYはIPv6専用リクエストで停止する可能性があります。
  • IPv6エグレスを有効にするまたはapi.telegram.orgのIPv4解決を強制することで修正します（例えば、IPv4 Aレコードを使用して/etc/hostsエントリを追加するか、OS DNSスタックでIPv4を優先します）、その後ゲートウェイを再起動します。
  • クイックチェック：dig +short api.telegram.org Aおよびdig +short api.telegram.org AAAAでDNSが何を返すかを確認します。

設定リファレンス（Telegram）

完全な設定：設定

プロバイダーオプション：

  • channels.telegram.enabled：チャネル起動の有効/無効。
  • channels.telegram.botToken：ボットトークン（BotFather）。
  • channels.telegram.tokenFile：ファイルパスからトークンを読み取る。
  • channels.telegram.dmPolicy：pairing | allowlist | open | disabled（デフォルト：pairing）。
  • channels.telegram.allowFrom：DM許可リスト（ID/ユーザー名）。openには"*"が必要。
  • channels.telegram.groupPolicy：open | allowlist | disabled（デフォルト：allowlist）。
  • channels.telegram.groupAllowFrom：グループ送信者許可リスト（ID/ユーザー名）。
  • channels.telegram.groups：グループごとのデフォルト + 許可リスト（グローバルデフォルトには"*"を使用）。
    • channels.telegram.groups.<id>.requireMention：メンション制御のデフォルト。
    • channels.telegram.groups.<id>.skills：スキルフィルター（省略 = すべてのスキル、空 = なし）。
    • channels.telegram.groups.<id>.allowFrom：グループごとの送信者許可リスト上書き。
    • channels.telegram.groups.<id>.systemPrompt：グループの追加システムプロンプト。
    • channels.telegram.groups.<id>.enabled：falseの場合、グループを無効化。
    • channels.telegram.groups.<id>.topics.<threadId>.*：トピックごとの上書き（グループと同じフィールド）。
    • channels.telegram.groups.<id>.topics.<threadId>.requireMention：トピックごとのメンション制御上書き。
  • channels.telegram.capabilities.inlineButtons：off | dm | group | all | allowlist（デフォルト：allowlist）。
  • channels.telegram.accounts.<account>.capabilities.inlineButtons：アカウントごとの上書き。
  • channels.telegram.replyToMode：off | first | all（デフォルト：first）。
  • channels.telegram.textChunkLimit：アウトバウンドチャンクサイズ（文字）。
  • channels.telegram.chunkMode：length（デフォルト）またはnewlineで、長さチャンク化の前に空白行（段落境界）で分割。
  • channels.telegram.linkPreview：アウトバウンドメッセージのリンクプレビューを切り替え（デフォルト：true）。
  • channels.telegram.streamMode：off | partial | block（ドラフトストリーミング）。
  • channels.telegram.mediaMaxMb：インバウンド/アウトバウンドメディアキャップ（MB）。
  • channels.telegram.retry：アウトバウンドTelegram API呼び出しの再試行ポリシー（attempts、minDelayMs、maxDelayMs、jitter）。
  • channels.telegram.network.autoSelectFamily：Node autoSelectFamilyを上書き（true=有効、false=無効）。Happy Eyeballsタイムアウトを避けるため、Node 22ではデフォルトで無効。
  • channels.telegram.proxy：Bot API呼び出しのプロキシURL（SOCKS/HTTP）。
  • channels.telegram.webhookUrl：Webhookモードを有効化。
  • channels.telegram.webhookSecret：Webhookシークレット（オプション）。
  • channels.telegram.webhookPath：ローカルWebhookパス（デフォルト/telegram-webhook）。
  • channels.telegram.actions.reactions：Telegramツールリアクションをゲート。
  • channels.telegram.actions.sendMessage：Telegramツールメッセージ送信をゲート。
  • channels.telegram.actions.deleteMessage：Telegramツールメッセージ削除をゲート。
  • channels.telegram.actions.sticker：Telegramステッカーアクション — 送信と検索をゲート（デフォルト：false）。
  • channels.telegram.reactionNotifications：off | own | all — どのリアクションがシステムイベントをトリガーするかを制御（デフォルト：設定されていない場合own）。
  • channels.telegram.reactionLevel：off | ack | minimal | extensive — エージェントのリアクション機能を制御（デフォルト：設定されていない場合minimal）。

関連するグローバルオプション：

  • agents.list[].groupChat.mentionPatterns（メンション制御パターン）。
  • messages.groupChat.mentionPatterns（グローバルフォールバック）。
  • commands.native（デフォルトは"auto" → Telegram/Discordでオン、Slackでオフ）、commands.text、commands.useAccessGroups（コマンドの動作）。channels.telegram.commands.nativeで上書き。
  • messages.responsePrefix、messages.ackReaction、messages.ackReactionScope、messages.removeAckAfterReply。
← ドキュメントに戻る