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

# Discord Agent Proxy 使用文档

> Discord Agent Proxy 集成指南 - Ace Data Cloud

Discord Agent Proxy 是一个**独立部署**的服务：它保管你自己的 Discord 账号凭据，与 Discord 保持一条常驻连接，并把这个账号的能力通过 **MCP** 和 **REST API** 两个接口开放出来，让 AI 或程序代替你操作 Discord。

容器内**不含任何 AI 模型**，它只负责执行——由你的 AI 客户端（Claude、Cursor 等）或自己的程序发起调用。

```
AI 客户端  ──MCP /mcp──┐
                       ├─→ Discord Agent Proxy ──→ Discord
你的程序 ──REST /api───┘      （保管你的账号凭据）
```

## ⚠️ 使用前必读

用程序自动化操作**个人账号**（self-bot）违反 Discord 的服务条款，账号存在被封禁的风险。这是本服务的固有前提：你提供自己的账号凭据，并自行承担风险。

**强烈建议使用一个专门的小号，不要用你的主账号。**

## 部署服务

进入 [控制台 → 应用](https://platform.acedata.cloud/console/applications)，找到 Discord Agent Proxy 并创建应用。创建后先开通订阅，再进入配置页填入你的 Discord 账号凭据并部署。实例资源由平台自动配置，无需选择规格。

提交部署后会进入应用管理页，与 Telegram、微信部署使用相同的「总览 / 日志 / 文档」布局。「总览」显示实例与订阅状态，并通过账号查询确认 Discord 是否已连接；容器运行正常不代表账号一定已连接。

「总览」中的 Discord 账号卡片提供两项接入信息：

| 项目 | 示例 | 用途 |
| - | - | - |
| MCP 接入地址 | `https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/mcp` | 配置到 AI 客户端 |
| 访问令牌 | `V0p7kAWY...` | 鉴权用，见下 |

### 在控制台查阅和测试接口

打开该应用的「文档」标签，可以查看全部 14 个 REST 操作的请求参数、响应结构，以及 Shell、Python、JavaScript 等语言示例。实例地址和访问令牌会自动填入；令牌默认隐藏。

选择 `GET /api/whoami`，点击「测试」即可确认代理连接的账号。发送、编辑或删除消息等操作会作用于真实 Discord 账号，请确认请求内容后再测试。

「下载 OpenAPI (JSON)」可以导出完整接口定义。文件包含实例地址，不包含访问令牌。若需要更换 Discord 账号凭据，在「总览」中选择「重新部署」，填写新的凭据后提交即可。

### 如何获取 Discord 账号凭据

1. 在电脑浏览器中登录 Discord（[discord.com/app](https://discord.com/app)）
2. 按 `F12` 打开开发者工具，切换到 **Network（网络）** 面板
3. 在 Discord 中随意点击一个频道，观察请求列表
4. 点开任意一个发往 `discord.com/api` 的请求，在 **Request Headers（请求头）** 中找到 `authorization` 字段
5. 复制它的值

这串凭据等同于你的账号登录态，**不要分享给任何人**。如果泄露，在 Discord 中修改密码即可使其立即失效。

## 鉴权方式

除 `/health` 和 `/readyz` 外，所有接口都需要在**请求头**中携带访问令牌：

```
Authorization: Bearer <你的访问令牌>
```

> **注意：本服务只接受请求头鉴权，不支持 `?token=xxx` 这种在网址后面拼接令牌的方式。** 直接在浏览器里打开接口地址会返回 `401 unauthorized`，这是正常现象，不代表部署失败。想确认进程是否存活，请访问 `/health`；想确认 Discord 连接能否处理请求，请访问 `/readyz`。这两个探针都无需鉴权。代理访问令牌未配置时，受保护接口返回 `503`，不会匿名开放。

## 检查服务状态

```bash theme={null}
curl https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/health
curl https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/readyz
```

`/health` 只表示 HTTP 进程存活：

```json theme={null}
{
  "status": "ok"
}
```

`/readyz` 表示 Discord Gateway 是否可用。连接正常时返回 HTTP 200：

```json theme={null}
{
  "status": "ready",
  "gateway_ready": true
}
```

连接中、凭据无效或连接中断时，Kubernetes 对 Pod 的直接探测返回 HTTP 503，并由实例后台自动重试。此时 Pod 会被临时移出公网 Service，因而不保证能通过实例域名读取这段诊断 JSON；请在控制台查看 Deployment 状态，恢复 Ready 后再调用 MCP / REST。

## 在 AI 客户端中使用（MCP）

以 Claude Code 为例：

```bash theme={null}
claude mcp add --transport http discord \
  https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/mcp \
  --header "Authorization: Bearer <你的访问令牌>"
```

Cursor 等支持静态请求头的客户端，请按其当前文档配置 Streamable HTTP 地址。接受下列结构的客户端可使用：

```json theme={null}
{
  "mcpServers": {
    "discord": {
      "type": "http",
      "url": "https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer <你的访问令牌>"
      }
    }
  }
}
```

这不是所有 MCP 客户端的通用配置格式。Claude Desktop / Claude.ai 的远程连接器由云端建立，不读取本地 `claude_desktop_config.json` 中的任意 HTTP 请求头；当前如需静态 Bearer 请求头，请使用 Claude Code 或明确支持该能力的客户端。

配置完成后，就可以直接用自然语言指挥 AI 操作 Discord，例如：

> 看一下我在「项目讨论」频道有没有新消息，如果有人问到发布时间，帮我回复说这周五。

### 可用工具

| MCP 工具 | 作用 |
| - | - |
| `discord_whoami` | 查看当前代理的是哪个账号 |
| `discord_list_guilds` | 列出账号加入的所有服务器 |
| `discord_list_channels` | 列出某个服务器下的频道 |
| `discord_create_text_channel` | 创建文字频道 |
| `discord_list_members` | 列出服务器成员 |
| `discord_send_message` | 发送消息（可指定回复某条消息） |
| `discord_read_messages` | 读取频道最近的消息 |
| `discord_edit_message` | 编辑自己发过的消息 |
| `discord_delete_message` | 删除消息 |
| `discord_search_messages` | 在频道内搜索消息 |
| `discord_add_reaction` | 给消息添加表情回应 |
| `discord_pin_message` | 置顶消息 |
| `discord_create_dm` | 开启一对一私聊，返回频道 ID |
| `discord_send_dm` | 给某个用户发私信 |

## 在程序中使用（REST API）

所有 REST 接口挂载在 `/api` 下，返回体统一为 `{"data": ...}`，出错时为 `{"error": "..."}`。

### 查看当前账号

```bash theme={null}
curl https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/api/whoami \
  -H "Authorization: Bearer <你的访问令牌>"
```

### 发送消息

```bash theme={null}
curl -X POST https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/api/messages \
  -H "Authorization: Bearer <你的访问令牌>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <本次发送的唯一操作 ID>" \
  -d '{"channel_id": "1234567890", "content": "你好"}'
```

重试同一次发送时复用相同的 `Idempotency-Key`，进程会返回首次结果而不重复发送。实例重启会清空最多 5,000 条的内存去重记录，因此调用方仍需自行跟踪长期投递状态。

可选参数 `reply_to` 用于回复指定消息：

```json theme={null}
{
  "channel_id": "1234567890",
  "content": "收到",
  "reply_to": "9876543210"
}
```

### 读取消息

```bash theme={null}
curl "https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/api/channels/1234567890/messages?limit=20" \
  -H "Authorization: Bearer <你的访问令牌>"
```

### 完整接口列表

| 方法与路径 | 参数 | 作用 |
| - | - | - |
| `GET /api/whoami` | — | 当前代理的账号信息 |
| `GET /api/guilds` | — | 账号加入的服务器列表 |
| `GET /api/guilds/{guild_id}/channels` | — | 服务器下的频道列表 |
| `POST /api/guilds/{guild_id}/channels` | `{name}` | 创建文字频道 |
| `GET /api/guilds/{guild_id}/members` | `?limit=`（默认 100） | 服务器成员列表 |
| `POST /api/messages` | `{channel_id, content, reply_to?}` | 发送消息 |
| `GET /api/channels/{channel_id}/messages` | `?limit=`（默认 50，上限 100） | 读取最近消息 |
| `GET /api/channels/{channel_id}/messages/search` | `?q=`（必填）`&limit=`（默认 25） | 搜索消息 |
| `PATCH /api/channels/{channel_id}/messages/{message_id}` | `{content}` | 编辑消息 |
| `DELETE /api/channels/{channel_id}/messages/{message_id}` | — | 删除消息 |
| `POST /api/channels/{channel_id}/messages/{message_id}/reactions` | `{emoji}` | 添加表情回应 |
| `POST /api/channels/{channel_id}/messages/{message_id}/pin` | — | 置顶消息 |
| `POST /api/dms` | `{recipient_id}` | 开启私聊，返回频道 ID |
| `POST /api/dms/send` | `{recipient_id, content}` | 发送私信 |

### 如何获取频道 ID 和用户 ID

在 Discord 客户端中依次打开 **用户设置 → 高级设置**，开启 **开发者模式**。之后右键点击任意频道或用户，菜单中会出现「复制 ID」。

也可以直接调用 `GET /api/guilds` 和 `GET /api/guilds/{guild_id}/channels` 来枚举。

## 常见问题

**返回 `401 unauthorized`**

访问令牌不正确，或者使用了 `?token=` 的方式传递。请确认令牌通过请求头 `Authorization: Bearer &lt;令牌>` 传递，且与控制台显示的一致。

**返回 `503`**

与 Discord 的连接尚未建立。先访问 `/readyz` 查看 `gateway_ready`，若长时间为 `false`，多为账号凭据失效，请重新获取并重新部署。

**返回 `403` 或 `404`**

账号本身没有对应权限（例如不在该服务器中、无权在该频道发言），或者 ID 填错了。这类错误来自 Discord，不是代理服务的问题。

**返回 `429`**

触发了 Discord 的频率限制，响应中的 `retry_after` 字段给出建议的等待秒数。请降低调用频率。

**消息发送后账号被封禁**

如前所述，自动化操作个人账号违反 Discord 服务条款。请使用专用小号，并控制操作频率、避免群发等敏感行为。

## 验证范围

2026 年 8 月 1 日的生产 smoke 使用专用账号验证了账号、服务器、频道、成员、读消息、搜索、发送、编辑、回应和删除。自动化测试覆盖鉴权、参数校验、错误映射与当前依赖库签名；worker 或 chart 变更后仍应重新执行 smoke，不能把历史验证当作持续可用性证明。


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