• /setprivacy で privacy mode を無効にする
• bot をグループ管理者にする

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

• ダイレクトチャット: プレビューメッセージ + editMessageText
• グループ/トピック: プレビューメッセージ + editMessageText

• channels.telegram.streaming は off | partial | block | progress です（デフォルト: partial）
• progress は Telegram では partial にマップされます（チャネル横断の命名互換性のため）
• レガシーな channels.telegram.streamMode と boolean の streaming 値は自動マッピングされます

• DM: OpenClaw は同じプレビューメッセージを保持し、最後にその場で編集します（2 通目のメッセージは送信しません）
• グループ/トピック: OpenClaw は同じプレビューメッセージを保持し、最後にその場で編集します（2 通目のメッセージは送信しません）

• /reasoning stream は、生成中の reasoning をライブプレビューに送信します
• 最終回答は reasoning テキストなしで送信されます

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

• commands.native: "auto" は Telegram のネイティブコマンドを有効にします

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

• 名前は正規化されます（先頭の / を削除し、小文字化）
• 有効パターン: a-z、0-9、_、長さ 1..32
• カスタムコマンドはネイティブコマンドを上書きできません
• 競合/重複はスキップされ、ログに記録されます

• カスタムコマンドはメニュー項目のみです。動作は自動実装されません
• Telegram メニューに表示されなくても、plugin/skill コマンドは手入力で動作できます

• setMyCommands failed で BOT_COMMANDS_TOO_MUCH が出る場合、削減後でも Telegram メニューが多すぎることを意味します。plugin/skill/custom コマンドを減らすか、channels.telegram.commands.native を無効にしてください。
• setMyCommands failed で network/fetch エラーが出る場合、通常は api.telegram.org への outbound DNS/HTTPS がブロックされています。

​

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

1. /pair でセットアップコードを生成します
2. iOS アプリにコードを貼り付けます
3. /pair pending で保留中リクエストを一覧表示します（role/scopes を含む）
4. リクエストを承認します:
   • 明示的に承認するには /pair approve <requestId>
   • 保留中リクエストが 1 件だけなら /pair approve
   • 最新のものなら /pair approve latest

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

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

• off
• dm
• group
• all
• 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" }],
  ],
}

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

• channels.telegram.actions.sendMessage
• channels.telegram.actions.deleteMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker（デフォルト: 無効）

• [[reply_to_current]] は起動元メッセージに返信します
• [[reply_to:<id>]] は特定の Telegram message ID に返信します

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

• トピックのセッションキーに :topic:<threadId> が追加されます
• 返信と typing はそのトピック thread を対象にします
• トピック config パス: channels.telegram.groups.<chatId>.topics.<threadId>

• メッセージ送信では message_thread_id を省略します（Telegram は sendMessage(...thread_id=1) を拒否します）
• typing アクションでは引き続き message_thread_id を含めます

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

• type: "acp" と match.channel: "telegram" を持つ bindings[]

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

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

• MessageThreadId
• IsForum

• message_thread_id を持つプライベートチャットでは、DM ルーティングを維持しつつ、thread 認識型の session key / reply target を使います。

​

音声メッセージ

• デフォルト: 音声ファイルとしての挙動
• エージェント返信に [[audio_as_voice]] タグを付けると、ボイスノート送信を強制

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

​

ステッカー

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

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

• ~/.openclaw/telegram/sticker-cache.json

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

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

{
  action: "sticker-search",
  channel: "telegram",
  query: "cat waving",
  limit: 5,
}

• 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 はリアクション更新に thread ID を含めません。
  • forum でないグループではグループ chat session にルーティングされます
  • forum グループでは、正確な元トピックではなく、グループ一般トピック session（:topic:1）にルーティングされます

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

• Telegram は unicode 絵文字を期待します（たとえば "👀"）。
• チャネルまたはアカウントでリアクションを無効にするには "" を使ってください。

• channels.telegram.groups を更新するためのグループ migration イベント（migrate_to_chat_id）
• /config set と /config unset（コマンド有効化が必要）

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

• channels.telegram.webhookUrl を設定
• channels.telegram.webhookSecret を設定（webhook URL を設定した場合は必須）
• 任意で channels.telegram.webhookPath（デフォルト /telegram-webhook）
• 任意で channels.telegram.webhookHost（デフォルト 127.0.0.1）
• 任意で channels.telegram.webhookPort（デフォルト 8787）

