feat(channel): support telegram bot

2026-06-02 00:57:41 +08:00 · 2026-05-28 15:07:09 +08:00
parent d106465419
commit e3eacc77d7
11 changed files with 261 additions and 23 deletions
--- a/docs/ja/README.md
+++ b/docs/ja/README.md
@@ -30,7 +30,7 @@ CowAgent は軽量でデプロイしやすく、拡張性に優れています
 | [ナレッジベース](https://docs.cowagent.ai/ja/knowledge/index) | 構造化された知識を Markdown Wiki として自動整理し、進化し続けるナレッジグラフを可視化ブラウジング |
 | [Skill](https://docs.cowagent.ai/ja/skills/index) | [Skill Hub](https://skills.cowagent.ai/)、GitHub、ClawHub からワンクリックでインストール；対話によるカスタム Skill 作成にも対応 |
 | [ツール](https://docs.cowagent.ai/ja/tools/index) | ファイル I/O、ターミナル、ブラウザ、スケジューラ、記憶検索、Web 検索など 10+ の組み込みツール — MCP プロトコルに完全対応 |
-| [チャネル](https://docs.cowagent.ai/ja/channels/index) | 一つの Agent で Web、WeChat、Feishu、DingTalk、WeCom、QQ、公式アカウントを同時にサポート |
+| [チャネル](https://docs.cowagent.ai/ja/channels/index) | 一つの Agent で Web、WeChat、Feishu、DingTalk、WeCom、QQ、公式アカウント、Telegram を同時にサポート |
 | マルチモーダル | テキスト・画像・音声・ファイルをフルサポート — 認識・生成・双方向送受信 |
 | [モデル](https://docs.cowagent.ai/ja/models/index) | Claude、GPT、Gemini、DeepSeek、GLM、Qwen、Kimi、MiniMax、Doubao など、設定 1 行で切り替え可能 |
 | [デプロイ](https://docs.cowagent.ai/ja/guide/quick-start) | ワンラインインストーラー、統合された Web コンソール、複数のデプロイモード（ローカル / Docker / サーバー） |
@@ -126,6 +126,7 @@ CowAgent は主要な LLM プロバイダーすべてに対応しています。
 | [QQ](https://docs.cowagent.ai/ja/channels/qq) | ✅ | ✅ | ✅ | | ✅ |
 | [WeCom App](https://docs.cowagent.ai/ja/channels/wecom) | ✅ | ✅ | ✅ | ✅ | |
 | [WeChat 公式アカウント](https://docs.cowagent.ai/ja/channels/wechatmp) | ✅ | ✅ | | ✅ | |
+| [Telegram](https://docs.cowagent.ai/ja/channels/telegram) | ✅ | ✅ | ✅ | ✅ | ✅ |

 > Feishu と WeCom Bot は **Web コンソール内で QR コードをスキャンするだけで接続**できます — パブリック IP は不要です。詳細は [チャネル概要](https://docs.cowagent.ai/ja/channels/index) を参照してください。

--- a/docs/ja/channels/index.mdx
+++ b/docs/ja/channels/index.mdx
@@ -19,6 +19,7 @@ CowAgent は複数のチャットチャネルへの接続に対応しており
 | [QQ](/ja/channels/qq) | ✅ | ✅ | ✅ | | ✅ |
 | [WeCom アプリ](/ja/channels/wecom) | ✅ | ✅ | ✅ | ✅ | |
 | [WeChat 公式アカウント](/ja/channels/wechatmp) | ✅ | ✅ | | ✅ | |
+| [Telegram](/ja/channels/telegram) | ✅ | ✅ | ✅ | ✅ | ✅ |

 - **画像 / ファイル / 音声**列は対応するメッセージタイプの送受信に対応していることを示します。詳細は各チャネルのドキュメントを参照してください
 - **グループチャット**列はグループメッセージを認識して応答できることを示します
@@ -37,3 +38,4 @@ CowAgent は複数のチャットチャネルへの接続に対応しており
 - [QQ](/ja/channels/qq) — QQ 公式ボットオープンプラットフォーム
 - [WeCom アプリ](/ja/channels/wecom) — WeCom 自作アプリ接続
 - [WeChat 公式アカウント](/ja/channels/wechatmp) — WeChat 公式アカウント（購読アカウント / サービスアカウント）
+- [Telegram](/ja/channels/telegram) — グローバル IM、5 分で接続、公開 IP 不要
--- a/docs/ja/channels/telegram.mdx
+++ b/docs/ja/channels/telegram.mdx
@@ -0,0 +1,111 @@
+---
+title: Telegram
+description: Telegram Bot API 経由で CowAgent を接続
+---
+
+> 公式の Telegram Bot API を通じて CowAgent を接続します。1 対 1 チャットおよびグループチャット（@メンションまたはボットへの返信で起動）に対応。Long Polling 方式のため公開 IP は不要で、すぐに利用できます。
+
+
+## 1. 接続手順
+
+### ステップ 1: BotFather で Bot を作成
+
+1. Telegram で公式アカウント [@BotFather](https://t.me/BotFather) を開きます。
+2. `/newbot` を送り、案内に従って入力します:
+   - **Bot 名**（表示名、例: `My CowAgent Bot`）
+   - **Bot ユーザー名**（`bot` で終わる必要があります、例: `my_cowagent_bot`）
+3. 作成完了後、BotFather から **HTTP API Token**（例: `123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ`）が返されます。大切に保管してください。
+
+<Tip>
+  Token は Bot のパスワードに相当します。漏えいしないよう注意してください。万が一漏れた場合は `@BotFather` に `/revoke` を送って再発行できます。
+</Tip>
+
+### ステップ 2:（グループ利用時）Privacy Mode を無効化
+
+1 対 1 チャットのみ利用する場合はスキップ可能です。Telegram Bot は既定で **Privacy Mode** が有効で、グループ内では `@bot` 接尾辞付きのコマンド（例: `/start@your_bot`）と、Bot メッセージへの返信のみ受信できます。**通常の `@bot こんにちは` のようなテキストメッセージは届きません**。そのままだとグループで反応しないので、必要に応じて以下を設定してください。
+
+`@BotFather` に対して:
+
+1. `/setprivacy` を送信
+2. 作成した Bot を選択
+3. `Disable` を選択
+
+<Note>
+  設定後もグループで反応しない場合は、Bot を一度グループから外して再度追加してみてください。
+</Note>
+
+### ステップ 3: CowAgent に接続
+
+<Tabs>
+  <Tab title="Web コンソール（推奨）">
+    Web コンソール（既定 `http://127.0.0.1:9899`）を開き、**チャネル** メニュー → **チャネルを追加** → **Telegram** を選択し、Bot Token を貼り付けて接続をクリックします。
+  </Tab>
+  <Tab title="設定ファイル">
+    `config.json` に以下を追加して Cow を起動します:
+
+    ```json
+    {
+      "channel_type": "telegram",
+      "telegram_token": "123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ",
+      "telegram_group_trigger": "mention_or_reply"
+    }
+    ```
+
+    | パラメータ | 説明 | 既定値 |
+    | --- | --- | --- |
+    | `telegram_token` | BotFather から発行された HTTP API Token | - |
+    | `telegram_group_trigger` | グループのトリガー方式: `mention_or_reply`（@ または返信）/ `mention_only`（@ のみ）/ `all`（全メッセージ） | `mention_or_reply` |
+    | `telegram_register_commands` | 起動時に BotFather にコマンドメニューを登録するかどうか | `true` |
+  </Tab>
+</Tabs>
+
+ログに以下のような出力が表示されれば接続成功です:
+
+```
+[Telegram] Bot logged in as @my_cowagent_bot (id=123456789)
+[Telegram] Registered 10 bot commands
+[Telegram] ✅ Telegram bot ready, polling for updates
+```
+
+## 2. 機能
+
+| 機能 | 対応状況 |
+| --- | --- |
+| 1 対 1 チャット | ✅ |
+| グループチャット（@bot / Bot への返信） | ✅ |
+| テキストメッセージ | ✅ 送受信 |
+| 画像メッセージ | ✅ 送受信 |
+| 音声メッセージ | ✅ 送受信（OGG/Opus） |
+| 動画メッセージ | ✅ 送受信 |
+| ファイルメッセージ | ✅ 送受信（PDF / Word / Excel など） |
+| コマンドメニュー | ✅ Web コンソールの slash コマンドと一致 |
+
+### コマンドメニュー
+
+起動時に BotFather へコマンドメニューを自動登録します。Telegram の入力欄で `/` を入力するとサジェストが表示されます:
+
+| コマンド | 説明 |
+| --- | --- |
+| `/help` | コマンドヘルプを表示 |
+| `/status` | 実行ステータスを確認 |
+| `/context` | 対話コンテキストを表示（`/context clear` でクリア） |
+| `/skill` | スキル管理（`/skill list`、`/skill install` など） |
+| `/memory` | 記憶管理（`/memory dream`） |
+| `/knowledge` | ナレッジベース管理（`/knowledge list` / `on` / `off`） |
+| `/config` | 現在の設定を表示 |
+| `/cancel` | 実行中の Agent タスクを中断 |
+| `/logs` | 最近のログを表示 |
+| `/version` | バージョンを表示 |
+
+<Note>
+  Telegram のコマンドメニューはトップレベルのコマンドのみ表示されます。サブコマンドはスペース区切りで入力します（例: `/skill list`、`/context clear`）。
+</Note>
+
+## 3. 使い方
+
+接続が完了したら:
+
+- **1 対 1 チャット**: Telegram で Bot のユーザー名（例: `@my_cowagent_bot`）を検索し、`Start` をタップして会話を開始します。
+- **グループチャット**: Bot をグループに追加し、`@bot こんにちは` または **Bot のメッセージに返信** することで起動します。グループで反応しない場合は [ステップ 2](#ステップ-2-グループ利用時-privacy-mode-を無効化) の Privacy Mode 設定を確認してください。
+
+画像やファイルを送るときは、添付欄の上の入力欄に **キャプション**（説明・質問）を直接書いて一緒に送信できます。Bot は添付ファイルとキャプションを合わせて回答します。先に添付を送り、その後に質問を送る形でも、2 つのメッセージは自動でまとめて処理されます。