> ## Documentation Index
> Fetch the complete documentation index at: https://docs.echoauth.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# AI 代理设置指南

> 从许可证密钥到让 AI 代理回复你的 Discord 工单。

设置大约需要 15 分钟。你需要准备四样东西：

* 一个 EchoAuth AI 代理**许可证密钥**。如果还没有，请[在商店购买](https://shop.echoauth.dev/product/echos-ai-agent-hosted)。
* 一个你可以添加机器人和管理身份组的 **Discord 服务器**。
* 一个 **[OpenRouter](https://openrouter.ai) API 密钥**。一个 OpenRouter 密钥即可满足代理的全部需求：回答、截图识别和搜索。
* 可选：一个**文档站点**或一些书面文档，供代理作答时参考。

我们负责托管并保持你的代理运行。你只需在 [agent.echoauth.dev](https://agent.echoauth.dev) 的控制面板中完成设置。

> [!NOTE]
>
> \*\*推荐配置。\*\*长期测试仅使用 OpenRouter，并采用以下三个模型：
>
> | 角色 | 模型 |
> | - | - |
> | 聊天 / 代理 | `deepseek/deepseek-v4-flash-0731` |
> | 嵌入 | `qwen/qwen3-embedding-8b` |
> | 视觉（图片识别） | `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free` |
>
> 控制面板中也提供其他服务商（NVIDIA、OpenAI、Anthropic），但以上是我们长期测试过的组合。

## 1. 创建账号

**1. 打开注册页面**

前往 [agent.echoauth.dev/register](https://agent.echoauth.dev/register)。

**2. 输入许可证密钥**

粘贴购买邮件中的密钥，格式类似 `ECHO-XXXX-XXXX-XXXX-XXXX`。

**3. 选择用户名和密码**

密码至少需要 8 个字符。点击 **Create account**。

![包含许可证密钥、用户名和密码字段的注册表单](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/01-register.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=572419f600e4182cf06122e903cf3aa6)

注册页面

许可证生效后，系统会自动为你创建代理。你会进入控制面板，在这里可以看到代理、许可证和使用统计。

![显示一个代理、许可证状态和使用情况的控制面板](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/02-dashboard.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=2397a77fc1428106e09dcbc3b2869dab)

登录后的控制面板

> [!NOTE]
>
> 如果显示 **No agents yet**，请打开侧边栏中的 **License**，检查你的许可证是否有效。

点击你的代理打开它的页面。本指南接下来的所有操作都从这里开始：**Configure** 打开设置，**Live logs** 显示代理正在做什么，**Update Agent** 应用需要重新部署的设置。

![带有 Configure、Live logs、Restart 和 Update Agent 的代理页面](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/03-agent.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=6c4ca792bd16efd8e9e175519f337123)

代理页面

## 2. 创建你的 Discord 机器人

你的代理通过一个属于你自己的 Discord 机器人来回答。请在 Discord Developer Portal 中创建它。

**1. 创建应用程序**

打开 [Discord Developer Portal](https://discord.com/developers/applications)，点击 **New Application**。以你的支持代理命名，例如 "Acme Support"。

**2. 开启 Message Content intent**

进入 **Bot**。在 **Privileged Gateway Intents** 下开启 **Message Content Intent** 并保存。

> [!WARNING]
>
> 没有这个 intent，机器人收到的消息是空的，永远不会回复。

**3. 复制机器人令牌**

仍在 **Bot** 页面，点击 **Reset Token** 并复制令牌。你将在下一节把它粘贴到控制面板中。请妥善保密：任何拿到令牌的人都可以控制你的机器人。

**4. 邀请机器人加入你的服务器**

前往 **OAuth2** → **URL Generator**。勾选作用域 `bot` 和 `applications.commands`，然后勾选以下机器人权限：

* View Channels
* Send Messages
* Read Message History
* Embed Links
* Attach Files

打开生成的 URL，将机器人添加到你的服务器。

**5. 让机器人可以访问你的工单分类**

确保机器人的身份组可以看到创建工单频道所在的分类。如果它看不到该频道，就无法回答。

## 3. 添加密钥

在 [openrouter.ai/keys](https://openrouter.ai/keys) 创建一个 API 密钥，并给你的 OpenRouter 账号充值一些额度。视觉模型是免费的，但聊天和嵌入模型按使用量付费。

然后在你的代理页面点击 **Configure**，打开 **API Keys** 标签页。

![API Keys 标签页，OpenRouter API 密钥和 Discord 机器人令牌均标记为已配置](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/04-keys.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=635dd8eb112950e6f74cfdc24c4f5664)

API Keys 标签页，已配置 OpenRouter 密钥和 Discord 机器人令牌

1. 将密钥粘贴到 **OpenRouter API Key**。
2. 粘贴你的 **Discord Bot Token**。
3. 点击 **Save**。

OpenAI、Anthropic 和 NVIDIA 字段可以留空。密钥会加密存储，保存后不会再次显示。**configured** 标记表示密钥已设置。

## 4. 选择你的 AI 模型

打开 **AI Settings** 标签页。代理使用三个模型。请把三个都设为 **OpenRouter**，并选择推荐的模型：

| 设置 | 作用 | 服务商 | 模型 |
| - | - | - | - |
| **Chat / Agent Model** | 撰写回答，并决定在你的文档中查找什么。 | OpenRouter | `deepseek/deepseek-v4-flash-0731` |
| **Vision Model** | 读取客户附在工单中的截图。 | OpenRouter | `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free` |
| **Embedding Model** | 为你的文档建立索引并进行搜索。 | OpenRouter | `qwen/qwen3-embedding-8b` |

![AI Settings 标签页，聊天、视觉和嵌入模型均选择 OpenRouter](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/05-ai.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=9c43f2bab0d0ade4e7a897f04f0a21f0)

AI Settings 标签页，使用推荐的 OpenRouter 模型

> [!NOTE]
>
> 在嵌入模型下方，控制面板会提示它超过 2000 维。对于 `qwen/qwen3-embedding-8b` 这是正常的。搜索仍然有效：它会检查每一段内容而不是使用索引，对于几千段内容的知识库，速度依然很快。

然后撰写你的 **Base Prompt**。这是代理的常驻指令：它为谁工作、使用什么语气，以及绝对不能做什么。例如：

```text theme={null}
You are the support agent for Acme Store. Be friendly and concise.
Answer only from the documentation. If you are not sure, ask a staff member to step in.
```

> [!WARNING]
>
> 请在建立任何索引之前选好嵌入模型。之后更改它会使现有索引无法使用，直到你重建索引。

## 5. 连接到你的工单

打开 **Discord** 标签页。这些设置告诉代理在哪里回答，以及谁算作工作人员。

![包含 owner 身份组、staff 身份组、工单分类 ID、工单机器人 ID 和图像模型的 Discord 标签页](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/06-discord.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=43f9146b21aa094f8d7629f409930f57)

Discord 标签页

要复制 ID，请在 Discord 的 **User Settings** → **Advanced** 中开启 **Developer Mode**。然后右键点击身份组、分类或用户，选择 **Copy ID**。

> [accordion] Owner Role IDs
>
> 可以使用所有斜杠命令的身份组，包括 `/pause_bot` 和 `/edit_base`。多个 ID 用逗号分隔。

> [accordion] Staff Role IDs
>
> 你的支持团队的身份组。当工作人员在工单中发言时，代理会退后，并在该工单中保持安静。要让它回来，请在工单中提及机器人，或在该工单中使用 `/restart`。

> [accordion] Ticket Category IDs
>
> 创建工单频道所在的分类。代理只会在这些分类内回答。

> [accordion] Ticket Bot IDs
>
> 你的工单机器人的用户 ID，例如 Ticket Tool 或 SellAuth Tickets。代理会忽略其他机器人，因此请在此添加你的机器人，让代理能够读取工单的开场消息。

> [accordion] Image Models
>
> 备用视觉模型，每行一个，当 AI Settings 中的视觉模型失败时按顺序尝试。请填入以下备用模型：\
> `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free`\
> `google/gemma-4-31b-it:free`\
> `google/gemma-4-26b-a4b-it:free`\
> `thinkingmachines/inkling-small:free`\
> `dots-studio/dots-3-note-preview:free`

点击 **Save**。

## 6. 为代理提供你的文档

打开 **Knowledge Base** 标签页。代理从两种来源作答，你可以使用其中之一或两者同时使用。

![包含 Index documentation 按钮、Docs URL 和内部知识库的 Knowledge Base 标签页](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/07-knowledge.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=18150d070975d8635a2a87c251b04dfa)

Knowledge Base 标签页

> [tab] 文档站点
>
> 如果你的文档发布在 Mintlify 上，请使用此方式。
>
> 1. 输入你的 **Docs URL**，例如 `https://docs.acme-store.com`，末尾不要加斜杠。该站点必须提供 `/llms.txt`，Mintlify 会自动提供。
> 2. 点击 **Save**，然后回到你的代理页面并点击 **Update Agent**。
> 3. 回到此标签页，点击 **Index documentation**。几百个页面需要几分钟，运行期间你可以离开页面。
>
> 当 **Sync Mode** 设为 **Poll llms.txt hourly** 时，代理每小时检查一次你的文档，并只重新索引有变化的页面。

> [tab] 内部知识库
>
> 用于不在文档站点上的任何内容：FAQ、政策、错误代码。
>
> 1. 滚动到 **Internal Knowledge Base**。
> 2. 粘贴你的文本，或点击 **Load file** 并选择 `.txt` 或 `.md` 文件。
> 3. 点击 **Save**。
>
> 代理会在大约一分钟内为其建立索引。纯文本即可：全大写的标题或位于 `=====` 行之间的标题会成为可搜索的章节。

请保持 **Documentation Retrieval** 和 **Agentic Retrieval** 开启。开启检索后，代理只会查找与每个问题相关的段落，而不是每次都阅读全部内容。

## 7. 设置回复时机和升级处理

打开 **Behavior** 标签页。

![包含回复时机和人工协助关键词的 Behavior 标签页](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/08-behavior.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=14df915b4ac0f9860f6e3a6b3a61d318)

Behavior 标签页

代理会等到客户停止输入，然后一次性回复所有内容。每条新消息都会重新开始计时。

| 设置 | 默认值 | 含义 |
| - | - | - |
| After ticket opens | 45 秒 | 第一条消息之后的等待时间，因为客户通常会补充细节或截图。 |
| After each message | 30 秒 | 后续消息之后回复前所需的安静时间。 |
| Maximum wait | 180 秒 | 即使客户一直在输入，超过这个时间也会回复。 |

在 **Human Help Keywords** 下，列出应该把工单转交给你的团队的词，每行一个。例如 `refund`、`chargeback` 或 `real person`。

## 8. 获取提醒（可选）

打开 **Notifications** 标签页，粘贴一个私密工作人员频道的 ID。当你的许可证即将到期，以及 AI 服务商拒绝你的密钥或额度用尽时，代理会在这里发布消息。

![包含通知频道 ID 的 Notifications 标签页](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/09-notifications.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=5906f4bf0dbdf4fa308c4958553bded2)

Notifications 标签页

## 9. 启动代理

回到你的代理页面，点击 **Update Agent**。这会用你的机器人令牌、文档 URL 和嵌入模型重新部署代理。运行期间，输出会显示在按钮下方。

> [!NOTE]
>
> 大多数设置会在大约一分钟内生效，无需重新部署。只有在更改 **Discord Bot Token**、**Docs URL**、**Embedding Model** 或 **Sync Mode** 之后，才需要 **Update Agent**。

检查一切是否正常：

1. 在你的服务器中打开一个测试工单，询问一个你的文档能回答的问题。
2. 在代理页面打开 **Live logs**，观察代理接收消息、搜索你的文档并回复。

![Live logs 显示代理启动、同步、搜索文档并在工单中回复](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/11-logs.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=18d1bd77e85407858cd81751cd36388e)

Live logs

代理运行时，状态标记显示 **Online**。

## 斜杠命令

代理加入你的服务器后，owner 和 staff 可以在 Discord 中控制它。

| 命令 | 谁可以使用 | 作用 |
| - | - | - |
| `/stop` | Owner、staff | 让代理停止在此频道回复。 |
| `/restart` | Owner、staff | 让代理重新在此频道回复。 |
| `/mute_existing` | Owner、staff | 让代理在所有已打开的工单中停止回复。 |
| `/pause_bot` | Owner | 在所有地方暂停代理。 |
| `/resume_bot` | Owner | 在所有地方恢复代理。 |
| `/edit_base` | Owner | 编辑基础提示词。 |
| `/chat_model` | Owner | 更改聊天模型。 |

你也可以在控制面板 **Discord** 标签页中使用 **Global Bot Pause** 来暂停代理。

## 保持许可证有效

只要许可证有效，你的代理就会保持在线。**License** 页面显示剩余天数和到期日期。

![显示状态、剩余天数和可用套餐的 License 页面](https://mintcdn.com/echoauth/cLGTi81QYaoRs3IW/images/ai-agent-setup/10-license.png?fit=max\&auto=format\&n=cLGTi81QYaoRs3IW\&q=85\&s=62db270604520c9a0c2815db6201b908)

License 页面

要续订，请在[商店](https://shop.echoauth.dev/product/echos-ai-agent-hosted)购买新密钥，点击 **Renew license** 并粘贴密钥。时间会叠加到你当前的许可证上。

## 故障排除

> [accordion] 机器人在线，但从不回复
>
> * 检查 Discord Developer Portal 中 **Message Content Intent** 是否已开启。
> * 检查工单的分类 ID 是否在 **Ticket Category IDs** 中。
> * 检查机器人是否可以在该分类中查看并发送消息。
> * 检查是否已有工作人员在工单中发言。提及机器人或使用 `/restart` 让它回来。
> * 检查 **Global Bot Pause** 是否已关闭。

> [accordion] 机器人忽略工单的开场消息
>
> 在 **Discord** 标签页的 **Ticket Bot IDs** 中添加你的工单机器人的用户 ID。

> [accordion] 代理没有使用我的文档
>
> 打开 **Knowledge Base** 标签页。如果显示 **Documentation is not indexed yet**，请点击 **Index documentation**。如果显示 **The index does not match the embedding model**，请点击 **Clear and rebuild the index**，或将嵌入模型改回显示的那一个并保存。

> [accordion] 回复或索引因 OpenRouter 错误而失败
>
> 检查你的 OpenRouter 账号是否有额度，以及 **API Keys** 标签页中的密钥是否仍然有效。视觉模型等免费模型在繁忙时段可能被限流；此时代理会回退到 **Image Models** 中的下一个模型。

> [accordion] 代理停止响应
>
> 打开 **Live logs** 查找错误，例如密钥无效或额度用尽。然后点击代理页面上的 **Restart**。如果仍无效，请点击 **Update Agent**。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.