Skip to content
SlopCode

疑難排解

要偵錯 SlopCode 的問題，請先檢查其儲存在磁碟上的日誌和本地資料。

日誌

日誌檔案寫入位置：

  • macOS/Linux: ~/.local/share/slopcode/log/
  • Windows: 按 WIN+R 並貼上 %USERPROFILE%\.local\share\slopcode\log

日誌檔案以時間戳記命名（例如 2025-01-09T123456.log），並保留最近的 10 個日誌檔案。

你可以透過 --log-level 命令列選項設定日誌等級以取得更詳細的偵錯資訊。例如：slopcode --log-level DEBUG。

儲存

SlopCode 將工作階段資料和其他應用程式資料儲存在磁碟上：

  • macOS/Linux: ~/.local/share/slopcode/
  • Windows: 按 WIN+R 並貼上 %USERPROFILE%\.local\share\slopcode

該目錄包含：

  • auth.json - 身分驗證資料，如 API 金鑰、OAuth Token
  • log/ - 應用程式日誌
  • project/ - 專案特定資料，如工作階段和訊息資料
    • 如果專案位於 Git 儲存庫中，則儲存在 ./<project-slug>/storage/
    • 如果不是 Git 儲存庫，則儲存在 ./global/storage/

桌面應用程式

SlopCode Desktop 會在背景執行一個本地 SlopCode 伺服器（即 slopcode-cli 附屬程序）。大多數問題是由外掛異常、快取損壞或錯誤的伺服器設定引起的。

快速檢查

  • 完全退出並重新啟動應用程式。
  • 如果應用程式顯示錯誤頁面，請點擊重新啟動並複製錯誤詳情。
  • 僅限 macOS：SlopCode 選單 -> Reload Webview（當 UI 空白或凍結時有效）。

停用外掛

如果桌面應用程式在啟動時當機、卡住或行為異常，請先停用外掛。

檢查全域設定

開啟你的全域設定檔，查找 plugin 鍵。

  • macOS/Linux: ~/.config/slopcode/slopcode.jsonc（或 ~/.config/slopcode/slopcode.json）
  • macOS/Linux（舊版安裝）: ~/.local/share/slopcode/slopcode.jsonc
  • Windows: 按 WIN+R 並貼上 %USERPROFILE%\.config\slopcode\slopcode.jsonc

如果你設定了外掛，請透過移除該鍵或將其設定為空陣列來暫時停用它們：

{
  "$schema": "https://slopcode.dev/config.json",
  "plugin": [],
}

檢查外掛目錄

SlopCode 還可以從磁碟載入本地外掛。暫時將這些外掛移走（或重新命名資料夾），然後重新啟動桌面應用程式：

  • 全域外掛
    • macOS/Linux: ~/.config/slopcode/plugins/
    • Windows: 按 WIN+R 並貼上 %USERPROFILE%\.config\slopcode\plugins
  • 專案外掛（僅當你使用了專案級設定時）
    • <your-project>/.slopcode/plugins/

如果應用程式恢復正常，請逐個重新啟用外掛，找出導致問題的那個。

清除快取

如果停用外掛沒有幫助（或外掛安裝卡住了），請清除快取以便 SlopCode 重新建置。

  1. 完全退出 SlopCode Desktop。
  2. 刪除快取目錄：
  • macOS: Finder -> Cmd+Shift+G -> 貼上 ~/.cache/slopcode
  • Linux: 刪除 ~/.cache/slopcode（或執行 rm -rf ~/.cache/slopcode）
  • Windows: 按 WIN+R 並貼上 %USERPROFILE%\.cache\slopcode
  1. 重新啟動 SlopCode Desktop。

修復伺服器連線問題

SlopCode Desktop 可以啟動自己的本地伺服器（預設行為），也可以連線到你設定的伺服器 URL。

如果你看到**「Connection Failed」**對話框（或應用程式始終停留在啟動畫面），請檢查自訂伺服器 URL。

清除桌面預設伺服器 URL

在主頁面上，點擊伺服器名稱（帶有狀態指示點）以開啟伺服器選擇器。在預設伺服器部分，點擊清除。

從設定中移除 server.port / server.hostname

如果你的 slopcode.json(c) 包含 server 部分，請暫時移除該部分並重新啟動桌面應用程式。

檢查環境變數

如果你在環境中設定了 SLOPCODE_PORT，桌面應用程式將嘗試使用該連接埠作為本地伺服器連接埠。

  • 取消設定 SLOPCODE_PORT（或選擇一個空閒連接埠）並重新啟動。

Linux: Wayland / X11 問題

在 Linux 上，某些 Wayland 設定可能會導致視窗空白或合成器錯誤。

  • 如果你使用 Wayland 且應用程式出現空白或當機，請嘗試使用 OC_ALLOW_WAYLAND=1 啟動。
  • 如果情況變得更糟，請移除該設定並嘗試在 X11 工作階段下啟動。