• channels.telegram.textChunkLimit のデフォルトは 4000 です。
• channels.telegram.chunkMode="newline" は、長さ分割の前に段落境界（空行）を優先します。
• channels.telegram.mediaMaxMb（デフォルト 100）は、受信・送信両方の Telegram メディアサイズ上限です。
• channels.telegram.timeoutSeconds は Telegram API クライアントのタイムアウトを上書きします（未設定時は grammY デフォルト）。
• グループコンテキスト履歴は channels.telegram.historyLimit または messages.groupChat.historyLimit（デフォルト 50）を使います。0 で無効化します。
• reply/quote/forward の補助コンテキストは、現在は受信したまま渡されます。
• Telegram の allowlist は主に誰がエージェントを起動できるかを制御するものであり、補助コンテキスト全体のマスキング境界ではありません。
• DM 履歴制御:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• channels.telegram.retry config は、回復可能な outbound API エラーに対する Telegram 送信ヘルパー（CLI/tools/actions）に適用されます。

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

• --poll-duration-seconds（5-600）
• --poll-anonymous
• --poll-public
• forum topic 用の --thread-id（または :topic: ターゲットを使用）

• channels.telegram.capabilities.inlineButtons が許可している場合の、インラインキーボード用 --buttons
• 送信画像や GIF を圧縮された写真やアニメーションメディアアップロードではなく document として送る --force-document

• channels.telegram.actions.sendMessage=false は、poll を含む outbound Telegram メッセージを無効化します
• channels.telegram.actions.poll=false は、通常送信は有効のまま Telegram poll 作成を無効化します

• channels.telegram.execApprovals.enabled
• channels.telegram.execApprovals.approvers（任意。可能な場合は allowFrom とダイレクトメッセージの defaultTo から推測される数値 owner ID にフォールバック）
• channels.telegram.execApprovals.target（dm | channel | both、デフォルト: dm）
• agentFilter、sessionFilter

• target: "dm" は、解決された approver DM にのみ承認プロンプトを送信します
• target: "channel" は、元の Telegram chat/topic にプロンプトを送り返します
• target: "both" は、approver DM と元の chat/topic の両方に送信します

• plugin: で始まる承認 ID は常に plugin 承認を通じて解決されます。
• それ以外の承認 ID は最初に exec.approval.resolve を試します。
• Telegram も plugin 承認用に認可されており、かつ Gateway が exec 承認を unknown/expired と返した場合、Telegram は plugin.approval.resolve で 1 回だけ再試行します。
• 実際の exec 承認拒否/エラーは、黙って plugin 承認解決にフォールスルーしません。

• requireMention=false の場合、Telegram privacy mode が完全可視性を許可している必要があります。
  • BotFather: /setprivacy -> Disable
  • その後、グループから bot を削除して再追加
• openclaw channels status は、config がメンションなしのグループメッセージを想定している場合に警告します。
• openclaw channels status --probe は明示的な数値グループ ID を確認できます。ワイルドカード "*" は membership probe できません。
• 手早いセッションテスト: /activation always。

• channels.telegram.groups が存在する場合、グループはそこに列挙されている必要があります（または "*" を含める）
• グループ内の bot メンバーシップを確認
• スキップ理由は openclaw logs --follow でログを確認

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

• Node 22+ とカスタム fetch/proxy の組み合わせでは、AbortSignal 型の不一致により即時 abort 挙動が発生することがあります。
• 一部ホストでは api.telegram.org がまず IPv6 に解決され、IPv6 outbound が壊れていると Telegram API 障害が断続的に発生することがあります。
• ログに TypeError: fetch failed または Network request for 'getUpdates' failed! が含まれている場合、OpenClaw は現在これらを回復可能なネットワークエラーとして再試行します。
• 直接 outbound/TLS が不安定な VPS ホストでは、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

• RFC 2544 の benchmark-range 応答（198.18.0.0/15）は、Telegram メディアダウンロードでデフォルト許可されています。信頼できる fake-IP または transparent proxy がメディアダウンロード中に api.telegram.org を別の private/internal/special-use アドレスへ書き換える場合は、Telegram 専用バイパスを opt-in できます:

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• 同じ opt-in はアカウントごとにも利用できます: channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork。
• proxy が Telegram メディアホストを 198.18.x.x に解決する場合は、まず dangerous フラグをオフのままにしてください。Telegram メディアは RFC 2544 benchmark range をすでにデフォルト許可しています。

• 一時的な環境変数上書き:
  • 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