メインコンテンツへスキップ

​
Telegram（Bot API）

状態: grammY 経由でボット DM + グループに本番対応。デフォルトはロングポーリング、webhook モードは任意です。

ペアリング

Telegram のデフォルト DM ポリシーはペアリングです。

チャンネルトラブルシューティング

クロスチャネル診断と修復プレイブック。

ゲートウェイ設定

チャンネル設定パターンと完全な例。

​
クイックセットアップ

1

BotFather でボットトークンを作成

Telegram を開き、@BotFather とチャットします（ハンドルが正確に @BotFather であることを確認）。/newbot を実行し、指示に従ってトークンを保存します。
2

トークンと DM ポリシーを設定

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}
環境変数フォールバック: TELEGRAM_BOT_TOKEN=...（デフォルトアカウントのみ）。
3

ゲートウェイを起動し、最初の DM を承認

openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>
ペアリングコードは 1 時間で失効します。
4

ボットをグループに追加

ボットをグループに追加し、アクセスモデルに合わせて channels.telegram.groups と groupPolicy を設定します。
トークン解決順はアカウント対応です。実際には config の値が env フォールバックより優先され、TELEGRAM_BOT_TOKEN はデフォルトアカウントにのみ適用されます。

​
Telegram 側の設定

Telegram ボットはデフォルトで プライバシーモード が有効で、グループメッセージの受信が制限されます。ボットがすべてのグループメッセージを見る必要がある場合、次のいずれかを行います。
  • /setprivacy でプライバシーモードを無効化する、または
  • ボットをグループ管理者にする。
プライバシーモードを切り替えた場合は、各グループからボットを削除して再追加し、変更を適用させてください。
管理者ステータスは Telegram グループ設定で制御されます。管理者ボットはすべてのグループメッセージを受信できるため、常時有効なグループ動作に便利です。
  • /setjoingroups — グループ追加の許可／拒否
  • /setprivacy — グループ可視性の制御

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

channels.telegram.dmPolicy はダイレクトメッセージのアクセスを制御します。
  • pairing（デフォルト）
  • allowlist
  • open（allowFrom に "*" を含める必要あり）
  • disabled
channels.telegram.allowFrom は数値の Telegram ユーザー ID を受け付けます。telegram: / tg: プレフィックスも受け付けられ、正規化されます。 オンボーディングウィザードは @username 入力を受け付け、数値 ID に解決します。 以前の設定に @username の allowlist エントリが含まれている場合は、openclaw doctor --fix を実行して解決してください（ベストエフォート。Telegram ボットトークンが必要）。

​
Telegram ユーザー ID の確認方法

より安全（サードパーティ不要）:
  1. ボットに DM を送信。
  2. openclaw logs --follow を実行。
  3. from.id を確認。
公式 Bot API 方法:
curl "https://api.telegram.org/bot<bot_token>/getUpdates"
サードパーティ（プライバシー低）: @userinfobot または @getidsbot。

​
実行時の動作

  • Telegram は gateway プロセスによって管理されます。
  • ルーティングは決定的です。Telegram からの受信は Telegram に返信されます（モデルがチャンネルを選択することはありません）。
  • 受信メッセージは、返信メタデータとメディアプレースホルダーを含む共有チャンネルエンベロープに正規化されます。
  • グループセッションはグループ ID ごとに分離されます。フォーラムトピックでは :topic:<threadId> が付加され、トピックを分離します。
  • DM メッセージは message_thread_id を含む場合があり、OpenClaw はスレッド対応セッションキーでルーティングし、返信時に thread ID を保持します。
  • ロングポーリングは grammY runner を使用し、チャット／スレッド単位で順序制御されます。全体の同時実行数は agents.defaults.maxConcurrent を使用します。
  • Telegram Bot API は既読通知をサポートしません（sendReadReceipts は適用されません）。

​
機能リファレンス

OpenClaw は一時的な Telegram メッセージを送信し、テキスト到着に応じて編集することで部分返信をストリーミングできます。要件:
  • channels.telegram.streamMode が "off" ではない（デフォルト: "partial"）
モード:
  • off: ライブプレビューなし
  • partial: 部分テキストで頻繁に更新
  • block: channels.telegram.draftChunk を使用したチャンク更新
streamMode: "block" の draftChunk デフォルト:
  • minChars: 200
  • maxChars: 800
  • breakPreference: "paragraph"
maxChars は channels.telegram.textChunkLimit によって制限されます。これは DM とグループ／トピックで動作します。テキストのみの返信では、同じプレビューメッセージを保持し、最終的にその場で編集します（2 通目は送信されません）。複雑な返信（例: メディアを含む場合）は通常の最終配信にフォールバックし、その後プレビューメッセージを削除します。streamMode はブロックストリーミングとは別です。Telegram でブロックストリーミングが有効な場合、二重ストリーミングを避けるためプレビューはスキップされます。Telegram 専用推論ストリーム:
  • /reasoning stream は生成中に推論をライブプレビューへ送信
  • 最終回答は推論テキストなしで送信
More help: Channel troubleshooting.

​
関連