TelegramでOpenClawを使うイメージ

【最新版】TelegramでOpenClawを使う方法（Bot APIでDM・グループ連携）

Telegram

Telegram（Bot API）

ステータス：本番運用向け（production-ready）。 grammY による Bot の DM / グループ対応。デフォルトはロングポーリングで、Webhook モードも任意で利用できます。

関連ドキュメント

クイックセットアップ

Step 1：BotFather で bot token を作成する

Telegram を開き、@BotFather にチャットします（ハンドルが正確に @BotFather であることを確認してください）。

/newbot を実行し、案内に沿って進め、トークンを保存します。

Step 2：トークンと DM ポリシーを設定する

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

環境変数フォールバック：TELEGRAM_BOT_TOKEN=...（デフォルトアカウントのみ）。

Telegram は openclaw channels login telegram を使いません。 config / env にトークンを設定してから gateway を起動してください。

Step 3：gateway を起動し、最初の DM を承認する

openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

ペアリングコードは 1 時間で期限切れになります。

Step 4：bot をグループに追加する

bot をグループに追加し、channels.telegram.groups とgroupPolicy を、あなたのアクセスモデルに合わせて設定します。

注：トークンの解決順はアカウントを意識した挙動です。実務上は config の値が env フォールバックより優先され、TELEGRAM_BOT_TOKEN はデフォルトアカウントにのみ適用されます。

Telegram 側の設定

プライバシーモードとグループ可視性

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

bot がグループ内のすべてのメッセージを見る必要がある場合、次のいずれかを行います。

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

プライバシーモードを切り替えた場合、Telegram が変更を反映するように、各グループから bot を一度削除して再追加してください。

グループ権限

管理者権限は Telegram のグループ設定で制御します。管理者 bot はグループ内のすべてのメッセージを受信でき、常時稼働のグループ運用に便利です。

BotFather の便利な切り替え

  • /setjoingroups：グループへの追加を許可 / 拒否
  • /setprivacy：グループ可視性の挙動

アクセス制御と有効化

DM ポリシー

channels.telegram.dmPolicy が、ダイレクトメッセージ（DM）のアクセスを制御します：

  • pairing（デフォルト）
  • allowlist（allowFrom に少なくとも 1 件の送信者 ID が必要）
  • open（allowFrom に "*" を含める必要）
  • disabled

channels.telegram.allowFrom は Telegram の数値ユーザー IDを受け付けます。telegram: / tg: プレフィックスは受理され、正規化されます。

  • dmPolicy: "allowlist" で allowFrom が空だと、すべての DM がブロックされ、設定バリデーションで拒否されます。
  • オンボーディングは @username 入力を受け付け、数値 ID に解決します。
  • アップグレード後に allowlist が @username のまま残っている場合、openclaw doctor --fix で数値 ID へ解決できます（ベストエフォート。Telegram bot token が必要）。
  • 以前 pairing-store の allowlist ファイルに依存していた場合、openclaw doctor --fix が channels.telegram.allowFrom（allowlist フロー）へ復元できることがあります（例：dmPolicy: "allowlist" だが明示 ID がまだない場合）。

単一オーナー運用の bot では、アクセス制御を config に固定できるよう、dmPolicy: "allowlist" + 明示的な数値 allowFrom を推奨します（過去のペアリング承認に依存しない）。

Telegram のユーザー ID を見つける方法

より安全（サードパーティ bot 不使用）：

  1. 自分の bot に DM を送る
  2. openclaw logs --follow を実行する
  3. from.id を読む

公式 Bot API の方法：

curl "https://api.telegram.org/bot<bot_token>/getUpdates"

サードパーティの方法（プライバシー面では劣る）：@userinfobot / @getidsbot

グループポリシーと allowlist

