OpenClaw Skills | OpenClaw 拡張機能の最大のライブラリ

ステータス：本番環境で利用可能。grammY 経由でボットのDMとグループチャットをサポート。デフォルトでlong-pollingを使用。webhookもサポート。

Tutorial.step

初心者向けクイックセットアップ

1. ''@BotFather''でボットを作成（''リンク''）。ハンドルが''@BotFather''であることを確認し、ボットトークンをコピーします。

2. トークンを設定：

- Environment variable: ''TELEGRAM_BOT_TOKEN=...''

- または設定：''channels.telegram.botToken: "..."''。

- 両方を設定した場合、設定が優先（envはデフォルトアカウントのフォールバックのみ）。

3. Gatewayを起動。

4. DMはデフォルトでペアリング有効。最初の連絡でペアリングコードを受信し、承認後にメッセージを処理。

Minimum config:

Json5

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

Tutorial.step

これは何か

- Gatewayが管理するTelegram Bot APIチャンネル。

- 決定論的ルーティング：返信は常にTelegramに戻り、モデルはチャンネルを選択しない。

- DM uses agent's main session by default; group chats are isolated as ''agent:<agentId>:telegram:group:<chatId>''.

Tutorial.step

設定（クイックパス）

Tutorial.step

1）ボットトークンを作成（BotFather）

1. Telegramを開き、''@BotFather''とチャット（''リンク''）、ハンドルが''@BotFather''であることを確認。

2. ''/newbot''を実行し、プロンプトに従って完了（名前 + ''bot''で終わるユーザー名）。

3. トークンをコピーして安全に保管。

オプション設定：

- ''/setjoingroups'' — ボットのグループ参加を許可/禁止

- ''/setprivacy'' — ボットがすべてのグループメッセージを表示できるか制御

オプション設定：

- ''/setjoingroups'' — ボットのグループ参加を許可/禁止

- ''/setprivacy'' — ボットがすべてのグループメッセージを表示できるか制御

Tutorial.step

2）トークンを設定（envまたはconfig）

Example:

Json5

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

環境変数方式：''TELEGRAM_BOT_TOKEN=...''（デフォルトアカウントのみ）。envとconfigが両方存在する場合、configが優先。

マルチアカウント：''channels.telegram.accounts''を使用して各アカウントのトークンを設定（オプションの''name''）。共有構造は''/gateway/configuration''を参照。

3. Gatewayを起動：トークンが解析可能（設定優先、envフォールバック）になるとTelegramチャンネルが起動。

4. DMはデフォルトでペアリング：最初の連絡でペアリングコードを提供し、承認後にメッセージを処理。

5. グループチャット：ボットをグループに追加。BotFatherのprivacy/adminポリシーを決定（下記参照）。次に''channels.telegram.groups''を使用してメンションゲーティングと許可リストを制御。

Tutorial.step

Telegram側：トークン / プライバシー / 権限

Tutorial.step

トークン（BotFather）

- ''/newbot''はボットを作成し、トークンを返す（秘密にする）。

- 漏洩した場合、@BotFatherでトークンを取り消し/リセットし、設定を更新。

Tutorial.step

グループメッセージの可視性（プライバシーモード）

Telegramボットはデフォルトでプライバシーモードが有効で、受信できるグループメッセージの範囲が制限されます。ボットがグループ内のすべてのメッセージを表示する必要がある場合、2つの方法があります：

- ''/setprivacy''を使用してプライバシーモードを無効にする、''または''

- ボットをグループ管理者に設定（管理者ボットはすべてのメッセージを受信）。

注意： プライバシーモードを切り替えた後、設定を有効にするにはボットをグループから削除して再追加する必要があります。

Tutorial.step

グループ権限（管理者）

管理者権限はグループUIで設定。管理者ボットはすべてのグループメッセージを受信。「完全な可視性」が本当に必要な場合のみ実行。

Tutorial.step

How It Works (Behavior)

