常見問題

以下列出 discli 使用者最常遇到的問題、症狀、根因與處理方式。

找不到 token

錯誤：找不到機器人 token。請透過 `discli config set token`、`--token` 旗標或 `DISCORD_BOT_TOKEN` 環境變數設定。

原因： discli 會依序檢查三個位置是否有 token：--token CLI 參數、DISCORD_BOT_TOKEN 環境變數，以及 ~/.discli/config.json。若三者都沒有，則出現此錯誤。

修正方式：

# 方案一：永久儲存
discli config set token YOUR_BOT_TOKEN

# 方案二：本次工作階段設定
export DISCORD_BOT_TOKEN=YOUR_BOT_TOKEN

# 方案三：指令級指定
 discli --token YOUR_BOT_TOKEN message send "#general" "hello"

指令被權限拒絕

錯誤：動作 "channel_delete" 不受權限設定檔 "safe-agent" 允許。

原因： 你使用的權限設定檔限制了目前操作。

修正方式：

# 檢查目前設定檔
 discli permission show safe-agent

# 切換到可用的設定檔
discli serve --profile admin

# 或不帶設定檔（允許全部）
discli serve

機器人沒有回應訊息

症狀： 機器人在線上（Discord 顯示綠點）但完全不回應訊息；discli listen --events messages 無輸出。

原因： 未啟用機器人的 MESSAGE_CONTENT Privileged Intent。

修正方式：

被速率限制

錯誤：觸發速率限制。請在 2.5 秒後重試。

原因： Discord API 速率限制或 discli 內建速率限制被觸發。discli 預設保護設定為每 5 秒最多 5 次破壞性動作，避免機器人意外發送大量請求。

修正方式：

• 降低發送頻率：特別是大量發送時要放慢節奏
• 檢查程式邏輯：無窮迴圈或缺少去重會造成爆量請求
• 針對 429：discli 會自動退避重試；若仍持續 429，表示請求量過高

discli listen 無任何輸出

症狀： 執行 discli listen --events messages 後進程啟動，但即使 server 有訊息也沒事件。

原因： GUILD_MESSAGES Intent 未啟用，或機器人沒有頻道的觀看權限。

修正方式：

1. 到開發者主控台啟用 Server Members Intent 與 Message Content Intent（同上）
2. 確認機器人在目標頻道有 View Channel 與 Read Message History 權限
3. 檢查機器人是否真正加入伺服器，discli server list 應有該伺服器

discli serve 立即退出

症狀： discli serve 啟動後數秒內退出，有時完全沒有輸出。

原因： 常見為 token 無效、網路不通，或缺少意圖設定。

修正方式：

# 看 stderr 錯誤
 discli serve 2> error.log
 cat error.log

# 確認 token 是否可用
discli server list

# 確認網路連線
discli config show

Slash 指令未顯示

症狀： 已註冊 Slash 指令，但在 Discord 命令選單中看不到。

原因： 全域 Slash 指令需要最多 1 小時 傳播，不是 discli 的問題，而是 Discord 的傳播限制。

修正方式：

• 等待最多 1 小時 等全域同步完成
• 測試階段請用伺服器註冊，可立即同步：

# 伺服器同步（即時）
discli slash register --guild 1234567890 --name ping --description "Pong!"

# 全域同步（最慢）
discli slash register --name ping --description "Pong!"

未知頻道錯誤

錯誤：找不到頻道 "general"。你是否要使用 "#general"？

原因： 頻道名稱必須加 # 前綴，否則 discli 會將它當作伺服器名稱。

修正方式：

# 錯誤：會被當作伺服器名稱
 discli message send general "hello"

# 正確：# 前綴代表頻道
 discli message send "#general" "hello"

# 直接使用數字 ID 不需前綴
 discli message send 1234567890123456789 "hello"

機器人可讀訊息但無法回覆

症狀： discli message list "#general" 正常，但 discli message send "#general" "hello" 回傳權限錯誤。

原因： 機器人有 View Channel 與 Read Message History，但缺少 Send Messages。

修正方式：

1. 進入 Discord 的 Server Settings > Roles
2. 找到機器人的身分組
3. 開啟 Send Messages 權限
4. 若該頻道有權限覆蓋，請另外檢查該頻道權限（頻道權限優先於身分組）

語音功能錯誤：未安裝語音額外套件

症狀： 任一 discli voice 指令執行後立刻退出，顯示：

錯誤：尚未安裝語音功能所需的額外套件：PyNaCl、discord-ext-voice-recv、davey。
請使用：`uv sync --extra voice`（或：`pip install 'discord-cli-agent[voice]'`）。
請執行 `discli doctor` 確認完整設定。

原因： 未安裝語音可選依賴套件。discli 的核心安裝為文字精簡版。

修正方式：

pip install 'discord-cli-agent[voice,deepgram]'
# 或在 checkout 目錄中：
uv sync --extra voice --extra deepgram

再執行：

discli doctor

機器人加入語音但沒有逐字稿

症狀： discli voice listen（或會議逐字稿示範）顯示已連線 Listening to #...，但不論音量多大都不出現轉譯文字。

可能原因與修正：

1. 未設定 STT 金鑰。 執行 discli doctor，若 DEEPGRAM_API_KEY（或你使用的 provider）未設定，請補上並重啟。
2. 機器人被伺服器設定為啞音。 管理員可將機器人 server-deafen，請在成員清單中確認機器人未被靜音/被語音封禁。
3. DAVE 修補未生效。 discli doctor 應顯示 [ok] DAVE/Opus patches；若顯示 [FAIL]，listener 無法解密音訊，請附帶輸出提交 issue。
4. 音訊有到達但 STT 拒絕。 你可執行 discli voice capture --duration 10 讓人說話測試。若 WAV 非空且可播，表示收音正常，問題在下游（STT 金鑰、網路、供應額度）。若 WAV 空白或長度僅約 20ms，收音本身壞掉，請回報問題。

語音日誌出現 OpusError: corrupted stream

症狀： 日誌重複出現 OpusError('corrupted stream')，逐字稿會空白或不穩定。

原因： Discord 語音傳輸使用 DAVE 加密；discord-ext-voice-recv 原生函式庫不會解開 DAVE，libopus 看到的是加密位元組所以回傳錯誤。discli 於執行期做 monkeypatch，於 SecretBox 與 libopus 之間呼叫 davey.DaveSession.decrypt(...)。

若修補成功，通常仍會看到少量 [voice] skipping bad opus packet（每個 session 少數，代表封包順序不穩或傳輸異常）。若看到大量訊息，通常表示修補沒生效。

修正方式：

discli doctor

確認 DAVE/Opus patches 為 [ok]。若不是，重新安裝語音 extras：

pip install --force-reinstall 'discord-cli-agent[voice]'

discli doctor 回報問題

症狀： discli doctor 結束訊息為 找到 N 個問題。

修正方式： 每條失敗檢查都有 hint: 說明，依該提示安裝套件或設定環境變數。--json 也會輸出相同結構資料，方便腳本處理：

discli doctor --json | jq '.sections[].checks[] | select(.ok==false)'