次の 2 つの制御が同時に適用されます。

  • どのグループを許可するか（channels.telegram.groups）
    • groups 設定なし：
      • groupPolicy: "open" の場合、どのグループでも group-ID チェックを通過可能
      • groupPolicy: "allowlist"（デフォルト）の場合、groups に ID（または "*"）を追加するまでブロック
    • groups 設定あり：allowlist として機能（明示 ID か "*"）
  • グループ内のどの送信者を許可するか（channels.telegram.groupPolicy）
    • open
    • allowlist（デフォルト）
    • disabled

groupAllowFrom はグループ送信者フィルタに使われます。設定されていない場合、Telegram は allowFrom にフォールバックします。

  • groupAllowFrom は数値 Telegram ユーザー ID を指定してください（telegram: / tg: は正規化）。
  • Telegram のグループ / supergroup の chat ID（負の ID）を groupAllowFrom に入れないでください。負の chat ID は channels.telegram.groups 側です。
  • 送信者認可では、非数値のエントリは無視されます。
  • セキュリティ境界（2026.2.25+）：グループ送信者認可は DM の pairing-store 承認を継承しません。
  • ペアリングは DM 専用です。グループでは groupAllowFrom か、グループ/トピック単位の allowFrom を設定してください。
  • 実行時の注意：channels.telegram が完全に欠けている場合、channels.defaults.groupPolicy を明示しない限り、実行時は fail-closed で groupPolicy="allowlist" が既定になります。

例：特定の 1 グループでは誰でも許可する：

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          groupPolicy: &quot;open&quot;,
          requireMention: false,
        },
      },
    },
  },
}

例：特定の 1 グループ内で、特定ユーザーだけ許可する：

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          requireMention: true,
          allowFrom: ["8734062810", "745123456"],
        },
      },
    },
  },
}

よくある間違い：

  • groupAllowFrom は Telegram グループの allowlist ではありません。
  • 負の Telegram グループ / supergroup chat ID（例：-1001234567890）は channels.telegram.groups に入れてください。
  • Telegram ユーザー ID（例：8734062810）は、許可されたグループ内で話しかけられる人を制限したい場合に groupAllowFrom に入れます。
  • 許可されたグループの任意メンバーに bot を使わせたい場合のみ groupAllowFrom: ["*"] を使ってください。

メンション挙動

グループ返信はデフォルトでメンションが必要です。

メンションは次のいずれかで成立します：

  • ネイティブの @botusername メンション
  • メンションパターン（agents.list[].groupChat.mentionPatterns / messages.groupChat.mentionPatterns）

セッション単位のコマンド切り替え：

  • /activation always
  • /activation mention

これはセッション状態のみ更新します。永続化は config を使ってください。

永続設定例：

{
  channels: {
    telegram: {
      groups: {
        &quot;*&quot;: { requireMention: false },
      },
    },
  },
}

グループ chat ID の取得方法：

  • グループメッセージを @userinfobot / @getidsbot に転送
  • openclaw logs --follow から chat.id を読む
  • Bot API の getUpdates を確認

実行時の挙動

  • Telegram は gateway プロセスが所有します。
  • ルーティングは決定的です：Telegram の受信返信は Telegram に戻ります（モデルがチャンネルを選びません）。
  • 受信メッセージは共有のチャンネルエンベロープに正規化され、返信メタデータとメディアプレースホルダーを保持します。
  • グループセッションは group ID で分離されます。フォーラムトピックは :topic:<threadId> を付けて分離されます。
  • DM は message_thread_id を持つことがあり、OpenClaw はスレッド対応のセッションキーでルーティングし、返信でも thread ID を保持します。
  • ロングポーリングは grammY runner を使い、チャット/スレッド単位でシーケンスを保証します。全体の runner sink の同時実行は agents.defaults.maxConcurrent に従います。
  • Telegram Bot API は既読（read receipt）をサポートしません（sendReadReceipts は適用されません）。

機能リファレンス

ライブストリームプレビュー（メッセージ編集）

OpenClaw は部分的な返信をリアルタイムでストリームできます：

  • ダイレクトチャット：プレビュー message + editMessageText
  • グループ/トピック：プレビュー message + editMessageText