- 受信メッセージは汎用チャンネルエンベロープ（返信コンテキストとメディアプレースホルダーを含む）に正規化。

- グループチャットはデフォルトでメンションが必要（ネイティブ@メンションまたは''agents.list[].groupChat.mentionPatterns'' / ''messages.groupChat.mentionPatterns''の一致）。

- 複数のエージェントの場合、''agents.list[].groupChat.mentionPatterns''でエージェントごとのオーバーライドが可能。

- 返信は常にトリガーしたTelegramチャットに戻る。

- long-pollingはgrammYランナーを使用し、チャットごとに順次処理。全体の並行性は''agents.defaults.maxConcurrent''で制限。

- Telegram Bot APIには既読確認がないため、''sendReadReceipts''はない。

Tutorial.step

ドラフトストリーミング

OpenClawはTelegram DMで''sendMessageDraft''を使用して部分更新をストリーミング可能。

Requirements:

- @BotFatherでボットのスレッドモード（フォーラムトピックモード）を有効化。

- DMスレッドのみ（Telegramは受信メッセージに''message_thread_id''を含む）。

- ''channels.telegram.streamMode''が''"off"''ではない（デフォルト''"partial"''；''"block"''はチャンクドラフト更新を実行）。

ドラフトストリーミングはDMのみサポート。Telegramはグループ/チャンネルではこのメカニズムをサポートしない。

Tutorial.step

フォーマット（Telegram HTML）

- 送信Telegramテキストは''parse_mode: "HTML"''を使用（Telegramがサポートするタグのサブセット）。

- Markdown風入力はTelegramセーフHTMLとしてレンダリング（太字/斜体/取り消し線/コード/リンク）。ブロックレベル要素は改行/箇条書き付きテキストにフラット化。

- モデルからの生HTMLはTelegram解析エラーを回避するためにエスケープ。

- TelegramがHTMLペイロードを拒否した場合、OpenClawは同じメッセージをプレーンテキストで再試行。

Tutorial.step

コマンド（ネイティブ + カスタム）

OpenClawは起動時にTelegramボットメニューにネイティブコマンドを登録（''/status''、''/reset''、''/model''など）。

設定を通じてカスタムコマンドをメニューに追加可能：

Notes:

- カスタムコマンドはメニューエントリのみ。別の場所で処理しない限り、OpenClawは自動的に実装しない。

- コマンド名は正規化（先頭の''/''を削除、小文字）され、''a-z''、''0-9''、''_''のみ含む（長さ1–32）。

- カスタムコマンドはネイティブコマンドを上書きできない。競合項目は無視され、ログに記録。

- ''commands.native''を無効にした場合、カスタムコマンドのみ登録（カスタムコマンドがない場合はメニューをクリア）。

Tutorial.step

トラブルシューティング

- ログに''setMyCommands failed''が表示される場合、通常''api.telegram.org''へのHTTPS/DNS送信がブロックされていることを意味。

- ''sendMessage''または''sendChatAction''の失敗が表示される場合、IPv6ルーティングとDNSの確認を優先。

More: ''/channels/troubleshooting''.

Tutorial.step

Limits

- 送信テキストは''channels.telegram.textChunkLimit''で分割（デフォルト4000）。

- オプションで空行で優先分割：''channels.telegram.chunkMode="newline"''（段落境界）で長さで分割。

- メディアダウンロード/アップロード上限：''channels.telegram.mediaMaxMb''（デフォルト5MB）。

- Telegram Bot APIリクエストタイムアウト：''channels.telegram.timeoutSeconds''（デフォルト500、grammY）。長時間のハングを回避するために小さく設定を推奨。

- グループ履歴コンテキスト：''channels.telegram.historyLimit''（または''channels.telegram.accounts.*.historyLimit''）、''messages.groupChat.historyLimit''にフォールバック。''0''に設定で無効（デフォルト50）。

- DM履歴上限：''channels.telegram.dmHistoryLimit''（ユーザーターンで計算）。ユーザーごとにオーバーライド：''channels.telegram.dms["''"].historyLimit''。

