> ## 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.