Telegram

​

クイックセットアップ

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

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

​

Telegram側の設定

​

アクセス制御とアクティベーション

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

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

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: false },
      },
    },
  },
}

​

実行時の動作

• テレグラムはゲートウェイプロセスによって所有されます。
• ルーティングは決定的です: Telegram の受信応答は Telegram に返されます (モデルはチャネルを選択しません)。
• 受信メッセージは、返信メタデータとメディア プレースホルダーを使用して共有チャネル エンベロープに正規化されます。
• グループセッションはグループIDによって分離されます。トピックを分離するために、フォーラムのトピックには :topic:<threadId> が追加されます。
• DM メッセージには message_thread_id を含めることができます。 OpenClaw は、スレッド対応のセッション キーを使用してそれらをルーティングし、応答用のスレッド ID を保存します。
• ロングポーリングでは、チャットごと/スレッドごとのシーケンスを持つ grammY ランナーを使用します。全体的なランナー シンクの同時実行性は agents.defaults.maxConcurrent を使用します。
• Telegram Bot API には読み取り受信サポートがありません (sendReadReceipts は適用されません)。

​

機能リファレンス

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

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

{
  channels: {
    telegram: {
      accounts: {
        main: {
          capabilities: {
            inlineButtons: "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" }],
  ],
}

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

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

{
  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: {
      configWrites: false,
    },
  },
}

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

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:
    proxy: socks5://<user>:<password>@proxy-host:1080

channels:
  telegram:
    network:
      autoSelectFamily: false

dig +short api.telegram.org A
dig +short api.telegram.org AAAA

​

Telegram 構成参照ポインタ

• channels.telegram.botToken: ボット トークン (BotFather)。
• channels.telegram.tokenFile: ファイル パスからトークンを読み取ります。
• channels.telegram.dmPolicy: pairing | allowlist | open | disabled (デフォルト: ペアリング)。
• channels.telegram.allowFrom: DM 許可リスト (数値の Telegram ユーザー ID)。 allowlist には少なくとも 1 つの送信者 ID が必要です。 open には "*" が必要です。 openclaw doctor --fix は、レガシー @username エントリを ID に解決でき、ホワイトリスト移行フローのペアリング ストア ファイルからホワイトリスト エントリを回復できます。
• channels.telegram.actions.poll: Telegram 投票の作成を有効または無効にします (デフォルト: 有効。それでも sendMessage が必要です)。
• channels.telegram.defaultTo: 明示的な --reply-to が指定されていない場合に、CLI --deliver によって使用されるデフォルトの Telegram ターゲット。
• channels.telegram.groupPolicy: open | allowlist | disabled (デフォルト: ホワイトリスト)。
• channels.telegram.groupAllowFrom: グループ送信者の許可リスト (数値の Telegram ユーザー ID)。 openclaw doctor --fix は、従来の @username エントリを ID に解決できます。数値以外のエントリは認証時に無視されます。グループ認証では、DM ペアリングとストアのフォールバックは使用されません (2026.2.25+)。
• マルチアカウントの優先順位:
  • 2 つ以上のアカウント ID が設定されている場合は、channels.telegram.defaultAccount を設定 (または channels.telegram.accounts.default を含めて) デフォルトのルーティングを明示します。
  • どちらも設定されていない場合、OpenClaw は最初の正規化されたアカウント ID にフォールバックし、openclaw doctor が警告します。- channels.telegram.accounts.default.allowFrom および channels.telegram.accounts.default.groupAllowFrom は、default アカウントにのみ適用されます。
  • アカウントレベルの値が設定されていない場合、名前付きアカウントは channels.telegram.allowFrom および channels.telegram.groupAllowFrom を継承します。
  • 名前付きアカウントは channels.telegram.accounts.default.allowFrom / groupAllowFrom を継承しません。
• channels.telegram.groups: グループごとのデフォルト + ホワイトリスト (グローバルデフォルトには "*" を使用します)。
  • channels.telegram.groups.<id>.groupPolicy: groupPolicy のグループごとの上書き (open | allowlist | disabled)。
  • 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>.*: トピックごとのオーバーライド (グループ フィールド + トピックのみ agentId)。
  • channels.telegram.groups.<id>.topics.<threadId>.agentId: このトピックを特定のエージェントにルーティングします (グループ レベルおよびバインディング ルーティングをオーバーライドします)。
  • channels.telegram.groups.<id>.topics.<threadId>.groupPolicy: groupPolicy のトピックごとのオーバーライド (open | allowlist | disabled)。
  • channels.telegram.groups.<id>.topics.<threadId>.requireMention: トピックごとのメンション ゲートのオーバーライド。
  • トップレベル bindings[] と type: "acp" および正規トピック ID chatId:topic:topicId (match.peer.id): 永続的な ACP トピック バインディング フィールド (ACP エージェント を参照)。
  • channels.telegram.direct.<id>.topics.<threadId>.agentId: DM トピックを特定のエージェントにルーティングします (フォーラム トピックと同じ動作)。
• channels.telegram.capabilities.inlineButtons: off | dm | group | all | allowlist (デフォルト: ホワイトリスト)。- channels.telegram.accounts.<account>.capabilities.inlineButtons: アカウントごとの上書き。
• channels.telegram.commands.nativeSkills: Telegram ネイティブ スキル コマンドを有効/無効にします。
• channels.telegram.replyToMode: off | first | all (デフォルト: off)。
• channels.telegram.textChunkLimit: 送信チャンク サイズ (文字数)。
• channels.telegram.chunkMode: length (デフォルト) または newline は、長さをチャンクする前に空白行 (段落境界) で分割します。
• channels.telegram.linkPreview: 送信メッセージのリンク プレビューを切り替えます (デフォルト: true)。
• channels.telegram.streaming: off | partial | block | progress (ライブ ストリーム プレビュー; デフォルト: partial; progress は partial にマップされます。 block は従来のプレビュー モードとの互換性です)。 Telegram プレビュー ストリーミングでは、その場で編集された単一のプレビュー メッセージが使用されます。
• channels.telegram.mediaMaxMb: インバウンド/アウトバウンド Telegram メディアの上限 (MB、デフォルト: 100)。
• channels.telegram.retry: 回復可能なアウトバウンド API エラー (試行、minDelayMs、maxDelayMs、ジッター) に対する Telegram 送信ヘルパー (CLI/ツール/アクション) の再試行ポリシー。
• channels.telegram.network.autoSelectFamily: ノード autoSelectFamily をオーバーライドします (true=有効、false=無効)。ノード 22 以降ではデフォルトで有効になり、WSL2 はデフォルトで無効になります。
• channels.telegram.network.dnsResultOrder: DNS 結果の順序を上書きします (ipv4first または verbatim)。ノード 22 以降のデフォルトは ipv4first です。
• channels.telegram.proxy: ボット API 呼び出しのプロキシ URL (SOCKS/HTTP)。
• channels.telegram.webhookUrl: Webhook モードを有効にします (channels.telegram.webhookSecret が必要)。- channels.telegram.webhookSecret: Webhook シークレット (WebhookUrl が設定されている場合に必要)。
• channels.telegram.webhookPath: ローカル Webhook パス (デフォルト /telegram-webhook)。
• channels.telegram.webhookHost: ローカル Webhook バインド ホスト (デフォルト 127.0.0.1)。
• channels.telegram.webhookPort: ローカル Webhook バインド ポート (デフォルト 8787)。
• channels.telegram.actions.reactions: ゲートTelegramツールの反応。
• channels.telegram.actions.sendMessage: ゲート テレグラム ツール メッセージの送信。
• channels.telegram.actions.deleteMessage: ゲート テレグラム ツール メッセージが削除されます。
• channels.telegram.actions.sticker: ゲート テレグラム ステッカー アクション — 送信および検索 (デフォルト: false)。
• channels.telegram.reactionNotifications: off | own | all — どの反応がシステム イベントをトリガーするかを制御します (設定されていない場合、デフォルト: own)。
• channels.telegram.reactionLevel: off | ack | minimal | extensive — 制御エージェントの反応能力 (設定されていない場合のデフォルト: minimal)。
• 設定リファレンス - Telegram

• アクセス制御: dmPolicy、allowFrom、groupPolicy、groupAllowFrom、groups、groups.*.topics.*、トップレベル bindings[] (type: "acp")
• コマンド/メニュー: commands.native、commands.nativeSkills、customCommands
• スレッド化/返信: replyToMode
• ストリーミング: streaming (プレビュー)、blockStreaming
• フォーマット/配信: textChunkLimit、chunkMode、linkPreview、responsePrefix
• メディア/ネットワーク: mediaMaxMb、timeoutSeconds、retry、network.autoSelectFamily、proxy
• Webhook: webhookUrl、webhookSecret、webhookPath、webhookHost
• アクション/機能: capabilities.inlineButtons、actions.sendMessage|editMessage|deleteMessage|reactions|sticker
• 反応: reactionNotifications、reactionLevel
• 書き込み/履歴: configWrites、historyLimit、dmHistoryLimit、dms.*.historyLimit

​

関連

• ペアリング
• チャンネルルーティング
• マルチエージェントルーティング
• トラブルシューティング