Discord Agent Proxy 使用文档

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 的服务条款，账号存在被封禁的风险。这是本服务的固有前提：你提供自己的账号凭据，并自行承担风险。 强烈建议使用一个专门的小号，不要用你的主账号。

部署服务

进入控制台 → 应用，找到 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 账号凭据

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

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

鉴权方式

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

Authorization: Bearer <你的访问令牌>

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

检查服务状态

curl https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/health
curl https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/readyz

/health 只表示 HTTP 进程存活：

{
  "status": "ok"
}

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

{
  "status": "ready",
  "gateway_ready": true
}

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

在 AI 客户端中使用（MCP）

以 Claude Code 为例：

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

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

{
  "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": "..."}。

查看当前账号

curl https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/api/whoami \
  -H "Authorization: Bearer <你的访问令牌>"

发送消息

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 用于回复指定消息：

{
  "channel_id": "1234567890",
  "content": "收到",
  "reply_to": "9876543210"
}

读取消息

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 <令牌> 传递，且与控制台显示的一致。 返回 503 与 Discord 的连接尚未建立。先访问 /readyz 查看 gateway_ready，若长时间为 false，多为账号凭据失效，请重新获取并重新部署。 返回 403 或 404 账号本身没有对应权限（例如不在该服务器中、无权在该频道发言），或者 ID 填错了。这类错误来自 Discord，不是代理服务的问题。 返回 429 触发了 Discord 的频率限制，响应中的 retry_after 字段给出建议的等待秒数。请降低调用频率。 消息发送后账号被封禁 如前所述，自动化操作个人账号违反 Discord 服务条款。请使用专用小号，并控制操作频率、避免群发等敏感行为。

验证范围

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

入门

核心概念

AI 聊天

AI 图像

AI 视频

AI 音频

网络与数据

验证码

身份验证

高级

Coding

更多指南

Discord Agent Proxy 使用文档

⚠️ 使用前必读

部署服务

在控制台查阅和测试接口

如何获取 Discord 账号凭据

鉴权方式

检查服务状态

在 AI 客户端中使用（MCP）

可用工具

在程序中使用（REST API）

查看当前账号

发送消息

读取消息

完整接口列表

如何获取频道 ID 和用户 ID

常见问题

验证范围

​⚠️ 使用前必读

​部署服务

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

​如何获取 Discord 账号凭据

​鉴权方式

​检查服务状态

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

​可用工具

​在程序中使用（REST API）

​查看当前账号

​发送消息

​读取消息

​完整接口列表

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

​常见问题

​验证范围

⚠️ 使用前必读

部署服务

在控制台查阅和测试接口

如何获取 Discord 账号凭据

鉴权方式

检查服务状态

在 AI 客户端中使用（MCP）

可用工具

在程序中使用（REST API）

查看当前账号

发送消息

读取消息

完整接口列表

如何获取频道 ID 和用户 ID

常见问题

验证范围