mirror of
https://github.com/langbot-app/LangBot.git
synced 2026-10-28 19:35:27 +08:00
docs(discord): document verified setup and event delivery
This commit is contained in:
RockChinQ
@@ -4,54 +4,61 @@ description: "Build a Discord AI bot with LangBot. Connect GPT, Claude, Gemini,
|
||||
icon: "/images/platforms/discord.svg"
|
||||
---
|
||||
|
||||
## Create Bot
|
||||
## Create the application and bot
|
||||
|
||||
Go to the [Discord Developer Portal](https://discord.com/developers/applications), log in, and create an application.
|
||||
Open the [Discord Developer Portal](https://discord.com/developers/applications) and choose **New Application**. Do not include `Discord` in the application name: the portal rejects it. Complete the terms confirmation and verification shown by Discord.
|
||||
|
||||
|
||||
1. Copy the **Application ID** from **General Information**. This is the **Client ID** required by LangBot, not a server or channel ID.
|
||||
2. Open **Bot**, choose **Reset Token**, and complete verification. The token is shown only once. Enter it in LangBot; never include it in screenshots, source code, or public messages. Resetting invalidates the old token, so update LangBot as well.
|
||||
3. Under **Privileged Gateway Intents**, enable **Server Members Intent** and **Message Content Intent**, then **Save Changes**. The new adapter requests both. **Presence Intent is not required**.
|
||||
|
||||
Modify the basic information, click `Save Changes` to save.
|
||||
## Connect LangBot
|
||||
|
||||
|
||||
Create a bot using the new **Discord** adapter (`discord-omni`). Enter the Client ID and token and save.
|
||||
|
||||
Click `Bot` on the left, click `Reset Token`, copy the generated Token.
|
||||
Configure event processing next:
|
||||
|
||||
|
||||
- **Pipeline**: add a received-message rule and bind `message.received` to a pipeline with a configured model. Configure **Trigger conditions** on the bot's event route to limit messages by text, session type, or message elements. Explicit event routes bypass the Pipeline's own group response rules; an unconditional route processes every received message. The mention-element condition matches an @ mention, not necessarily the bot.
|
||||
- **Agent**: bind events to an Agent. Instruct it to use the event reply tool to deliver messages; generated text alone is not delivery. Select only the tools the task needs.
|
||||
- **Plugin processor**: add an existing plugin processor configuration separately on the bot page. It subscribes independently to the events declared by the plugin and can run alongside a Pipeline or Agent.
|
||||
|
||||
And check all options in `Privileged Gateway Intents` on this page, click `Save Changes` to save.
|
||||
Enable an available Box sandbox when the runner needs code execution or file generation. Unrelated MCP servers are unnecessary for attachments; external tools with missing credentials introduce additional failures.
|
||||
|
||||
|
||||
Enable the bot and look for `Discord adapter running as ...` in its logs. This confirms Gateway login. Send a real Discord message to verify routing and delivery.
|
||||
|
||||
**Finally, click `OAuth2` on the left, copy the `Client ID` on the page.**
|
||||
## Install in a test server
|
||||
|
||||
## Connect to LangBot
|
||||
In **OAuth2 → URL Generator**, select `bot` and **Guild Install**. For ordinary messages, images, and files, select:
|
||||
|
||||
Click to add a new bot, fill in the `Client ID` and `Token` obtained in the previous step into the configuration.
|
||||
- View Channels
|
||||
- Send Messages
|
||||
- Embed Links
|
||||
- Attach Files
|
||||
- Read Message History
|
||||
- Add Reactions
|
||||
|
||||
|
||||
Open the generated link, select your test server, and authorize installation. Administrator is unnecessary. Add permissions for moderation or threads only when needed. Channel permission overrides must also allow access and replies.
|
||||
|
||||
<Warning>
|
||||
If you are using this adapter within mainland China, you may need to set up a network proxy.
|
||||
</Warning>
|
||||
## Verify delivery
|
||||
|
||||
After filling in, start LangBot. If configured successfully, the log will show `[02-02 16:48:15.263] manager.py (68) - [INFO] : Initializing platform adapter 1: discord`, keep LangBot running.
|
||||
Send a message matching the trigger rules in a server channel, then open a DM from the bot's profile. Check ordinary replies, progressive streaming, image and text-file input, and actual returned attachments in both places. A filename or output path in a text reply is not proof that a file was delivered.
|
||||
|
||||
## Invite Bot to Server
|
||||
Discord limits each message's length, so long streaming replies must be delivered in multiple messages. Verify the final segment and end marker; a successful LangBot run alone does not prove complete delivery. Image understanding requires a vision model; file processing requires suitable runner tools and sandbox support.
|
||||
|
||||
You need to create a server first, then invite the bot to the server.
|
||||
The adapter also exposes edits, deletions, reaction additions/removals, member joins/leaves, bot joins/leaves, and platform-specific events. Pipelines process messages; route other events to an Agent or plugin. Interaction submissions come from interactive components sent by LangBot, not every possible Discord event.
|
||||
|
||||
Go to the `OAuth2` page, select `URL Generator`, select `bot`, check the permissions as shown in the image.
|
||||
For message events, `chat_id` is the channel ID and `group.id` is the server ID. Use the channel ID for channel delivery and the server ID for server/member queries and management. They are not interchangeable.
|
||||
|
||||
|
||||
For member join/leave events, there is no originating channel. Replies use the server's configured **System Messages Channel**. Configure it in Discord's server settings and grant the bot View Channels and Send Messages there; without a system channel, the reply fails explicitly. The member-leave callback does not distinguish voluntary departure from a kick, so do not use `is_kicked` as an authoritative moderation signal.
|
||||
|
||||
|
||||
|
||||
|
||||
Click `Copy`, paste the generated URL into your browser to open it, and invite the bot to your server.
|
||||
## Troubleshooting
|
||||
|
||||
|
||||
- **Gateway login fails**: check the current token and both required intents, including Save Changes. A browser login does not validate the bot token.
|
||||
- **Online without replies**: check enablement, event routes, processor model, group triggers, and channel permissions. Independent plugin subscriptions are configured separately.
|
||||
- **Attachments fail**: check attachment permissions, runner logs, Box readiness, and attachment download connectivity. CDN access is separate from Gateway connectivity.
|
||||
- **Restricted network**: the LangBot environment needs access to Discord Gateway, API, and attachment CDN. Configure a proxy appropriate to your deployment if required.
|
||||
- **Screenshots**: exclude tokens and real users' private conversations.
|
||||
|
||||
## Use Bot
|
||||
|
||||
Now you can use the bot normally in groups or private messages.
|
||||
|
||||
|
||||
- **Attachment 404 errors in an old conversation**: Discord attachment URLs expire, and an old image can also break later text-only requests. Upload the attachment again and reset the conversation context. With EssentialCommands installed, send `!reset` (use your configured command prefix). Resetting context preserves monitoring records.
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 12 KiB |
@@ -4,54 +4,61 @@ description: "LangBot で Discord AI ボットを構築。GPT・Claude・Gemini
|
||||
icon: "/images/platforms/discord.svg"
|
||||
---
|
||||
|
||||
## ボットの作成
|
||||
## アプリとボットを作成する
|
||||
|
||||
[Discord Developer Portal](https://discord.com/developers/applications)にアクセスし、ログインしてアプリケーションを作成します。
|
||||
[Discord Developer Portal](https://discord.com/developers/applications) で **New Application** を選択します。アプリ名に `Discord` を含めると作成が拒否されます。画面に従って規約の確認と認証を完了してください。
|
||||
|
||||
|
||||
1. **General Information** の **Application ID** をコピーします。LangBot の「クライアント ID」に使う値で、サーバー ID やチャンネル ID とは異なります。
|
||||
2. **Bot → Reset Token** で認証を完了し、表示されたトークンを LangBot に入力します。表示は一度だけです。スクリーンショット、コード、公開メッセージには含めないでください。再生成すると旧トークンは無効になるため、LangBot 側も更新します。
|
||||
3. **Privileged Gateway Intents** の **Server Members Intent** と **Message Content Intent** を有効にし、**Save Changes** で保存します。新アダプターは両方を要求します。**Presence Intent は不要です**。
|
||||
|
||||
基本情報を変更し、「Save Changes」をクリックして保存します。
|
||||
## LangBot に接続する
|
||||
|
||||
|
||||
新しい **Discord** アダプター（`discord-omni`）でボットを作成し、クライアント ID とトークンを入力して保存します。
|
||||
|
||||
左側の「Bot」をクリックし、「Reset Token」をクリックして、生成された Token をコピーします。
|
||||
続いてイベント処理を設定します。
|
||||
|
||||
|
||||
- **Pipeline**：「受信メッセージへの返信」ルールを追加し、`message.received` をモデル設定済みの Pipeline に割り当てます。ボットのイベントルートの**トリガー条件**で、本文・会話タイプ・メッセージ要素を指定します。明示的なイベントルートは Pipeline 内のグループ応答ルールをスキップするため、無条件のルートはすべての受信メッセージを処理します。メンション要素の条件はボット以外への @ メンションにも一致します。
|
||||
- **Agent**：イベントを Agent に割り当て、イベント返信ツールで実際にメッセージを送るよう指示します。テキストの生成だけでは送信されません。必要なツールだけを選択します。
|
||||
- **プラグイン処理器**：ボット画面で既存のプラグイン処理器設定を別途追加します。プラグインが宣言したイベントを独立して受信し、Pipeline や Agent と併用できます。
|
||||
|
||||
そして、このページの「Privileged Gateway Intents」のすべてのオプションをチェックし、「Save Changes」をクリックして保存します。
|
||||
コード実行やファイル生成には、利用可能な Box サンドボックスを有効にします。添付ファイルのために無関係な MCP サーバーを有効にする必要はありません。認証情報のない外部ツールは別のエラー原因になります。
|
||||
|
||||
|
||||
ボットを有効にし、ログの `Discord adapter running as ...` を確認します。これは Gateway ログインの確認です。経路と配信の確認には Discord から実際にメッセージを送信してください。
|
||||
|
||||
**最後に、左側の「OAuth2」をクリックし、ページの「Client ID」をコピーします。**
|
||||
## テストサーバーに追加する
|
||||
|
||||
## LangBot に接続
|
||||
**OAuth2 → URL Generator** で `bot` と **Guild Install** を選びます。通常のメッセージ、画像、ファイルのテストには次の権限を使用できます。
|
||||
|
||||
新しいボットを追加するためにクリックし、前の手順で取得した「Client ID」と「Token」を設定に入力します。
|
||||
- View Channels
|
||||
- Send Messages
|
||||
- Embed Links
|
||||
- Attach Files
|
||||
- Read Message History
|
||||
- Add Reactions
|
||||
|
||||
|
||||
生成されたリンクを開き、自分のテストサーバーを選択して認証します。Administrator は不要です。メンバー管理やスレッドの権限は必要な場合だけ追加します。チャンネル固有の権限でも閲覧と送信が許可されている必要があります。
|
||||
|
||||
<Warning title="">
|
||||
中国本土内でこのアダプターを使用している場合、ネットワークプロキシを設定する必要がある場合があります。
|
||||
</Warning>
|
||||
## 実際の送受信を確認する
|
||||
|
||||
入力後、LangBot を起動します。設定が成功した場合、ログに `[02-02 16:48:15.263] manager.py (68) - [INFO] : Initializing platform adapter 1: discord` と表示されます。LangBot を実行し続けてください。
|
||||
サーバーのチャンネルで応答条件に一致するメッセージを送信し、ボットのプロフィールから DM も開きます。両方で通常返信、段階的なストリーミング、画像・テキストファイルの入力、添付ファイルの返送を確認します。返信文にファイル名や保存先が書かれているだけでは配信の証拠になりません。
|
||||
|
||||
## ボットをサーバーに招待
|
||||
Discord には一通の文字数制限があるため、長いストリーミング出力は分割して送信する必要があります。最後の部分と終了マーカーまで確認してください。LangBot の成功ログだけでは完全な配信を保証できません。画像認識には視覚対応モデル、ファイル処理には適切なツールとサンドボックスが必要です。
|
||||
|
||||
まずサーバーを作成し、次にボットをサーバーに招待する必要があります。
|
||||
アダプターは編集、削除、リアクションの追加・削除、メンバーの参加・退出、ボットの参加・退出、プラットフォーム固有イベントも提供します。Pipeline はメッセージを処理するため、その他のイベントは Agent またはプラグインに割り当てます。対話の送信イベントは LangBot が送った対話コンポーネントから発生し、Discord の全イベントをそのまま転送する機能ではありません。
|
||||
|
||||
「OAuth2」ページに移動し、「URL Generator」を選択し、「bot」を選択して、画像に示されている権限をチェックします。
|
||||
メッセージイベントの `chat_id` はチャンネル ID、`group.id` はサーバー ID です。チャンネルへの送信にはチャンネル ID、サーバーやメンバーの照会・管理にはサーバー ID を使います。混同しないでください。
|
||||
|
||||
|
||||
メンバーの参加・退出イベントには送信元チャンネルがありません。返信にはサーバーで設定された **システムメッセージのチャンネル** を使用します。Discord のサーバー設定で指定し、Bot にチャンネルの閲覧とメッセージ送信を許可してください。未設定の場合、返信は明示的に失敗します。退出コールバックでは自主退出とキックを区別できないため、`is_kicked` を確実な管理判断に使用しないでください。
|
||||
|
||||
|
||||
|
||||
|
||||
「Copy」をクリックし、生成された URL をブラウザに貼り付けて開き、ボットをサーバーに招待します。
|
||||
## トラブルシューティング
|
||||
|
||||
|
||||
- **Gateway に接続できない**：最新トークンと必須の二つの Intent、保存状態を確認します。ブラウザーのログイン成功はボットの認証成功とは別です。
|
||||
- **オンラインでも返信がない**：有効化、イベント経路、モデル、応答条件、チャンネル権限を確認します。独立したプラグイン購読は別設定です。
|
||||
- **添付ファイルで失敗する**：添付権限、実行ログ、Box の状態、添付 CDN への接続を確認します。Gateway と CDN の到達性は別々です。
|
||||
- **ネットワーク制限**：LangBot から Discord の Gateway、API、添付 CDN に接続できる必要があります。必要に応じて環境に合ったプロキシを設定します。
|
||||
- **スクリーンショット**：トークンや実際の利用者の私的な会話を含めないでください。
|
||||
|
||||
## ボットの使用
|
||||
|
||||
グループまたはプライベートメッセージでボットを通常どおり使用できるようになりました。
|
||||
|
||||
|
||||
- **古い会話で添付の 404 が発生する**：Discord の添付 URL は期限切れになり、過去の画像によって後続のテキストだけの要求も失敗することがあります。添付を再アップロードし、会話のコンテキストをリセットしてください。EssentialCommands を導入している場合は `!reset` を送信できます（接頭辞はインスタンス設定に従います）。監視ログは削除されません。
|
||||
|
||||
@@ -4,54 +4,60 @@ description: "用 LangBot 搭建 Discord AI 机器人，几分钟内将 GPT、Cl
|
||||
icon: "/images/platforms/discord.svg"
|
||||
---
|
||||
|
||||
## 创建机器人
|
||||
## 创建应用和机器人
|
||||
|
||||
前往[Discord 开发者门户](https://discord.com/developers/applications)，登录后，创建应用。
|
||||
在 [Discord 开发者门户](https://discord.com/developers/applications)中选择 **New Application（新 APP）**。应用名称不要包含 `Discord`，否则门户会拒绝创建。按页面提示完成条款确认和人机验证。
|
||||
|
||||
|
||||
1. 在 **General Information（基本信息）** 复制 **Application ID**。它也是 LangBot 所需的 **客户端 ID**，不是服务器 ID 或频道 ID。
|
||||
2. 打开 **Bot（机器人）**，点击 **Reset Token（重置令牌）** 并完成验证。令牌只显示一次；将它填写到 LangBot，不要放进截图、代码或公开消息。重置后，旧令牌立即失效，需要同步更新 LangBot。
|
||||
3. 在 **Privileged Gateway Intents** 开启 **Server Members Intent** 和 **Message Content Intent**，点击 **Save Changes**。新版适配器会请求这两项；**Presence Intent 不需要开启**。
|
||||
|
||||
修改基础信息，点击`Save Changes`保存。
|
||||
## 连接 LangBot
|
||||
|
||||
|
||||
创建机器人，选择新版 **Discord** 适配器（`discord-omni`），填写客户端 ID 和令牌并保存。
|
||||
|
||||
点击左侧`Bot`，点击`Reset Token`，复制生成的 Token。
|
||||
接着配置事件处理：
|
||||
|
||||
|
||||
- **Pipeline**：添加“回复收到的消息”规则，将 `message.received` 绑定到已配置模型的流水线。在机器人的事件路由中设置**触发条件**，按消息文本、会话类型或消息元素筛选。显式事件路由会跳过 Pipeline 内的群响应规则；无条件路由会处理每条收到的消息。“@某人”元素条件匹配提及消息，并不限定被提及者是机器人。
|
||||
- **Agent**：将事件绑定到 Agent。明确要求 Agent 使用事件回复工具发送消息；单纯生成一段文本不等于已发送。只选择验收或业务实际需要的工具。
|
||||
- **插件处理器**：在机器人页面单独添加已有插件处理器配置。它按插件声明的事件独立接收事件，可与 Pipeline 或 Agent 同时运行。
|
||||
|
||||
并在此页面的`Privileged Gateway Intents`中勾选所有选项，点击`Save Changes`保存。
|
||||
需要执行代码或生成文件时，为运行器启用可用的 Box 沙箱。不要为了发送附件而启用无关的 MCP 服务器；未配置凭据的外部工具会造成额外失败。
|
||||
|
||||
|
||||
启用机器人，查看日志中的 `Discord adapter running as ...`。这说明网关已登录，还需要在 Discord 实际发送消息确认路由和回复正常。
|
||||
|
||||
**最后，点击左侧`OAuth2`，复制页面上的`Client ID`。**
|
||||
## 邀请到测试服务器
|
||||
|
||||
## 对接 LangBot
|
||||
在开发者门户的 **OAuth2 → URL Generator** 选择 `bot`，选择 **Guild Install（服务器安装）**。普通消息、图片和文件测试可使用以下权限：
|
||||
|
||||
点击添加一个新的机器人，将上一步获取的`Client ID`和`Token`填写到配置中。
|
||||
- View Channels（查看频道）
|
||||
- Send Messages（发送消息）
|
||||
- Embed Links（嵌入链接）
|
||||
- Attach Files（添加附件）
|
||||
- Read Message History（阅读消息历史）
|
||||
- Add Reactions（添加反应）
|
||||
|
||||
|
||||
复制生成的链接，在浏览器中打开，选定自己的测试服务器后授权。不需要授予 Administrator；成员管理、子区等功能再按需增加权限。频道自身的权限覆盖也必须允许机器人访问和发送消息。
|
||||
|
||||
<Warning title="">
|
||||
如果你在中国大陆境内使用此适配器，可能需要设置网络代理。
|
||||
</Warning>
|
||||
## 检查实际收发
|
||||
|
||||
填写完成后启动 LangBot，若成功配置，日志中会出现`[02-02 16:48:15.263] manager.py (68) - [INFO] : 初始化平台适配器 1: discord`的字样，保持 LangBot 运行。
|
||||
先在服务器频道发送一条符合触发条件的消息，再从机器人的资料卡打开私信。分别检查普通回复、逐步更新的流式回复、图片和文本文件输入，以及返回的真实附件。文件名或下载路径出现在文字中不能代替附件送达。
|
||||
|
||||
## 邀请机器人到服务器
|
||||
Discord 单条消息有长度限制，长流式输出需要分段送达。检查最后一段和结束标记，不能仅凭 LangBot 运行日志的“成功”判断内容完整。图片理解需要视觉模型；文件处理需要运行器具备相应工具与沙箱能力。
|
||||
|
||||
你需要先创建一个服务器，然后邀请机器人到服务器。
|
||||
新版适配器还提供消息编辑、删除、添加/移除表情、成员加入/离开、机器人加入/离开服务器，以及平台特定事件。Pipeline 仅处理消息；其他事件应交给 Agent 或对应插件。平台特定事件中的交互提交来自 LangBot 发出的交互组件，不代表任意 Discord 事件都会透传。
|
||||
|
||||
前往`OAuth2`页面，选择`URL Generator`，选择`bot`，按照图中所示勾选权限。
|
||||
消息事件的 `chat_id` 是频道 ID，`group.id` 是服务器 ID。发送到频道时使用频道 ID，查询或管理服务器成员时使用服务器 ID；两者不能互换。
|
||||
|
||||
|
||||
成员加入/离开事件没有来源频道，回复会发送到服务器配置的 **系统消息频道**。请在 Discord 服务器设置中配置该频道，并授予机器人查看频道、发送消息权限；未配置系统消息频道时，回复会明确失败。成员离开回调无法区分主动退群和被踢，不要将 `is_kicked` 作为可靠的管理判断依据。
|
||||
|
||||
|
||||
|
||||
|
||||
点击`Copy`，将生成的 URL 粘贴到浏览器中打开，邀请机器人到你的服务器。
|
||||
## 排查问题
|
||||
|
||||
|
||||
|
||||
## 使用机器人
|
||||
|
||||
现在在群里或者私聊机器人都可以正常使用了。
|
||||
|
||||
|
||||
- **无法登录网关**：核对最新 Token，并确认两个必需 Intent 已开启且保存；浏览器登录成功不代表机器人 Token 正确。
|
||||
- **在线但不回复**：核对启用状态、事件路由、处理器模型、群响应规则和频道权限。独立插件订阅与主路由分开检查。
|
||||
- **附件失败**：同时检查 Discord 的附件权限、运行器日志、Box 状态和附件下载网络；图片 CDN 可达性与网关连接是两回事。
|
||||
- **网络受限**：LangBot 所在环境必须能够连接 Discord 网关、API 和附件 CDN。按部署环境配置网络代理。
|
||||
- **文档截图**：不要截取令牌显示页或真实用户的私人消息。
|
||||
- **旧会话突然出现附件 404**：Discord 附件链接会过期，历史图片也可能让后续纯文本请求失败。重新上传附件，并使用会话上下文重置；安装 EssentialCommands 时可发送 `!reset`（命令前缀以实例配置为准）。重置上下文不删除监控记录。
|
||||
|
||||
Reference in New Issue
Block a user