跳到內容
OpenCode
app.header.homeapp.header.docs

故障排除

常見問題以及如何解決它們。

要調試 opencode 問題，請首先檢查其存儲在磁盤上的日誌和本地數據。

紀錄

日誌文件寫入：

  • macOS/Linux：~/.local/share/opencode/log/
  • Windows：按WIN+R並粘貼%USERPROFILE%\.local\share\opencode\log

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

您可以使用 --log-level 命令行選項設置日誌級別以獲取更詳細的調試信息。例如，opencode --log-level DEBUG。

存儲

opencode 將會話數據和其他應用程式數據存儲在磁盤上：

  • macOS/Linux：~/.local/share/opencode/
  • Windows：按WIN+R並粘貼%USERPROFILE%\.local\share\opencode

該目錄包含：

  • auth.json - 身份驗證數據，例如 API 密鑰、OAuth 令牌
  • log/ - 應用程式日誌
  • project/ - 項目特定數據，例如會話和消息數據
    • 如果項目位於 Git 存儲庫中，則它存儲在 ./<project-slug>/storage/ 中
    • 如果不是 Git 存儲庫，則存儲在 ./global/storage/ 中

桌面應用程式

opencode Desktop 在後台運行本地 opencode 服務器（opencode-cli sidecar）。大多數問題是由行為不當的插件、損壞的緩存或錯誤的服務器設置引起的。

快速檢查

  • 完全退出並重新啟動應用程式。
  • 如果應用程式顯示錯誤屏幕，請單擊“重新啟動”並複制錯誤詳細信息。
  • 僅限 macOS：OpenCode 菜單 -> 重新加載 Webview（如果 UI 為空白/凍結，則有幫助）。

禁用插件

如果桌面應用程式在啟動時崩潰、掛起或行為異常，請首先禁用插件。

檢查全局配置

打開全局配置文件並查找 plugin 密鑰。

  • macOS/Linux：~/.config/opencode/opencode.jsonc（或~/.config/opencode/opencode.json）
  • macOS/Linux（較舊的安裝）：~/.local/share/opencode/opencode.jsonc
  • Windows：按WIN+R並粘貼%USERPROFILE%\.config\opencode\opencode.jsonc

如果您配置了插件，請通過刪除密鑰或將其設置為空數組來暫時禁用它們：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [],
}

檢查插件目錄

opencode 還可以從磁盤加載本地插件。暫時將它們移開（或重命名文件夾）並重新啟動桌面應用程式：

  • 全局插件
    • macOS/Linux：~/.config/opencode/plugins/
    • Windows：按WIN+R並粘貼%USERPROFILE%\.config\opencode\plugins
  • 項目插件（僅當您使用每個項目配置時）
    • <your-project>/.opencode/plugins/

如果應用程式再次開始工作，請一次重新啟用一個插件，以找出導致問題的插件。

清除緩存

如果禁用插件沒有幫助（或者插件安裝被卡住），請清除緩存，以便 opencode 可以重建它。

  1. 完全退出 opencode Desktop。
  2. 刪除緩存目錄：
  • macOS：Finder -> Cmd+Shift+G -> 粘貼~/.cache/opencode
  • Linux：刪除~/.cache/opencode（或運行rm -rf ~/.cache/opencode）
  • Windows：按WIN+R並粘貼%USERPROFILE%\.cache\opencode
  1. 重新啟動 opencode 桌面。

修復服務器連接問題

opencode Desktop 可以啟動自己的本地服務器（默認）或連接到您配置的服務器 URL。

如果您看到 “連接失敗” 對話框（或者應用程式永遠無法通過啟動屏幕），請檢查自定義服務器 URL。

清除桌面默認服務器 URL

在主屏幕中，單擊服務器名稱（帶有狀態點）以打開服務器選取器。在“默認服務器”部分中，單擊“清除”。

從您的配置中刪除server.port / server.hostname

如果您的 opencode.json(c) 包含 server 部分，請將其暫時刪除並重新啟動桌面應用程式。

檢查環境變量

