# Discourse AI：Discord 机器人集成指南

**URL:** <https://meta.discourse.org/t/discourse-ai-discord-bot-integration-guide/390391>\
**Category:** Sysadmins\
**Created:** [2025年十二月4日 10:07 UTC](https://meta.discourse.org/t/discourse-ai-discord-bot-integration-guide/390391 "2025-12-04T10:07:23Z")\
**Posts on this page:** 1\
**Showing post:** 1

<div class="post-metadata">

**Author:** ![DevTeVe](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/devteve/32/487601_2.png) [@DevTeVe](https://meta.discourse.org/u/DevTeVe)\
**Post date:** [2025年十二月4日 10:07 UTC](https://meta.discourse.org/t/discourse-ai-discord-bot-integration-guide/390391/1 "2025-12-04T10:07:23Z")

</div>

# 工作原理（架构）

在进行设置之前，重要的是要了解 **您不需要托管单独的机器人应用程序** 或在服务器上运行“机器人”脚本（如 Node.js 或 Python 机器人）。

> **此集成使用 Discord 交互（Webhooks）结合渐进式编辑来模拟流式 AI 体验：**
>
> 1. **用户操作：** 用户在您的 Discord 服务器中输入 `/ask`。
> 2. **Webhook：** Discord 直接向您的 Discourse 服务器发送一个 HTTP POST 请求。
> 3. **即时确认：** Discourse 立即以“正在搜索…”状态进行响应。这可以防止 Discord 出现“交互失败”超时。
> 4. **流式响应：** 后台作业开始生成 AI 答案。随着 AI 生成文本，Discourse 会发送频繁的 **HTTP PATCH** 请求，实时_编辑_ Discord 消息。
> 
> _结果：_ 用户会看到答案实时打出，就像 ChatGPT 一样，而不是等待一个静态的文本块。
> 
> **主要优势：** 由于 Discourse 在内部处理逻辑，因此无需维护额外的基础设施。如果您的论坛在线，您的机器人就在线。

本指南详细介绍了将 Discourse AI 机器人与 Discord 服务器集成的完整过程。它包括 **通过 API 手动注册斜杠命令** 的具体说明，这是目前绕过插件中自动同步问题的要求。

## 先决条件

- **Discourse 管理员访问权限：** 您必须是自托管 Discourse 实例的管理员。
- **Discord 管理员访问权限：** 您必须在目标 Discord 服务器上拥有“管理服务器”权限。
- **终端访问权限：** 您需要一个终端来运行 `curl` 命令。

## 1. 创建 Discord 应用程序

1. 导航至 [Discord 开发者门户](https://discord.com/developers/applications)。
2. 点击右上角的**新建应用程序 (New Application)**。
3. 为您的应用程序命名（例如，“Discourse 助手”）并点击**创建 (Create)**。
4. **复制凭据：** 在**常规信息 (General Information)** 页面上，找到并保存以下内容以备后用：

 ![image](https://global.discourse-cdn.com/meta/original/4X/4/8/1/481cdd154f62f2998b6f48618d71c6e0d1b1d002.png)

## 2. 配置机器人用户

1. 在左侧边栏菜单中，点击**机器人 (Bot)**。

2. 点击**重置令牌 (Reset Token)**。

3. **启用特权意图：**

4. 点击**保存更改 (Save Changes)**。

 ![image](https://global.discourse-cdn.com/meta/original/4X/6/0/5/605cd9175cdcb14d1ce5d5d0bf533af4346a8967.jpeg)

# 3. 配置 Discourse 设置

1. 登录您的 Discourse 管理面板。

2. 导航至**管理 (Admin)** → **插件 (Plugins)** → **AI** → **功能 (Features)**。

3. 搜索“discord”并点击编辑：  

4. 填写详细信息

5. **允许您的 Discord 服务器：**

# 4. 设置交互端点

1. 构建您的端点 URL：`https://=ForumUrl=/discourse-ai/discord/interactions`
2. 返回 [Discord 开发者门户](https://discord.com/developers/applications)。
3. 在**常规信息 (General Information)** 页面上，滚动到**交互端点 URL (Interactions Endpoint URL)**。
4. 粘贴您的 URL 并点击**保存更改 (Save Changes)**。
  - _ **成功** ：_ Discord 将发送一个测试信号。如果保存没有错误，则您的 Discourse 实例成功验证了签名。
  - _ **失败** ：_ 如果出现错误，请确保 `AI Discord app ID` 和 `AI Discord app public key` 已在 Discourse 设置中正确保存。

# 5. 邀请机器人

1. 在开发者门户中，点击侧边栏的**安装 (Installation)**。
2. **范围 (Scopes)：** 勾选 `bot` 和 `applications.commands` 框。
3. **机器人权限 (Bot Permissions)：** 勾选以下内容：
  - 发送消息 (Send Messages)
  - 嵌入链接 (Embed Links)
  - 附加文件 (Attach Files)
  - 读取消息历史记录 (Read Message History)

4. 复制页面顶部的**安装链接 (Installation Link)**。
5. 在浏览器标签页中打开此 URL，授权机器人加入您的服务器。

 ![image](https://global.discourse-cdn.com/meta/original/4X/4/7/6/4769726da3ce0028f87a28d7eb036eead111a0cc.png)

# 6. 注册斜杠命令（手动 API 调用）

**重要提示：** 命令参数名称 **必须** 是 `query`。

## 适用于 Mac / Linux (Bash)

```plaintext
curl -X POST "https://discord.com/api/v10/applications/=ApplicationId=/commands" \
  -H "Authorization: Bot =BotToken=" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ask",
    "description": "Ask the AI a question",
    "options": [
        {
            "name": "query",
            "description": "What is your question?",
            "type": 3,
            "required": true
        }
    ]
}'

```

- **成功响应：** 您应该收到一个包含新命令 ID 的 JSON 响应。
- **错误 401？** 确保在 Authorization 标头中保留了 `Bot `（带空格）这个词在您的令牌之前。

# 7. 验证

1. 打开您的 Discord 服务器。
2. 在文本频道中输入 `/ask`。
3. 应出现命令菜单。选择 `/ask` 并在 `query` 字段中输入问题。
4. **预期行为：**
  - **即时：** 机器人回复“正在搜索…”
  - **几秒钟后：** 消息更新为 AI 的答案。

# 故障排除

| 错误 | 原因 | 解决方案 |
| --- | --- | --- |
| **Curl 中的 401 未授权** | 令牌格式错误 | 确保标头是 `Authorization: Bot =BotToken=`. 使用**机器人 (Bot)** 选项卡中的令牌，而不是“常规信息 (General)”选项卡中的令牌。 |
| **作业 (Job) 异常：上下文**必须是 BotContext 的实例 | 错误的数据包 | 确保您已更新到最新版本，此问题已在 [FIX: Discord Bot crash due to missing BotContext in PersonaReplier by devtekve · Pull Request #36429 · discourse/discourse · GitHub](https://github.com/discourse/discourse/pull/36429#issuecomment-3610843271) 中修复 |

---

_[View the full topic](https://meta.discourse.org/t/discourse-ai-discord-bot-integration-guide/390391)._