Windows: WebView2 執行階段

在 Windows 上，SlopCode Desktop 需要 Microsoft Edge WebView2 Runtime。如果應用程式開啟後是空白視窗或無法啟動，請安裝或更新 WebView2 後重試。

Windows: 常見效能問題

如果你在 Windows 上遇到效能緩慢、檔案存取問題或終端機問題，請嘗試使用 WSL (Windows Subsystem for Linux)。WSL 提供了一個 Linux 環境，能更好地與 SlopCode 的功能相容。

通知不顯示

SlopCode Desktop 僅在以下情況下顯示系統通知：

  • 在作業系統設定中已為 SlopCode 啟用通知，且
  • 應用程式視窗未處於焦點狀態。

重設桌面應用程式儲存（最後手段）

如果應用程式無法啟動且你無法從 UI 內部清除設定，請重設桌面應用程式的儲存狀態。

  1. 退出 SlopCode Desktop。
  2. 找到並刪除以下檔案（它們位於 SlopCode Desktop 應用程式資料目錄中）：
  • slopcode.settings.dat（桌面預設伺服器 URL）
  • slopcode.global.dat 和 slopcode.workspace.*.dat（UI 狀態，如最近的伺服器/專案）

快速找到該目錄：

  • macOS: Finder -> Cmd+Shift+G -> ~/Library/Application Support（然後搜尋上述檔案名稱）
  • Linux: 在 ~/.local/share 下搜尋上述檔案名稱
  • Windows: 按 WIN+R -> %APPDATA%（然後搜尋上述檔案名稱）

取得幫助

如果你遇到 SlopCode 的問題：

  1. 在 GitHub 上回報問題

    回報 Bug 或請求功能的最佳方式是透過我們的 GitHub 儲存庫：

    github.com/grappeggia/slopcode/issues

    在建立新 Issue 之前，請先搜尋已有的 Issue，看看你的問題是否已被回報。

  2. 加入我們的 Discord

    如需即時幫助和社群討論，請加入我們的 Discord 伺服器：

    slopcode.dev/discord

常見問題

以下是一些常見問題及其解決方法。

SlopCode 無法啟動

  1. 檢查日誌中的錯誤訊息
  2. 嘗試使用 --print-logs 執行以在終端機中查看輸出
  3. 使用 slopcode upgrade 確保你使用的是最新版本

身分驗證問題

  1. 嘗試在 TUI 中使用 /connect 指令重新進行身分驗證
  2. 檢查你的 API 金鑰是否有效
  3. 確保你的網路允許連線到供應商的 API

模型不可用

  1. 檢查你是否已通過供應商的身分驗證
  2. 驗證設定中的模型名稱是否正確
  3. 某些模型可能需要特定的存取權限或訂閱

如果你遇到 ProviderModelNotFoundError，很可能是在某處錯誤地參考了模型。 模型應按如下方式參考：<providerId>/<modelId>

範例：

  • openai/gpt-4.1
  • openrouter/google/gemini-2.5-flash
  • slopcode/kimi-k2

要查看你有權存取哪些模型，請執行 slopcode models

ProviderInitError

如果你遇到 ProviderInitError，很可能是設定無效或已損壞。

要解決此問題：

  1. 首先，按照供應商指南驗證你的供應商是否已正確設定

  2. 如果問題仍然存在，請嘗試清除已儲存的設定：

    Terminal window
    rm -rf ~/.local/share/slopcode

    在 Windows 上，按 WIN+R 並刪除：%USERPROFILE%\.local\share\slopcode

  3. 在 TUI 中使用 /connect 指令重新與供應商進行身分驗證。

AI_APICallError 和供應商套件問題

如果你遇到 API 呼叫錯誤，可能是由於供應商套件過期導致的。SlopCode 會根據需要動態安裝供應商套件（OpenAI、Anthropic、Google 等）並將它們快取到本地。

要解決供應商套件問題：

  1. 清除供應商套件快取：

    Terminal window
    rm -rf ~/.cache/slopcode

    在 Windows 上，按 WIN+R 並刪除：%USERPROFILE%\.cache\slopcode

  2. 重新啟動 SlopCode 以重新安裝最新的供應商套件

這將強制 SlopCode 下載最新版本的供應商套件，通常可以解決模型參數和 API 變更帶來的相容性問題。

在 Linux 上複製/貼上不可用

Linux 使用者需要安裝以下剪貼簿工具之一，複製/貼上功能才能正常運作：

對於 X11 系統：

Terminal window
apt install -y xclip
# or
apt install -y xsel

對於 Wayland 系統：

Terminal window
apt install -y wl-clipboard

對於無頭環境：

Terminal window
apt install -y xvfb
# and run:
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0

SlopCode 會偵測你是否正在使用 Wayland 並優先使用 wl-clipboard，否則將按以下順序嘗試查找剪貼簿工具：xclip 和 xsel。