要件：

  • channels.telegram.streaming：off | partial | block | progress（デフォルト：partial）
  • progress は Telegram では partial にマップされます（クロスチャンネル命名との互換）。
  • レガシーの channels.telegram.streamMode と boolean streaming 値は自動マップされます。

テキストのみ返信の場合：

  • DM：同じプレビューを保ち、最後に編集で確定（2 通目は送らない）
  • グループ/トピック：同様に 1 通で完結

複雑な返信（例：メディア payload）では、通常の最終配信にフォールバックし、プレビューはクリーンアップされます。

プレビューストリーミングはブロックストリーミングとは別です。Telegram で block streaming を明示的に有効化した場合、二重ストリーミング回避のためプレビューはスキップされます。

ネイティブ draft transport が利用できない/拒否される場合、OpenClaw は自動的に sendMessage + editMessageText にフォールバックします。

Telegram 専用 reasoning ストリーム：/reasoning stream は生成中に reasoning をライブプレビューへ送信し、最終回答は reasoning テキストなしで送信します。

フォーマットと HTML フォールバック

送信テキストは Telegram の parse_mode: "HTML" を使います。

  • Markdown っぽいテキストは Telegram 安全な HTML にレンダリングされます。
  • モデルが生成した生の HTML は Telegram の parse 失敗を減らすためにエスケープされます。
  • Telegram が parse 済み HTML を拒否した場合、OpenClaw は plain text として再試行します。

リンクプレビューはデフォルトで有効で、channels.telegram.linkPreview: false で無効化できます。

ネイティブコマンドとカスタムコマンド

Telegram のコマンドメニュー登録は起動時に setMyCommands で行われます。

ネイティブコマンドの既定：

  • commands.native: "auto" で Telegram のネイティブコマンドを有効化

カスタムコマンドメニューを追加する：

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

ルール：

  • 名前は正規化（先頭の / を除去、lowercase）
  • 有効パターン：a-z, 0-9, _、長さ 1..32
  • カスタムコマンドはネイティブコマンドを上書きできない
  • 競合/重複はスキップされログに出る

注意：

  • カスタムコマンドはメニュー項目のみで、挙動を自動実装しません。
  • Telegram メニューに表示されなくても、plugin/skill コマンドは typed で動作する場合があります。
  • ネイティブコマンドを無効化すると built-in は削除されます。カスタム/plugin は設定次第で登録されることがあります。

よくあるセットアップ失敗：

  • setMyCommands が BOT_COMMANDS_TOO_MUCH：メニューが溢れています。plugin/skill/custom の数を減らすか、channels.telegram.commands.native を無効化してください。
  • setMyCommands が network/fetch エラー：api.telegram.org への DNS/HTTPS がブロックされている可能性があります。

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

device-pair plugin がインストールされている場合：

  • /pair：セットアップコードを生成
  • iOS アプリにコードを貼り付け
  • /pair approve：最新の保留リクエストを承認

詳細：Pairing

インラインボタン

インラインキーボードのスコープを設定：

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

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

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

スコープ：

  • off
  • dm
  • group
  • all
  • allowlist（デフォルト）

レガシー：capabilities: ["inlineButtons"] は inlineButtons: "all" にマップされます。

メッセージアクション例：

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

クリックはテキストとして agent に渡されます：callback_data: <value>

Telegram のメッセージアクション（agents / automation 用）

Telegram tool actions には次が含まれます：

  • sendMessage（to, content, optional mediaUrl, replyToMessageId, messageThreadId）
  • react（chatId, messageId, emoji）
  • deleteMessage（chatId, messageId）
  • editMessage（chatId, messageId, content）
  • createForumTopic（chatId, name, optional iconColor, iconCustomEmojiId）

チャンネルメッセージアクションはエイリアスも提供します（send / react / delete / edit / sticker / sticker-search / topic-create）。

ゲーティング制御：

  • channels.telegram.actions.sendMessage
  • channels.telegram.actions.deleteMessage
  • channels.telegram.actions.reactions
  • channels.telegram.actions.sticker（デフォルト：disabled）