如果您在環境中設置了 OPENCODE_PORT，桌面應用程式將嘗試將該端口用於本地服務器。

  • 取消設置OPENCODE_PORT（或選擇一個空閒端口）並重新啟動。

Linux：Wayland / X11 問題

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

  • 如果您在 Wayland 上且應用程式空白/崩潰，請嘗試使用 OC_ALLOW_WAYLAND=1 啟動。
  • 如果這讓事情變得更糟，請將其刪除並嘗試在 X11 會話下啟動。

Windows：WebView2 運行時

在 Windows 上，opencode Desktop 需要 Microsoft Edge WebView2 運行時。如果應用程式打開為空白窗口或無法啟動，請安裝/更新 WebView2，然後重試。

Windows：一般性能問題

如果您在 Windows 上遇到性能緩慢、文件訪問問題或terminal問題，請嘗試使用WSL（適用於 Linux 的 Windows 子系統）。 WSL 提供了一個可以與 opencode 功能更加無縫協作的 Linux 環境。

通知不顯示

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

  • 在您的操作系統設置中啟用 opencode 通知，並且
  • 應用程式窗口未聚焦。

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

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

  1. 退出 opencode Desktop。
  2. 查找並刪除這些文件（它們位於 opencode Desktop 應用程式數據目錄中）：
  • opencode.settings.dat（桌面默認服務器 URL）
  • opencode.global.dat 和 opencode.workspace.*.dat（UI 狀態，如最近的服務器/項目）

快速找到目錄：

  • macOS：Finder -> Cmd+Shift+G -> ~/Library/Application Support（然後搜索上面的文件名）
  • Linux：在 ~/.local/share 下搜索上述文件名
  • Windows：按WIN+R -> %APPDATA%（然後搜索上面的文件名）

尋求幫助

如果您遇到 opencode 問題：

  1. 在 GitHub 上報告問題

    報告錯誤或請求功能的最佳方式是通過我們的 GitHub 存儲庫：

    github.com/anomalyco/opencode/issues

    在創建新問題之前，請搜索現有問題以查看您的問題是否已被報告。

  2. 加入我們的不和諧

    如需實時幫助和社區討論，請加入我們的 Discord 服務器：

    opencode.ai/discord

常見問題

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

opencode 無法啟動

  1. 檢查日誌中是否有錯誤消息
  2. 嘗試使用 --print-logs 運行以查看terminal 中的輸出
  3. 確保您擁有最新版本opencode upgrade

身份驗證問題

  1. 嘗試使用 TUI 中的 /connect 命令重新進行身份驗證
  2. 檢查您的 API 密鑰是否有效
  3. 確保您的網絡允許連接到提供商的 API

型號不可用

  1. 檢查您是否已通過提供商的身份驗證
  2. 驗證配置中的型號名稱是否正確
  3. 某些型號可能需要特定的訪問權限或訂閱

如果您遇到ProviderModelNotFoundError，您很可能是錯誤的 在某處引用模型。 模型應該像這樣引用：<providerId>/<modelId>

示例：

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

要了解您可以訪問哪些模型，請運行opencode models

提供者初始化錯誤

如果遇到 ProviderInitError，您的配置可能無效或損壞。

要解決這個問題：

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

  2. 如果問題仍然存在，請嘗試清除存儲的配置：

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

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

  3. 使用 TUI 中的 /connect 命令向您的提供商重新進行身份驗證。

AI_APICallError 和提供商套件問題

如果您遇到 API 調用錯誤，這可能是由於過時的提供商套件造成的。 opencode 根據需要動態安裝提供商套件（OpenAI、Anthropic、Google 等）並將其緩存在本地。

要解決提供商套件問題：

  1. 清除提供商套件緩存：

    Terminal window
    rm -rf ~/.cache/opencode

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

  2. 重新啟動 opencode 以重新安裝最新的提供商套件

這將強制 opencode 下載最新版本的提供商套件，這通常可以解決模型參數和 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

opencode 將檢測您是否使用 Wayland 並更喜歡 wl-clipboard，否則它將嘗試按 xclip 和 xsel 的順序查找剪貼板工具。