疑難排解

常見問題及其解決方法。

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 聊天小工具聯絡支援