Tutorial.step

グループチャットトリガーモード

デフォルトでは、ボットはメンションされた場合のみグループで返信（''@botname''または''agents.list[].groupChat.mentionPatterns''の一致）。動作を調整するには：

Tutorial.step

Via Config (Recommended)

Json5

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": { requireMention: false }, // This group always responds
      },
    },
  },
}

''重要：'' ''channels.telegram.groups''を設定すると、''グループ許可リスト''になります：リストされたグループ（または''"*"''）のみが受け入れられます。

フォーラムトピックはデフォルトで親グループ設定（allowFrom、requireMention、skills、prompts）を継承。''channels.telegram.groups.''.topics.''''にトピックレベルのオーバーライドを書かない限り。

すべてのグループを許可し、常に返信：

Json5

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

すべてのグループでメンションを要求（デフォルトの動作）：

Json5

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: true }, // Or omit groups entirely
      },
    },
  },
}

Tutorial.step

コマンド経由（現在のセッションのみ）

グループで送信：

- ''/activation always'' — すべてのメッセージに返信

- ''/activation mention'' — メンションが必要（デフォルト）

注意：このコマンドはセッション状態のみを変更。再起動後に動作を維持するには、設定を使用。

Tutorial.step

グループチャットIDを取得

グループの任意のメッセージを''@userinfobot''または''@getidsbot''に転送してチャットIDを確認（通常''-1001234567890''のような負の数）。

プライバシー注意：''@userinfobot''はサードパーティボット。サードパーティを使用したくない場合、ボットをグループに追加し、メッセージを送信してから''openclaw logs --follow''を使用して''chat.id''を読み取るか、Bot APIの''getUpdates''を使用。

Tutorial.step

設定書き込み（Config writes）

デフォルトでは、Telegramはチャンネルイベントまたは''/config set|unset''によってトリガーされた設定更新を設定ファイルに書き戻すことを許可。

典型的なシナリオ：

- グループがスーパーグループにアップグレードされ、Telegramが''migrate_to_chat_id''を発行（チャットIDが変更）。OpenClawは''channels.telegram.groups''を自動的に移行可能。

- Telegramチャットで''/config set''または''/config unset''を実行（''commands.config: true''が必要）。

Disable:

Json5

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

Tutorial.step

トピック（フォーラムスーパーグループ）

Telegramフォーラムトピックは各メッセージに''message_thread_id''を含む。OpenClawは：

Tutorial.step

インラインボタン

Telegramはインラインキーボード（コールバックボタン）をサポート。

Json5

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

アカウントごとの設定：

Json5

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

スコープ：

- ''off'' — disabled

- ''dm'' — DMのみ（グループターゲットはブロック）

- ''group'' — グループのみ（DMターゲットはブロック）

- ''all'' — DM + グループ

- ''allowlist'' — DM + グループ、''allowFrom''/''groupAllowFrom''で許可された送信者のみ許可（制御コマンドと一貫）

デフォルト：''allowlist''。古い構文：''capabilities: ["inlineButtons"]''は''inlineButtons: "all"''と同等。

Tutorial.step

ボタンを送信

メッセージツールを使用して''buttons''パラメータを渡す：

Json5

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

ユーザーがボタンをクリックすると、コールバックデータはメッセージとしてエージェントに送り返されます：

''callback_data: value''

Tutorial.step

Config Hierarchy

Telegram機能は2つのレベルで設定可能（上記の例はオブジェクト形式。古い文字列配列もまだサポート）：

- ''channels.telegram.capabilities''：グローバルデフォルト、すべてのTelegramアカウントに適用（オーバーライドされない限り）

- ''channels.telegram.accounts.''.capabilities''：アカウントごとのオーバーライド

Tutorial.step

アクセス制御（DM + グループ）

Tutorial.step

DMアクセス

- デフォルト：''channels.telegram.dmPolicy = "pairing"''。不明な送信者はペアリングコードを受信。承認後に処理（1時間有効期限）。

- Approve:

- ''openclaw pairing list telegram''

- ''openclaw pairing approve telegram ''''

