Telegram（Bot API）

Telegram Botはデフォルトで**プライバシーモード**が有効であり、受信できるグループメッセージが制限されます。

Botがすべてのグループメッセージを見る必要がある場合は以下のいずれかを行ってください：

- `/setprivacy`でプライバシーモードを無効化、または
- Botをグループ管理者にする

プライバシーモードを切り替えた後、変更を適用するために各グループでBotを削除してから再追加してください。

管理者ステータスはTelegramのグループ設定で制御されます。

管理者Botはすべてのグループメッセージを受信するため、常時応答のグループ動作に有用です。

- `/setjoingroups`：グループ追加の許可/拒否
- `/setprivacy`：グループ可視性の動作

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

- `channels.telegram.streaming`：`off | partial | block | progress`（デフォルト：`partial`）
- `progress`はTelegramでは`partial`にマッピング

テキストのみの返信では、OpenClawは同じプレビューメッセージを保持し最終編集をインプレースで行います（2番目のメッセージなし）。

メディアペイロードを含む返信では、通常の最終配信にフォールバックしてプレビューメッセージをクリーンアップします。

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

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

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

Telegramコマンドメニュー登録は起動時に`setMyCommands`で処理されます。

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

カスタムコマンドメニューエントリの追加：

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

ルール：名前は正規化されます（先頭の`/`を除去、小文字化）。パターン：`a-z`、`0-9`、`_`、長さ`1..32`。カスタムコマンドはネイティブコマンドをオーバーライドできません。

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

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

コールバッククリックはテキストとしてAgentに渡されます：`callback_data: <value>`

フォーラムスーパーグループ：

- トピックセッションキーに`:topic:<threadId>`が追加される
- 返信とタイピングはトピックスレッドをターゲット
- トピック設定パス：`channels.telegram.groups.<chatId>.topics.<threadId>`

トピック継承：トピックエントリは`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`をオーバーライドしない限りグループ設定を継承します。

**トピックごとのAgentルーティング**：各トピックに`agentId`を設定することで異なるAgentにルーティングできます。

```json5
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },
            "3": { agentId: "zu" },
            "5": { agentId: "coder" }
          }
        }
      }
    }
  }
}
```

Telegramはボイスノートと音声ファイルを区別します。デフォルトは音声ファイル動作です。Agent返信で`[[audio_as_voice]]`タグを使用するとボイスノートとして送信されます。

受信スタンプの処理：静的WEBPはダウンロードして処理されます。アニメーションTGSとビデオWEBMはスキップされます。

スタンプアクションの有効化：`channels.telegram.actions.sticker: true`

Telegramリアクションは`message_reaction`更新として到着します。

設定：

- `channels.telegram.reactionNotifications`：`off | own | all`（デフォルト：`own`）
- `channels.telegram.reactionLevel`：`off | ack | minimal | extensive`（デフォルト：`minimal`）

`own`はBot送信メッセージへのユーザーリアクションのみ（送信済みメッセージキャッシュベースのベストエフォート）。

`ackReaction`はOpenClawが受信メッセージを処理中に確認用の絵文字を送信します。

解決順序：

- `channels.telegram.accounts.<accountId>.ackReaction`
- `channels.telegram.ackReaction`
- `messages.ackReaction`
- Agent IDの絵文字フォールバック

Telegramはユニコード絵文字を使用します（例："eyes"）。`""`で無効化できます。

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

Webhookモード：

- `channels.telegram.webhookUrl`を設定
- `channels.telegram.webhookSecret`（webhookUrl設定時は必須）
- オプション：`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.retry`設定はTelegram送信ヘルパーに適用

CLIの送信ターゲットは数値チャットIDまたはユーザー名：

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

Telegramは承認者DMでの実行承認をサポートし、オプションで元のチャットやトピックに承認プロンプトを投稿できます。

設定パス：

- `channels.telegram.execApprovals.enabled`
- `channels.telegram.execApprovals.approvers`
- `channels.telegram.execApprovals.target`（`dm` | `channel` | `both`、デフォルト：`dm`）

承認者は数値のTelegramユーザーIDである必要があります。

関連ドキュメント：[実行承認](/docs/tools/exec-approvals)

- `requireMention=false`の場合、Telegramのプライバシーモードで完全な可視性が必要です
  - BotFather：`/setprivacy` → Disable
  - その後グループからBotを削除して再追加
- クイックセッションテスト：`/activation always`

- `channels.telegram.groups`が存在する場合、グループがリストされている必要あり（または`"*"`を含む）
- グループ内のBotメンバーシップを確認
- ログを確認：`openclaw logs --follow`でスキップ理由を確認

- 送信者IDを認証（ペアリングおよび/または数値`allowFrom`）
- グループポリシーが`open`でもコマンド認可は引き続き適用
- `setMyCommands failed`と`BOT_COMMANDS_TOO_MUCH`の場合はネイティブメニューのエントリ数を削減

- 一部のホストは`api.telegram.org`をIPv6で先に解決します。IPv6送信が壊れている場合、断続的なTelegram APIエラーが発生する可能性があります
- VPSホストでは`channels.telegram.proxy`でTelegram APIコールをプロキシ経由でルーティングしてください：

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