排查故障
彙總 OpenCode 常見故障的排查順序，覆蓋安裝、認證、模型、工具和終端問題。
排查 OpenCode 不要一上來刪配置、清快取、重灌。先判斷故障發生在哪一層：CLI/TUI、Desktop、本地資料、provider、模型、網路、外掛，還是作業系統依賴。
這一篇用 12 分鐘換什麼：你會拿到一條可複用排障路徑，知道先看哪些日誌、什麼時候停用外掛、什麼時候清快取，以及哪些刪除命令會影響憑據和會話。
先給結論：先定位層級，再動手修
常見故障可以先按症狀歸類：
| 症狀 | 優先檢查 |
|---|---|
| CLI 無法啟動 | --print-logs、日誌目錄、版本 |
| Desktop 空白或卡住 | 外掛、快取、伺服器 URL、WebView2 |
| provider 登入失敗 | /connect、API key、網路、auth store |
| 模型不可用 | provider/model 名稱、opencode models、模型許可權 |
| API 呼叫報錯 | provider 包快取、網路、模型引數變化 |
| Linux 複製貼上異常 | xclip / xsel / wl-clipboard / Xvfb |
清快取和刪除本地資料不是第一步。~/.local/share/opencode 裡有 auth、日誌、會話和專案資料；刪除前先確認你要丟掉什麼。
排障總流程
flowchart TB
Problem[出現故障] --> Scope{發生在哪個入口}
Scope -->|CLI/TUI| Logs[看日誌和 --print-logs]
Scope -->|Desktop| Desktop[禁外掛 / 清快取 / 查 server URL]
Scope -->|Provider| Auth[重新 /connect 和 auth list]
Scope -->|Model| Models[opencode models / 檢查 provider/model]
Scope -->|Network| Net[代理 / NO_PROXY / 證書]
Scope -->|OS| OS[WebView2 / Wayland / 剪貼簿工具]
Logs --> Fix[按錯誤資訊修根因]
Desktop --> Fix
Auth --> Fix
Models --> Fix
Net --> Fix
OS --> Fix不要跳過日誌。沒有錯誤資訊時，很多“修復”只是碰運氣。
--pure 是排障第一招：opencode --pure 啟動時不載入外部外掛，等於"裸 OpenCode"。如果 --pure 跑得通，問題大機率在你裝的某個外掛裡；如果 --pure 也不行，再往下看本機環境、provider 和網路。
日誌和本地資料在哪裡
日誌目錄：
- macOS / Linux：
~/.local/share/opencode/log/ - Windows：按
WIN+R，貼上%USERPROFILE%\.local\share\opencode\log
OpenCode 會保留最近 10 個日誌檔案，檔名帶時間戳。需要更詳細日誌時：
opencode --log-level DEBUG
opencode --print-logs本地資料目錄：
- macOS / Linux：
~/.local/share/opencode/ - Windows：按
WIN+R，貼上%USERPROFILE%\.local\share\opencode
裡面通常包括：
auth.json：API key、OAuth token 等認證資料。log/：應用日誌。project/：專案會話、訊息和儲存資料。Git 儲存庫會進入專案 slug 下；非 Git 儲存庫會進入global/storage/。
Desktop 應用打不開或空白
OpenCode Desktop 後臺會啟動一個本地 OpenCode server，也就是 opencode-cli sidecar。Desktop 問題通常來自三類：外掛異常、快取損壞、伺服器設定錯誤。
先做快速檢查：
- 完全退出並重新開啟 Desktop。
- 如果有錯誤頁面，點選 Restart 並複製錯誤詳情。
- macOS 上 UI 空白或凍結時，嘗試
OpenCode選單裡的 Reload Webview。
再停用外掛：
{
"$schema": "https://opencode.ai/config.json",
"plugin": []
}同時檢查外掛目錄：
- 全域性外掛：
~/.config/opencode/plugins/ - 專案外掛：
<your-project>/.opencode/plugins/
臨時移走外掛目錄後重啟。如果恢復正常，再逐個啟用，找出導致問題的外掛。
Desktop 伺服器連線失敗
如果看到 Connection Failed，或 Desktop 一直停在啟動頁，檢查這三件事：
- 是否設定過自定義 server URL。可在 Home 頁面點選伺服器名稱，進入 Server picker 後清除預設伺服器。
opencode.json(c)裡是否寫了server.port或server.hostname。先臨時移除後重啟。- 環境變數裡是否設定了
OPENCODE_PORT。如果埠被佔用，取消設定或換空閒埠。
如果停用外掛還不行，再清快取：
rm -rf ~/.cache/opencodeWindows 對應目錄是 %USERPROFILE%\.cache\opencode。
Provider 和模型問題
認證失敗時先重新連線：
/connect或用 CLI 檢查：
opencode auth list
opencode auth login模型不可用時，先確認模型 ID 是完整格式：
<providerId>/<modelId>例如：
openai/gpt-4.1openrouter/google/gemini-2.5-flashopencode/kimi-k2
然後執行：
opencode models
opencode models --refreshProviderModelNotFoundError 通常說明 provider 沒連好、模型 ID 寫錯，或該賬號沒有模型許可權。
ProviderInitError 和 API 呼叫錯誤
ProviderInitError 通常來自無效或損壞的 provider 配置。先按 provider 文件確認配置，再考慮清除本地資料。
rm -rf ~/.local/share/opencode 會刪除本地 OpenCode 資料，包括認證和會話相關資料。只有在確認配置損壞、且能重新登入時再執行。
更低風險的第一步，是清 provider 包快取：
rm -rf ~/.cache/opencodeOpenCode 會按需動態安裝 provider 包。快取過舊時，可能出現模型引數或 API 變更導致的 AI_APICallError。清快取後重啟，OpenCode 會重新安裝最新 provider 包。
網路、代理和證書
如果 provider 連線失敗，但 key 和模型名都沒問題，檢查網路：
- 公司網路是否需要
HTTPS_PROXY。 localhost、127.0.0.1是否放進NO_PROXY，避免本地 TUI/server 通訊被代理繞壞。- 企業自籤 CA 是否需要
NODE_EXTRA_CA_CERTS。
最小代理形態：
export HTTPS_PROXY=https://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1代理密碼不要寫進儲存庫或共享指令碼。
Linux、Windows 和剪貼簿問題
Linux 複製/貼上不可用時，安裝對應工具：
sudo apt install -y xclip
sudo apt install -y xsel
sudo apt install -y wl-clipboard無頭環境需要虛擬顯示：
sudo apt install -y xvfb
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0Wayland（Linux 現代圖形伺服器協議，多數較新發行版預設用它，比傳統 X11 更安全也更年輕）空白或崩潰時，可以嘗試：
OC_ALLOW_WAYLAND=1 opencode如果更糟，移除這個變數，改用 X11 session（Linux 老牌圖形協議，相容性最好）。
Windows Desktop 空白或無法啟動時，先安裝或更新 Microsoft Edge WebView2 Runtime（Windows 上讓桌面應用嵌入 Chromium 網頁引擎的執行時；OpenCode Desktop 用它顯示介面，缺它就空白）。Windows 上檔案訪問、效能或終端異常較多時，優先切到 WSL（Windows Subsystem for Linux，微軟在 Windows 裡跑完整 Linux 核心的子系統）。
什麼時候重置 Desktop 儲存
這是最後手段。只有 Desktop 無法啟動，且你無法從 UI 內部清除設定時再做。
需要刪除的 Desktop 狀態檔案包括：
opencode.settings.dat：Desktop 預設 server URL。opencode.global.dat、opencode.workspace.*.dat：UI 狀態、最近 server 和專案。
查詢位置：
- macOS：
~/Library/Application Support - Linux：
~/.local/share - Windows：
%APPDATA%
刪除前先退出 OpenCode Desktop。
獲取幫助前準備什麼
提交 GitHub issue 或去 Discord 求助前，先準備這些資訊：
- OpenCode 版本：
opencode --version - 系統和終端環境。
- 你使用的是 CLI、TUI、Desktop、Web 還是 IDE。
- 最近一段日誌裡的錯誤資訊。
- 是否使用外掛、MCP、代理、自定義 server URL。
- provider 和模型 ID，但不要貼 API key。
- 能否用
--pure或停用外掛復現。
官方反饋入口：
接下來去哪
使用 CLI
CLI 報錯時先回到命令入口和日誌引數。
配置網路
provider 連線失敗時，繼續檢查代理、NO_PROXY 和企業證書。
配置模型供應商
provider 和模型 ID 問題從這裡重新核對。
安裝外掛
如果停用外掛後恢復正常，回到外掛頁重新檢查載入和安全邊界。