注：edit と topic-create は現在デフォルトで有効で、個別の channels.telegram.actions.* トグルはありません。 実行時の send は有効な config/secrets スナップショット（起動/リロード）を使うため、action パスで送信ごとの SecretRef 再解決はしません。

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

返信スレッディングタグ

Telegram は生成出力に返信スレッディングタグを明示できます：

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

channels.telegram.replyToMode の扱い：

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

注：off は暗黙の返信スレッディングを無効化しますが、明示タグ [[reply_to_*]] は引き続き尊重されます。

フォーラムトピックとスレッド挙動

フォーラム supergroup：

  • トピックのセッションキーは :topic:<threadId> を付けます
  • 返信と typing はトピック thread をターゲットにします
  • トピック設定パス：channels.telegram.groups.<chatId>.topics.<threadId>

General topic（threadId=1）の特別扱い：

  • message send は message_thread_id を省略（Telegram が sendMessage(...thread_id=1) を拒否するため）
  • typing アクションは message_thread_id を含む

トピックの継承：

トピックエントリは、上書きされない限りグループ設定を継承します（requireMention / allowFrom / skills / systemPrompt / enabled / groupPolicy）。agentId はトピック専用で、グループデフォルトから継承しません。

トピック単位の agent ルーティング：

各トピックは config の agentId で別 agent にルーティングできます。各トピックは独立した workspace / memory / session を持てます。例：

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

このとき各トピックは次のセッションキーになります：agent:zu:telegram:group:-1001234567890:topic:3

永続 ACP トピックバインディング：

フォーラムトピックは、トップレベルの typed ACP bindings により ACP harness セッションをピン留めできます：

bindings[] に type: "acp"、match.channel: "telegram" を指定します。

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: &quot;acp&quot;,
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: &quot;acp&quot;,
      agentId: "codex",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
    },
  ],
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "42": {
              requireMention: false,
            },
          },
        },
      },
    },
  },
}

これは現在、グループ/supergroup のフォーラムトピックにスコープされています。

チャットからの thread-bound ACP spawn：

/acp spawn <agent> --thread here|auto で現在の Telegram トピックを新しい ACP セッションにバインドできます。 以後のトピックメッセージは、バインドされた ACP セッションに直接ルーティングされます（/acp steer 不要）。 バインドに成功すると OpenClaw は spawn 確認メッセージをトピックにピン留めします。 これには channels.telegram.threadBindings.spawnAcpSessions=true が必要です。

テンプレートコンテキストには次を含みます：MessageThreadId / IsForum

DM のスレッド挙動：

private chat の message_thread_id は DM ルーティングを維持しますが、スレッド対応のセッションキーと返信ターゲットを使います。

音声・動画・ステッカー

音声メッセージ

Telegram はボイスノートと音声ファイルを区別します。デフォルトは音声ファイル扱いです。

