feat(channel): add Discord channel

2026-06-02 00:57:41 +08:00 · 2026-05-30 18:20:27 +08:00
parent 54a20bca92
commit c5b8e06891
18 changed files with 1055 additions and 186 deletions
--- a/docs/channels/discord.mdx
+++ b/docs/channels/discord.mdx
@@ -0,0 +1,93 @@
+---
+title: Discord
+description: 将 CowAgent 接入 Discord Bot
+---
+
+> 通过 Discord Bot 的 **Gateway 长连接** 接入 CowAgent，支持私聊（DM）与服务器频道（@机器人 / 回复机器人触发）。Gateway 基于 WebSocket 长连接，无需公网 IP 与回调地址，开箱即用。
+
+## 一、接入步骤
+
+### 步骤一：创建 Discord 应用与 Bot
+
+1. 打开 [Discord 开发者后台](https://discord.com/developers/applications)，点击 **New Application**，填写名称（如 `CowAgent`）并创建。
+2. 左侧菜单进入 **Bot** 页面，点击 **Reset Token** 生成 Bot Token，复制并妥善保存（仅显示一次）。
+
+<Tip>
+  这个 Token 等同于 Bot 的密码，请勿泄露。若意外泄漏，在 Bot 页面再次点击 **Reset Token** 重置即可。
+</Tip>
+
+### 步骤二：开启 Message Content Intent
+
+私聊与频道读取文本均依赖该权限。
+
+1. 在 **Bot** 页面下方找到 **Privileged Gateway Intents**。
+2. 打开 **Message Content Intent** 开关并保存。
+
+<Note>
+  未开启该开关时，机器人收到的消息内容会为空，导致无响应。
+</Note>
+
+### 步骤三：邀请 Bot 进入服务器
+
+1. 左侧菜单进入 **OAuth2 → URL Generator**。
+2. **Scopes** 勾选 `bot`。
+3. **Bot Permissions** 至少勾选：`Send Messages`、`Read Message History`、`Attach Files`、`View Channels`。
+4. 复制底部生成的授权链接，在浏览器打开，选择目标服务器完成授权。
+
+<Note>
+  仅需私聊（DM）可跳过此步，但仍需先在任意共同服务器中与机器人建立 DM 通道，或由用户主动私聊机器人。
+</Note>
+
+### 步骤四：接入 CowAgent
+
+<Tabs>
+  <Tab title="Web 控制台（推荐）">
+    打开 Web 控制台（本地链接：http://127.0.0.1:9899 ），选择 **通道** 菜单，点击 **接入通道**，选择 **Discord**，填入 Bot Token，点击接入即可。
+  </Tab>
+  <Tab title="配置文件">
+    在 `config.json` 中添加以下配置后启动：
+
+    ```json
+    {
+      "channel_type": "discord",
+      "discord_token": "your-discord-bot-token",
+      "discord_group_trigger": "mention_or_reply"
+    }
+    ```
+
+    | 参数 | 说明 | 默认值 |
+    | --- | --- | --- |
+    | `discord_token` | 开发者后台 Bot 页面生成的 Bot Token | - |
+    | `discord_group_trigger` | 频道触发方式：`mention_or_reply`（@或回复机器人）/ `mention_only`（仅@） / `all`（所有消息） | `mention_or_reply` |
+  </Tab>
+</Tabs>
+
+启动 Cow 后，日志中出现以下输出即表示接入成功：
+
+```
+[Discord] Bot logged in as CowAgent#1234 (id=123456789)
+[Discord] ✅ Discord bot ready, listening for messages
+```
+
+## 二、功能说明
+
+| 功能 | 支持情况 |
+| --- | --- |
+| 私聊（DM） | ✅ |
+| 服务器频道（@机器人 / 回复机器人） | ✅ |
+| 文本消息 | ✅ 收发 |
+| 图片消息 | ✅ 收发 |
+| 文件消息 | ✅ 收发（PDF / Word / Excel 等） |
+
+<Note>
+  Discord 单条消息上限为 2000 字符，超长回复会自动按换行拆分为多条发送。
+</Note>
+
+## 三、使用
+
+完成接入后：
+
+- **私聊（DM）**：在服务器成员列表中找到你的机器人，点击头像直接发消息对话。
+- **频道**：在已邀请机器人的频道中，使用 `@你的机器人 你好` 或 **回复机器人的某条消息** 触发对话。
+
+发送图片或文件时，可以在附件的输入框中 **添加文字说明**（描述/问题）一并发送，机器人会结合附件回答。也支持先发附件再发问题，两条消息会自动合并提问。
--- a/docs/channels/index.mdx
+++ b/docs/channels/index.mdx
@@ -21,6 +21,7 @@ CowAgent 支持接入多种聊天通道，启动时通过 `channel_type` 切换
 | [公众号](/channels/wechatmp) | ✅ | ✅ | | ✅ | |
 | [Telegram](/channels/telegram) | ✅ | ✅ | ✅ | ✅ | ✅ |
 | [Slack](/channels/slack) | ✅ | ✅ | ✅ | | ✅ |
+| [Discord](/channels/discord) | ✅ | ✅ | ✅ | | ✅ |

 - **图片 / 文件 / 语音**列表示通道支持收发对应消息类型，具体细节详见各通道文档
 - **群聊**列指可识别并响应群消息
@@ -41,3 +42,4 @@ CowAgent 支持接入多种聊天通道，启动时通过 `channel_type` 切换
 - [公众号](/channels/wechatmp) — 微信公众号（订阅号 / 服务号）
 - [Telegram](/channels/telegram) — 海外 IM，5 分钟接入，无需公网 IP
 - [Slack](/channels/slack) — 团队协作 IM，Socket Mode 接入，无需公网 IP
+- [Discord](/channels/discord) — 社区 IM，Gateway 长连接接入，无需公网 IP
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -199,7 +199,8 @@
                  "channels/wechat-kf",
                  "channels/wechatmp",
                  "channels/telegram",
-                  "channels/slack"
+                  "channels/slack",
+                  "channels/discord"
                ]
              }
            ]