- ペアリングはTelegram DMのデフォルトトークンエクスチェンジ。詳細は''Pairing''を参照。

- ''channels.telegram.allowFrom''は数値ユーザーIDの使用を推奨、''@username''もサポート。ボットのユーザー名ではなく、人間の送信者のIDを指す。ウィザードは可能な場合''@username''を数値IDに解決。

#

Tutorial.stepTelegramユーザーIDを取得する方法

より安全（サードパーティボットに依存しない）：

1. gatewayを起動し、ボットにDMを送信。

2. ''openclaw logs --follow''を実行し、''from.id''を見つける。

公式Bot API（より直接的）：

1. ボットにDMを送信。

2. トークンを使用して''getUpdates''を呼び出し、''message.from.id''を読み取る：

''''`bash", "p8": "curl "https://api.telegram.org/bot''/getUpdates"", "p9": "''''`

curl "https://api.telegram.org/bot''/getUpdates"

''''`

サードパーティ（プライバシーが低い）：

- ''@userinfobot''または''@getidsbot''にDM。

#

Tutorial.stepグループアクセス

グループチャットには2つの独立した制御があります：

''1）どのグループを許可するか''（''channels.telegram.groups''をグループ許可リストとして）：

- ''groups''を書かない：すべてのグループを許可

- ''groups''を書く：リストされたグループまたは''"*"''のみ許可

- 例："groups": { "-1001234567890": {'}, "*": {'} }'はすべてのグループを許可（特定のグループにオーバーライドを書きながら）を意味

''2）どの送信者を許可するか''（''channels.telegram.groupPolicy''がグループ送信者フィルタリングを制御）：

- ''"open"''：グループ内のすべての送信者を許可

- ''"allowlist"''：''channels.telegram.groupAllowFrom''の送信者のみ許可

- ''"disabled"''：グループメッセージを完全に拒否

デフォルトは''groupPolicy: "allowlist"''（''groupAllowFrom''を設定しない場合、デフォルトでブロック）

ほとんどのユーザーは：''groupPolicy: "allowlist"'' + ''groupAllowFrom'' + ''channels.telegram.groups''に許可されたグループをリストアップ。

Tutorial.stepLong-pollingとWebhook

- デフォルト：long-polling（公開URL不要）。

- Webhook：''channels.telegram.webhookUrl''と''channels.telegram.webhookSecret''を設定（オプションの''channels.telegram.webhookPath''）。

- ローカルリスンはデフォルトで''0.0.0.0:8787''にバインド、デフォルトパス''POST /telegram-webhook''。

- 公開URLが異なる場合、リバースプロキシを使用し、''channels.telegram.webhookUrl''を公開エンドポイントにポイント。

Tutorial.step返信スレッド化（Reply threading）

Telegramはオプションの「トリガーメッセージに返信」機能をサポート（タグに基づく）：

- ''[[reply_to_current]]'' — トリガーメッセージに返信

- ''[[reply_to:'']]'' — 指定されたメッセージIDに返信

''channels.telegram.replyToMode''で制御：

- ''first''（デフォルト）、''all''、''off''。

Tutorial.stepオーディオメッセージ（ボイスノート vs オーディオファイル）

Telegramはボイスノート（丸いバブル）とオーディオファイル（メタデータカード付き）を区別。古い動作との互換性のため、OpenClawはデフォルトでオーディオファイルを送信。

エージェントの返信でボイスノートを強制的に送信するには、返信の任意の場所に追加：

- ''[[audio_as_voice]]'' — オーディオをボイスノートとして送信

このタグは最終的に配信されるテキストには表示されません。他のチャンネルは無視します。

メッセージツールを使用してボイスノートを送信：''asVoice: true''を設定し、ボイス互換のオーディオ''media''URLを提供（''message''は省略可能）：

Json5

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  media: "https://example.com/voice.ogg",
  asVoice: true,
}