agent の返信に [[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,
}

ビデオノートはキャプションをサポートしないため、メッセージテキストは別送されます。

ステッカー

受信ステッカーの扱い：

  • 静的 WEBP：ダウンロードして処理（プレースホルダー <media:sticker>）
  • アニメ TGS：スキップ
  • 動画 WEBM：スキップ

ステッカーのコンテキストフィールド：

  • Sticker.emoji
  • Sticker.setName
  • Sticker.fileId
  • Sticker.fileUniqueId
  • Sticker.cachedDescription

ステッカーキャッシュファイル：~/.openclaw/telegram/sticker-cache.json

ステッカーは可能なら 1 回だけ説明し、キャッシュして vision 呼び出しを減らします。

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

{
  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 update として届きます（message payload とは別）。

有効化すると OpenClaw は次のような system event をキューに入れます：

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 はリアクション update に thread ID を提供しません。
  • 非フォーラムグループはグループチャットセッションにルーティング。
  • フォーラムグループは group の general-topic セッション（:topic:1）にルーティングされ、元のトピックには戻りません。
  • ポーリング/Webhook の allowed_updates には message_reaction が自動で含まれます。

Ack リアクション

ackReaction は、OpenClaw が受信メッセージを処理中に「受け取った」絵文字を返します。

解決順：

  • channels.telegram.accounts.<accountId>.ackReaction
  • channels.telegram.ackReaction
  • messages.ackReaction
  • agent identity 絵文字のフォールバック（agents.list[].identity.emoji、なければ "👀"）

注：

  • Telegram は unicode emoji（例："👀"）を想定します。
  • チャンネル/アカウントで無効化するには空文字列 "" を使います。

Telegram イベント/コマンドによる config 書き込み

チャンネル config 書き込みはデフォルトで有効です（configWrites !== false）。

Telegram 起因の書き込み例：

  • グループ移行イベント（migrate_to_chat_id）による channels.telegram.groups 更新
  • /config set と /config unset（コマンドが有効化されている場合）

無効化：

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

ロングポーリング vs Webhook

デフォルト：ロングポーリング。

Webhook モード：

  • channels.telegram.webhookUrl を設定
  • channels.telegram.webhookSecret を設定（webhookUrl がある場合は必須）
  • 任意：channels.telegram.webhookPath（デフォルト /telegram-webhook）
  • 任意：channels.telegram.webhookHost（デフォルト 127.0.0.1）
  • 任意：channels.telegram.webhookPort（デフォルト 8787）

Webhook モードのデフォルトのローカルリスナーは 127.0.0.1:8787 に bind します。

公開エンドポイントが異なる場合は、リバースプロキシを前段に置き、webhookUrl を公開 URL に向けてください。

意図的に外部からの ingress が必要な場合は webhookHost（例：0.0.0.0）を設定します。

制限、リトライ、CLI ターゲット

  • channels.telegram.textChunkLimit のデフォルトは 4000。
  • channels.telegram.chunkMode="newline" は、長さ分割の前に段落境界（空行）を優先します。
  • channels.telegram.mediaMaxMb（デフォルト 100）は Telegram の入出力メディアサイズ上限（MB）。
  • channels.telegram.timeoutSeconds は Telegram API クライアントの timeout を上書き（未設定なら grammY のデフォルト）。
  • グループのコンテキスト履歴は channels.telegram.historyLimit または messages.groupChat.historyLimit（デフォルト 50）。0 で無効化。
  • DM 履歴：channels.telegram.dmHistoryLimit / channels.telegram.dms["<user_id>"].historyLimit
  • channels.telegram.retry は Telegram の送信ヘルパー（CLI/tools/actions）のリトライポリシーに適用（recoverable outbound API エラー）。

CLI の送信ターゲットは数値 chat ID または username：

openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"

Telegram の poll は openclaw message poll を使い、フォーラムトピックもサポートします：

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

Telegram 専用 poll フラグ：

  • --poll-duration-seconds（5-600）
  • --poll-anonymous
  • --poll-public
  • --thread-id（フォーラムトピック。もしくは :topic: 形式の target）

Telegram の send は次もサポートします：

  • --buttons（channels.telegram.capabilities.inlineButtons が許す場合にインラインキーボード）
  • --force-document（画像や GIF を圧縮アップロードではなく document として送る）

アクションゲーティング：

  • channels.telegram.actions.sendMessage=false で Telegram 送信（poll 含む）を無効化
  • channels.telegram.actions.poll=false で poll 作成のみ無効化（通常 send は残す）

Telegram での exec 承認（Exec approvals）

Telegram は approver の DM で exec 承認をサポートし、任意で元のチャット/トピックにも承認プロンプトを投稿できます。

設定パス：

  • channels.telegram.execApprovals.enabled
  • channels.telegram.execApprovals.approvers
  • channels.telegram.execApprovals.target（dm | channel | both、デフォルト dm）
  • agentFilter, sessionFilter

approver は数値 Telegram ユーザー ID である必要があります。 enabled が false、または approvers が空の場合、Telegram は exec 承認クライアントとして動作しません。 承認リクエストは他の承認ルート、または exec 承認フォールバックポリシーにフォールバックします。

配信ルール：

  • target: "dm"：設定された approver DM にのみ送信
  • target: "channel"：元の Telegram チャット/トピックにプロンプトを返す
  • target: "both"：approver DM と元のチャット/トピックの両方へ送る

設定された approver のみが approve/deny できます。非 approver は /approve や Telegram 承認ボタンを使えません。

channel への配信はチャットにコマンド本文が表示されるため、信頼できるグループ/トピックでのみ channel / both を有効化してください。

フォーラムトピックにプロンプトが届く場合、OpenClaw は承認プロンプトと承認後フォローアップの両方でトピックを保持します。

インライン承認ボタンは、channels.telegram.capabilities.inlineButtons が対象サーフェス（dm/group/all）を許可している必要があります。

関連：Exec approvals

トラブルシューティング

bot が「メンションなし」のグループメッセージに反応しない

  • requireMention=false の場合、Telegram の privacy mode がフル可視性を許可している必要があります。
  • BotFather：/setprivacy → Disable → その後 bot をグループから削除して再追加。
  • openclaw channels status は、設定がメンションなしグループメッセージを期待している場合に警告します。
  • openclaw channels status --probe は数値の group ID を明示した場合に membership を probe できます（ワイルドカード "*" は probe 不可）。
  • クイックなセッションテスト：/activation always。

bot がグループメッセージをまったく見ていない

  • channels.telegram.groups が存在する場合、グループが list されている（または "*" を含む）必要があります。
  • bot がグループに参加していることを確認。
  • openclaw logs --follow を見て、スキップ理由を確認。

コマンドが部分的にしか動かない / まったく動かない

  • 送信者のアイデンティティを認可してください（pairing および/または数値 allowFrom）。
  • グループポリシーが open でも、コマンド認可は適用されます。
  • setMyCommands が BOT_COMMANDS_TOO_MUCH：メニュー項目が多すぎます。plugin/skill/custom を減らすかネイティブメニューを無効化してください。
  • setMyCommands の network/fetch エラー：api.telegram.org への DNS/HTTPS 到達性の問題の可能性。

ポーリングやネットワーク不安定

Node 22+ + カスタム fetch/proxy により、AbortSignal の型不一致で即時 abort が起きることがあります。

一部ホストは api.telegram.org を IPv6 優先で解決します。IPv6 の egress が壊れていると Telegram API の失敗が断続的に起きます。

ログに TypeError: fetch failed や Network request for 'getUpdates' failed! がある場合、OpenClaw はこれらを recoverable network error としてリトライするようになりました。

VPS で egress/TLS が不安定な場合、Telegram API を channels.telegram.proxy でプロキシできます：

channels:
  telegram:
    proxy: socks5://<user>:<password>@proxy-host:1080

Node 22+ はデフォルトで autoSelectFamily=true（WSL2 を除く）、dnsResultOrder=ipv4first です。

WSL2 または IPv4-only のほうが良い環境では、family selection を固定できます：

channels:
  telegram:
    network:
      autoSelectFamily: false

環境変数上書き（暫定）：

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

参考（Telegram config 参照ポインタ）

プライマリ参照：

  • channels.telegram.enabled：チャンネル起動の有効/無効
  • channels.telegram.botToken：bot token（BotFather）
  • channels.telegram.tokenFile：通常ファイルパスから token を読む（symlink は拒否）
  • channels.telegram.dmPolicy：pairing | allowlist | open | disabled（デフォルト：pairing）
  • channels.telegram.allowFrom：DM allowlist（数値 Telegram user ID）。allowlist には 1 件以上必須。open には "*" 必須。openclaw doctor --fix はレガシー @username を ID に解決し、移行フローでは pairing-store から allowlist を回復できます。
  • channels.telegram.actions.poll：Telegram poll 作成の有効/無効（デフォルト：enabled。sendMessage も必要）
  • channels.telegram.defaultTo：CLI --deliver で --reply-to がない場合のデフォルト target
  • channels.telegram.groupPolicy：open | allowlist | disabled（デフォルト：allowlist）
  • channels.telegram.groupAllowFrom：グループ送信者 allowlist（数値 Telegram user ID）。openclaw doctor --fix でレガシー @username を解決できます。非数値は認可時に無視。グループ認可は DM pairing-store フォールバックを使用しません（2026.2.25+）。

マルチアカウント優先順位：

  • 2 つ以上の account ID を設定する場合、channels.telegram.defaultAccount を設定（または channels.telegram.accounts.default を含める）して、デフォルトルーティングを明示します。
  • どちらも設定されない場合、OpenClaw は最初に正規化された account ID にフォールバックし、openclaw doctor が警告します。
  • channels.telegram.accounts.default.allowFrom と groupAllowFrom はデフォルトアカウントのみに適用。
  • 名前付きアカウントは、アカウントレベル値が未設定の場合にのみ channels.telegram.allowFrom / groupAllowFrom を継承します。
  • 名前付きアカウントは channels.telegram.accounts.default.allowFrom / groupAllowFrom を継承しません。

その他の参照（抜粋）：

  • channels.telegram.groups：グループ別デフォルト + allowlist（グローバルデフォルトは "*"）
  • channels.telegram.groups.<id>.groupPolicy：グループ別 override
  • channels.telegram.groups.<id>.requireMention：メンションゲーティング
  • channels.telegram.groups.<id>.skills：skill フィルタ（省略=全 skill、空=なし）
  • channels.telegram.groups.<id>.allowFrom：グループ別送信者 allowlist override
  • channels.telegram.groups.<id>.systemPrompt：グループ用の追加 system prompt
  • channels.telegram.groups.<id>.enabled：false でグループ無効化
  • channels.telegram.groups.<id>.topics.<threadId>.*：トピック別 override（+ トピック専用 agentId）
  • channels.telegram.groups.<id>.topics.<threadId>.agentId：特定 agent にルーティング
  • トップレベル bindings[]（type: "acp"）：match.peer.id に chatId:topic:topicId を指定（ACP Agents を参照）
  • channels.telegram.direct.<id>.topics.<threadId>.agentId：DM トピックを特定 agent へルーティング（フォーラムトピックと同様）
  • channels.telegram.execApprovals.* と channels.telegram.accounts.<account>.execApprovals：exec 承認
  • channels.telegram.capabilities.inlineButtons とアカウント別 override
  • channels.telegram.commands.nativeSkills：Telegram ネイティブ skills コマンド
  • channels.telegram.replyToMode：返信ターゲット
  • channels.telegram.textChunkLimit, chunkMode, linkPreview, streaming, mediaMaxMb, timeoutSeconds, retry, network.autoSelectFamily, proxy
  • channels.telegram.webhookUrl, webhookSecret, webhookPath, webhookHost, webhookPort
  • channels.telegram.actions.*：sendMessage/editMessage/deleteMessage/reactions/sticker の gating
  • channels.telegram.reactionNotifications, reactionLevel
  • channels.telegram.configWrites、履歴：historyLimit, dmHistoryLimit, dms.*.historyLimit

関連

参考

BizClaw 導入支援

OpenClaw の構築を
まるごと代行します

Mac mini のセットアップから Slack・iMessage 連携まで、届いた日から使える状態でお届けします。

サービスを見る

関連記事

Read article
AIエージェントのメモリスタックとは？2026年に重要度が上がる理由をやさしく解説

AIエージェントのメモリスタックとは？2026年に重要度が上がる理由をやさしく解説

Read article
OpenClaw vs Hermes vs Claude、創業者はどれを選ぶべき？2026年版の実務比較

OpenClaw vs Hermes vs Claude、創業者はどれを選ぶべき？2026年版の実務比較

Read article
X公式MCPサーバーとは？AIエージェント運用で何が変わるのかを実務目線で解説

X公式MCPサーバーとは？AIエージェント運用で何が変わるのかを実務目線で解説