> For the complete documentation index, see [llms.txt](https://miulien.gitbook.io/bot/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://miulien.gitbook.io/bot/utilities/clear.md).

# 清除訊息（clear）

使用 `/clear` 或 `m!clear`，快速清理**目前頻道**中的訊息。除了刪除最近的訊息，也能**指定成員**，並決定是否刪除**釘選訊息**。

## 🧹 如何使用？

| 指令範例                  | 功能                   |
| --------------------- | -------------------- |
| `/clear 數量:10`        | 刪除目前頻道最新的 10 則符合條件訊息 |
| `/clear 數量:20 成員:@玩家` | 刪除該玩家最新的 20 則訊息      |
| `/clear 數量:5 包含釘選:是`  | 允許將釘選訊息一併列入刪除        |
| `m!clear 10`          | 使用文字指令刪除 10 則訊息      |
| `m!clear 20 @玩家`      | 使用文字指令只清理指定玩家的訊息     |

每次可指定刪除 **1～100 則**。刪除只作用於**執行指令的頻道**，不會同時清理其他頻道。

## 🔎 三個可調整的參數

* **數量（必填）**：要刪除的訊息數量，範圍為 **1～100**。
* **成員（選填）**：只刪除指定成員發出的訊息；不指定則不限發言者。
* **包含釘選（選填）**：預設為**否**，因此釘選訊息會被跳過；設為**是**才允許一併刪除。

**指定成員時，數量代表符合篩選條件的訊息數量。** 例如在頻道輸入「刪除某玩家的 20 則訊息」，Miulien 會從最新訊息往前搜尋，直到找到最多 20 則符合條件的訊息，而不是只在頻道最新 20 則裡尋找該玩家。

如果符合條件的訊息不足指定數量，Miulien 會刪除實際找到的訊息，並在結果中提醒。

## 📌 釘選訊息與舊訊息

**釘選訊息預設受到保護。** 執行一般清除指令時，這些訊息不會計入刪除目標。只有明確啟用「包含釘選」，才會把它們納入。

Discord 不支援將**超過 14 天**的訊息用批次方式刪除，但這不代表 Miulien 無法處理舊訊息：

* **14 天內的訊息**：優先使用批次刪除，提高效率。
* **超過 14 天的訊息**：改用逐則刪除，因此可能比較慢。

若批次刪除失敗，Miulien 也會嘗試改成逐則刪除。

## 💬 指令訊息與執行結果

如果使用 `m!clear`，Miulien 會嘗試**額外刪掉該則指令訊息**，不占指定的刪除數量。

完成後會在頻道顯示清理摘要，包含：

* 實際成功刪除的訊息數量。
* 是否指定成員、是否包含釘選。
* 符合條件的訊息不足，或有刪除失敗的情況。

提醒：**清除訊息屬於刪除操作，沒有內建的復原功能。** 執行前請特別確認數量，以及是否真的需要包含釘選訊息。

## 🔐 使用權限

執行者需要符合以下**任一條件**：

* 在目前頻道擁有 Discord **「管理訊息」** 權限。
* 所屬身份組已透過 Miulien 的 `permissions` 功能取得 **`clear` 指令授權**。

此外，**Miulien 本身**必須在該頻道擁有\*\*「管理訊息」**及**「讀取訊息歷史」\*\*權限。即使使用者已獲授權，Bot 缺少必要權限時仍不能清除訊息。

> `/clear` 只能在伺服器內支援訊息歷史的頻道使用，不能在私人訊息中執行。