@@ -398,6 +399,7 @@
                  "en/channels/web",
                  "en/channels/telegram",
                  "en/channels/slack",
+                  "en/channels/discord",
                  "en/channels/weixin",
                  "en/channels/feishu",
                  "en/channels/dingtalk",
@@ -611,7 +613,8 @@
                  "ja/channels/wechat-kf",
                  "ja/channels/wechatmp",
                  "ja/channels/telegram",
-                  "ja/channels/slack"
+                  "ja/channels/slack",
+                  "ja/channels/discord"
                ]
              }
            ]
--- a/docs/en/channels/discord.mdx
+++ b/docs/en/channels/discord.mdx
@@ -0,0 +1,93 @@
+---
+title: Discord
+description: Integrate CowAgent with a Discord Bot
+---
+
+> Integrate CowAgent into Discord via a Discord Bot using the **Gateway** (persistent WebSocket). Supports direct messages (DM) and server channels (triggered by @mention or replying to the bot). The Gateway uses a persistent WebSocket connection — no public IP or callback URL required, works out of the box.
+
+## 1. Setup
+
+### Step 1: Create a Discord Application and Bot
+
+1. Open the [Discord Developer Portal](https://discord.com/developers/applications), click **New Application**, enter a name (e.g. `CowAgent`), and create it.
+2. Go to the **Bot** page in the left sidebar, click **Reset Token** to generate a Bot Token, then copy and store it safely (shown only once).
+
+<Tip>
+  This token is your bot's password — keep it secret. If it leaks, click **Reset Token** again on the Bot page to regenerate it.
+</Tip>
+
+### Step 2: Enable the Message Content Intent
+
+Reading message text in both DMs and channels depends on this privileged intent.
+
+1. On the **Bot** page, find **Privileged Gateway Intents**.
+2. Turn on **Message Content Intent** and save.
+
+<Note>
+  Without this intent enabled, incoming message content will be empty and the bot will not respond.
+</Note>
+
+### Step 3: Invite the Bot to a Server
+
+1. Go to **OAuth2 → URL Generator** in the left sidebar.
+2. Under **Scopes**, check `bot`.
+3. Under **Bot Permissions**, check at least: `Send Messages`, `Read Message History`, `Attach Files`, `View Channels`.
+4. Copy the generated authorization URL at the bottom, open it in a browser, and authorize it for your target server.
+
+<Note>
+  You can skip this step if you only need DMs, but you still need a DM channel with the bot (e.g. the user messages the bot directly).
+</Note>
+
+### Step 4: Connect to CowAgent
+
+<Tabs>
+  <Tab title="Web Console (Recommended)">
+    Open the Web Console (default `http://127.0.0.1:9899`), go to **Channels**, click **Add Channel**, choose **Discord**, paste the Bot Token, and click connect.
+  </Tab>
+  <Tab title="Config File">
+    Add the following to `config.json` and start Cow:
+
+    ```json
+    {
+      "channel_type": "discord",
+      "discord_token": "your-discord-bot-token",
+      "discord_group_trigger": "mention_or_reply"
+    }
+    ```
+
+    | Key | Description | Default |
+    | --- | --- | --- |
+    | `discord_token` | Bot Token generated on the Bot page of the Developer Portal | - |
+    | `discord_group_trigger` | Channel trigger: `mention_or_reply` (@ or reply to bot) / `mention_only` (@ only) / `all` (all messages) | `mention_or_reply` |
+  </Tab>
+</Tabs>
+
+The integration is ready when you see logs like:
+
+```
+[Discord] Bot logged in as CowAgent#1234 (id=123456789)
+[Discord] ✅ Discord bot ready, listening for messages
+```
+
+## 2. Capabilities
+
+| Feature | Support |
+| --- | --- |
+| Direct message (DM) | ✅ |
+| Server channel (@bot / reply to bot) | ✅ |
+| Text messages | ✅ send / receive |
+| Image messages | ✅ send / receive |
+| File messages | ✅ send / receive (PDF / Word / Excel, etc.) |
+
+<Note>
+  A single Discord message is capped at 2000 characters; long replies are automatically split across multiple messages by line breaks.
+</Note>
+
+## 3. Usage
+
+Once connected:
+
+- **Direct message (DM)**: find your bot in the server member list, click its avatar, and message it directly.
+- **Channel**: in a channel where the bot is invited, trigger it with `@your-bot hello` or by **replying to one of the bot's messages**.
+
+When sending an image or file, you can **add a text caption** (description / question) in the attachment input — the bot will answer based on both. Sending an attachment first and then a follow-up question also works; the two messages are merged automatically.
--- a/docs/en/channels/index.mdx
+++ b/docs/en/channels/index.mdx
@@ -21,6 +21,7 @@ The table below summarizes the inbound message types, bot reply types, and group
 | [Official Account](/en/channels/wechatmp) | ✅ | ✅ | | ✅ | |
 | [Telegram](/en/channels/telegram) | ✅ | ✅ | ✅ | ✅ | ✅ |
 | [Slack](/en/channels/slack) | ✅ | ✅ | ✅ | | ✅ |
+| [Discord](/en/channels/discord) | ✅ | ✅ | ✅ | | ✅ |

 - The **Image / File / Voice** columns indicate that the channel can send and receive the corresponding message types; see each channel's docs for details
 - The **Group Chat** column indicates the ability to recognize and respond to group messages
@@ -41,3 +42,4 @@ The table below summarizes the inbound message types, bot reply types, and group
 - [Official Account](/en/channels/wechatmp) — WeChat Official Account (subscription / service)
 - [Telegram](/en/channels/telegram) — global IM, 5-minute setup, no public IP needed
 - [Slack](/en/channels/slack) — team collaboration IM, Socket Mode integration, no public IP needed
+- [Discord](/en/channels/discord) — community IM, Gateway connection, no public IP needed
--- a/docs/ja/README.md
+++ b/docs/ja/README.md
@@ -129,6 +129,7 @@ CowAgent は主要な LLM プロバイダーすべてに対応しています。
 | [WeChat 公式アカウント](https://docs.cowagent.ai/ja/channels/wechatmp) | ✅ | ✅ | | ✅ | |
 | [Telegram](https://docs.cowagent.ai/ja/channels/telegram) | ✅ | ✅ | ✅ | ✅ | ✅ |
 | [Slack](https://docs.cowagent.ai/ja/channels/slack) | ✅ | ✅ | ✅ | | ✅ |
+| [Discord](https://docs.cowagent.ai/ja/channels/discord) | ✅ | ✅ | ✅ | | ✅ |

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

--- a/docs/ja/channels/discord.mdx
+++ b/docs/ja/channels/discord.mdx
@@ -0,0 +1,93 @@
+---
+title: Discord
+description: Discord Bot 経由で CowAgent を接続
+---
+
+> Discord Bot の **Gateway 常時接続** を通じて CowAgent を接続します。ダイレクトメッセージ（DM）およびサーバーチャンネル（@メンションまたはボットへの返信で起動）に対応。Gateway は WebSocket の常時接続を使うため公開 IP やコールバック URL は不要で、すぐに利用できます。
+
+## 1. 接続手順
+
+### ステップ 1: Discord アプリと Bot を作成
+
+1. [Discord 開発者ポータル](https://discord.com/developers/applications) を開き、**New Application** をクリックして名前（例: `CowAgent`）を入力し作成します。
+2. 左メニューの **Bot** ページで **Reset Token** をクリックして Bot Token を生成し、コピーして安全に保管します（一度だけ表示されます）。
+
+<Tip>
+  この Token は Bot のパスワードに相当します。漏洩しないようにしてください。万一漏洩した場合は Bot ページで再度 **Reset Token** をクリックして再生成できます。
+</Tip>
+
+### ステップ 2: Message Content Intent を有効化
+
+DM・チャンネルいずれもテキスト読み取りにこの権限が必要です。
+
+1. **Bot** ページの **Privileged Gateway Intents** を探します。
+2. **Message Content Intent** をオンにして保存します。
+
+<Note>
+  この権限を有効にしないと、受信メッセージの本文が空になり、ボットが応答しません。
+</Note>
+
+### ステップ 3: Bot をサーバーに招待
+
+1. 左メニューの **OAuth2 → URL Generator** を開きます。
+2. **Scopes** で `bot` をチェックします。
+3. **Bot Permissions** で最低限以下をチェックします: `Send Messages`、`Read Message History`、`Attach Files`、`View Channels`。
+4. 下部に生成された認証 URL をコピーしてブラウザで開き、対象のサーバーを選択して認証を完了します。
+
+<Note>
+  DM のみを利用する場合はこのステップを省略できますが、ボットとの DM チャンネルが必要です（ユーザーがボットに直接メッセージを送るなど）。
+</Note>
+
+### ステップ 4: CowAgent に接続
+
+<Tabs>
+  <Tab title="Web コンソール（推奨）">
+    Web コンソール（既定 `http://127.0.0.1:9899`）を開き、**チャネル** メニュー → **チャネルを追加** → **Discord** を選択し、Bot Token を貼り付けて接続をクリックします。
+  </Tab>
+  <Tab title="設定ファイル">
+    `config.json` に以下を追加して Cow を起動します:
+
+    ```json
+    {
+      "channel_type": "discord",
+      "discord_token": "your-discord-bot-token",
+      "discord_group_trigger": "mention_or_reply"
+    }
+    ```
+
+    | パラメータ | 説明 | 既定値 |
+    | --- | --- | --- |
+    | `discord_token` | 開発者ポータルの Bot ページで生成した Bot Token | - |
+    | `discord_group_trigger` | チャンネルのトリガー方式: `mention_or_reply`（@ またはボットへの返信）/ `mention_only`（@ のみ）/ `all`（全メッセージ） | `mention_or_reply` |
+  </Tab>
+</Tabs>
+
+ログに以下のような出力が表示されれば接続成功です:
+
+```
+[Discord] Bot logged in as CowAgent#1234 (id=123456789)
+[Discord] ✅ Discord bot ready, listening for messages
+```
+
+## 2. 機能
+
+| 機能 | 対応状況 |
+| --- | --- |
+| ダイレクトメッセージ（DM） | ✅ |
+| サーバーチャンネル（@bot / ボットへの返信） | ✅ |
+| テキストメッセージ | ✅ 送受信 |
+| 画像メッセージ | ✅ 送受信 |
+| ファイルメッセージ | ✅ 送受信（PDF / Word / Excel など） |
+
+<Note>
+  Discord の 1 メッセージは最大 2000 文字です。長い返信は改行単位で自動的に複数メッセージに分割して送信されます。
+</Note>
+
+## 3. 使い方
+
+接続が完了したら:
+
+- **ダイレクトメッセージ（DM）**: サーバーのメンバー一覧からボットを見つけ、アイコンをクリックして直接メッセージを送ります。
+- **チャンネル**: ボットを招待したチャンネルで、`@your-bot こんにちは` または **ボットのメッセージへの返信** で起動します。
+
+画像やファイルを送るときは、添付の入力欄に **テキスト説明**（説明・質問）を書いて一緒に送信できます。Bot は添付ファイルと説明を合わせて回答します。先に添付を送り、その後に質問を送る形でも、2 つのメッセージは自動でまとめて処理されます。
--- a/docs/ja/channels/index.mdx
+++ b/docs/ja/channels/index.mdx
@@ -11,6 +11,9 @@ CowAgent は複数のチャットチャネルへの接続に対応しており

 | チャネル | テキスト | 画像 | ファイル | 音声 | グループチャット |
 | --- | :-: | :-: | :-: | :-: | :-: |
+| [Telegram](/ja/channels/telegram) | ✅ | ✅ | ✅ | ✅ | ✅ |
+| [Slack](/ja/channels/slack) | ✅ | ✅ | ✅ | | ✅ |
+| [Discord](/ja/channels/discord) | ✅ | ✅ | ✅ | | ✅ |
 | [WeChat](/ja/channels/weixin) | ✅ | ✅ | ✅ | ✅ |  |
 | [Web コンソール](/ja/channels/web) | ✅ | ✅ | ✅ | ✅ | |
 | [Feishu](/ja/channels/feishu) | ✅ | ✅ | ✅ | ✅ | ✅ |
@@ -19,8 +22,6 @@ CowAgent は複数のチャットチャネルへの接続に対応しており
 | [QQ](/ja/channels/qq) | ✅ | ✅ | ✅ | | ✅ |
 | [WeCom アプリ](/ja/channels/wecom) | ✅ | ✅ | ✅ | ✅ | |
 | [WeChat 公式アカウント](/ja/channels/wechatmp) | ✅ | ✅ | | ✅ | |
-| [Telegram](/ja/channels/telegram) | ✅ | ✅ | ✅ | ✅ | ✅ |
-| [Slack](/ja/channels/slack) | ✅ | ✅ | ✅ | | ✅ |

 - **画像 / ファイル / 音声**列は対応するメッセージタイプの送受信に対応していることを示します。詳細は各チャネルのドキュメントを参照してください
 - **グループチャット**列はグループメッセージを認識して応答できることを示します
@@ -41,3 +42,4 @@ CowAgent は複数のチャットチャネルへの接続に対応しており
 - [WeChat 公式アカウント](/ja/channels/wechatmp) — WeChat 公式アカウント（購読アカウント / サービスアカウント）
 - [Telegram](/ja/channels/telegram) — グローバル IM、5 分で接続、公開 IP 不要
 - [Slack](/ja/channels/slack) — チームコラボレーション IM、Socket Mode 接続、公開 IP 不要
+- [Discord](/ja/channels/discord) — コミュニティ IM、Gateway 接続、公開 IP 不要
--- a/docs/zh/README.md
+++ b/docs/zh/README.md
@@ -129,6 +129,7 @@ CowAgent 支持国内外主流厂商的大语言模型。**文本对话、图像
 | [微信公众号](https://docs.cowagent.ai/channels/wechatmp) | ✅ | ✅ | | ✅ | |
 | [Telegram](https://docs.cowagent.ai/channels/telegram) | ✅ | ✅ | ✅ | ✅ | ✅ |
 | [Slack](https://docs.cowagent.ai/channels/slack) | ✅ | ✅ | ✅ | | ✅ |
+| [Discord](https://docs.cowagent.ai/channels/discord) | ✅ | ✅ | ✅ | | ✅ |

 > 飞书、企微智能机器人支持在 Web 控制台内**扫码一键接入**，无需公网 IP。详见 [通道概览](https://docs.cowagent.ai/channels)。