# 疑難排解

常見問題及其解決方法。

---

## Gateway 問題

### Gateway 無法啟動

- **連接埠衝突**, 另一個程序可能正在使用連接埠 18789。使用 `lsof -i :18789` 檢查。
- **設定錯誤**, `neotask.json` 中的 JSON 無效。Gateway 在啟動時驗證設定並報告特定錯誤。
- **Gateway 鎖定**, 之前的實例可能留下了過時的鎖定檔案。診斷工具可以偵測並修復此問題。
- **Node.js 版本**, Neotask 需要 Node 22+。

### Gateway 啟動但頻道無法連接

- **缺少憑證**, 每個頻道都需要自己的驗證（機器人令牌、QR 碼掃描、API 金鑰）。
- **網路問題**, 頻道需要網際網路存取才能連接至訊息平台 API。
- **速率限制**, 某些平台對新連接施加速率限制。等待並重試。

### 無法從桌面應用程式連接

- **連接埠錯誤**, 確保桌面應用程式連接至正確的 Gateway 連接埠。
- **驗證不符**, Gateway 令牌必須相符。
- **防火牆**, 如果 Gateway 在另一台機器上，確保連接埠可存取。

---

## 頻道問題

### WhatsApp 無法連接

- **QR 碼已過期**, QR 碼約 60 秒後過期。請快速重新掃描。
- **多裝置限制**, WhatsApp 限制連結裝置的數量。
- **工作階段損壞**, 刪除 WhatsApp 工作階段目錄並重新配對。

### Telegram 機器人未收到訊息

- **機器人令牌無效**, 使用 BotFather 驗證您的機器人令牌。
- **隱私模式**, 機器人預設只在群組中被提及時才看到訊息。
- **Webhook 衝突**, 另一個服務可能正在消耗訊息。

### Discord 機器人未回應

- **缺少意圖**, 在 Discord 開發者入口網站中啟用所需的 Gateway 意圖。
- **缺少權限**, 機器人在目標頻道中需要讀取和傳送權限。

---

## 模型問題

### 驗證錯誤

- **未設定金鑰**, 確保已設定提供者 API 金鑰。
- **金鑰已過期**, 某些 OAuth 令牌會過期。重新驗證。
- **速率限制**, 如果您有多個金鑰，金鑰輪換將自動切換。

### 回應緩慢

- **模型選擇**, 較大的模型速度較慢。對快速任務嘗試使用更快的模型。
- **上下文大小**, 長對話會減慢處理速度。嘗試 `/compact`。
- **網路延遲**, 檢查與您的模型提供者的連通性。

---

## 節點問題

### 伴侶應用程式找不到 Gateway

- **綁定模式**, Gateway 必須綁定至區域網路或 Tailnet（而非回送）才能讓外部裝置存取。
- **同一網路**, 對於 Bonjour 探索，兩個裝置必須在同一網路上。
- **手動輸入**, 在應用程式設定中手動輸入 Gateway 主機和連接埠。

---

## 工作階段問題

### 超出上下文視窗

- **壓縮**, 使用 `/compact` 摘要並重置上下文。
- **啟用自動壓縮**, 在設定中設定壓縮閾值。
- **新工作階段**, 使用 `/new` 重新開始。

---

## 診斷

內建診斷工具檢查常見問題，並可自動修復許多問題：

- 設定驗證
- 檔案權限
- 頻道連通性
- 模型驗證狀態
- Node.js 相容性
- 網路設定

查看 Gateway 日誌以獲取詳細的錯誤資訊。`/health` 端點提供所有元件的機器可讀狀態。

---

## 獲取幫助

1. 執行診斷工具以進行自動修復
2. 查看 Gateway 日誌以獲取詳細的錯誤訊息
3. 透過桌面應用程式中的 Intercom 聊天小工具聯絡支援