---
title: "排查故障"
description: "彙總 OpenCode 常見故障的排查順序，覆蓋安裝、認證、模型、工具和終端問題。"
verifiedAt: "2026-05-09"
---

排查 OpenCode 不要一上來刪配置、清快取、重灌。先判斷故障發生在哪一層：CLI/TUI、Desktop、本地資料、provider、模型、網路、外掛，還是作業系統依賴。

> [!NOTE]
> **這一篇用 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 |

> [!IMPORTANT]
> 清快取和刪除本地資料不是第一步。`~/.local/share/opencode` 裡有 auth、日誌、會話和專案資料；刪除前先確認你要丟掉什麼。

## 排障總流程

```mermaid
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
```

不要跳過日誌。沒有錯誤資訊時，很多“修復”只是碰運氣。

> [!TIP]
> **`--pure` 是排障第一招**：`opencode --pure` 啟動時不載入外部外掛，等於"裸 OpenCode"。如果 `--pure` 跑得通，問題大機率在你裝的某個外掛裡；如果 `--pure` 也不行，再往下看本機環境、provider 和網路。

## 日誌和本地資料在哪裡

日誌目錄：

- macOS / Linux：`~/.local/share/opencode/log/`
- Windows：按 `WIN+R`，貼上 `%USERPROFILE%\.local\share\opencode\log`

OpenCode 會保留最近 10 個日誌檔案，檔名帶時間戳。需要更詳細日誌時：

```bash
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 問題通常來自三類：外掛異常、快取損壞、伺服器設定錯誤。

先做快速檢查：

1. 完全退出並重新開啟 Desktop。
2. 如果有錯誤頁面，點選 Restart 並複製錯誤詳情。
3. macOS 上 UI 空白或凍結時，嘗試 `OpenCode` 選單裡的 Reload Webview。

再停用外掛：

```jsonc
{
  "$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`。如果埠被佔用，取消設定或換空閒埠。

如果停用外掛還不行，再清快取：

```bash
rm -rf ~/.cache/opencode
```

Windows 對應目錄是 `%USERPROFILE%\.cache\opencode`。

## Provider 和模型問題

認證失敗時先重新連線：

```text
/connect
```

或用 CLI 檢查：

```bash
opencode auth list
opencode auth login
```

模型不可用時，先確認模型 ID 是完整格式：

```text
<providerId>/<modelId>
```

例如：

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

然後執行：

```bash
opencode models
opencode models --refresh
```

`ProviderModelNotFoundError` 通常說明 provider 沒連好、模型 ID 寫錯，或該賬號沒有模型許可權。

## ProviderInitError 和 API 呼叫錯誤

`ProviderInitError` 通常來自無效或損壞的 provider 配置。先按 provider 文件確認配置，再考慮清除本地資料。

> [!CAUTION]
> `rm -rf ~/.local/share/opencode` 會刪除本地 OpenCode 資料，包括認證和會話相關資料。只有在確認配置損壞、且能重新登入時再執行。

更低風險的第一步，是清 provider 包快取：

```bash
rm -rf ~/.cache/opencode
```

OpenCode 會按需動態安裝 provider 包。快取過舊時，可能出現模型引數或 API 變更導致的 `AI_APICallError`。清快取後重啟，OpenCode 會重新安裝最新 provider 包。

## 網路、代理和證書

如果 provider 連線失敗，但 key 和模型名都沒問題，檢查網路：

- 公司網路是否需要 `HTTPS_PROXY`。
- `localhost`、`127.0.0.1` 是否放進 `NO_PROXY`，避免本地 TUI/server 通訊被代理繞壞。
- 企業自籤 CA 是否需要 `NODE_EXTRA_CA_CERTS`。

最小代理形態：

```bash
export HTTPS_PROXY=https://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1
```

代理密碼不要寫進儲存庫或共享指令碼。

## Linux、Windows 和剪貼簿問題

Linux 複製/貼上不可用時，安裝對應工具：

```bash
sudo apt install -y xclip
sudo apt install -y xsel
sudo apt install -y wl-clipboard
```

無頭環境需要虛擬顯示：

```bash
sudo apt install -y xvfb
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0
```

**Wayland**（Linux 現代圖形伺服器協議，多數較新發行版預設用它，比傳統 X11 更安全也更年輕）空白或崩潰時，可以嘗試：

```bash
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` 或停用外掛復現。

官方反饋入口：

- [GitHub issues](https://github.com/anomalyco/opencode/issues)
- [OpenCode Discord](https://opencode.ai/discord)

## 接下來去哪

<Cards>
  <Card title="使用 CLI" href="/zh-Hant/docs/opencode/official/00-getting-started/cli">
    CLI 報錯時先回到命令入口和日誌引數。
  </Card>
  <Card title="配置網路" href="/zh-Hant/docs/opencode/official/05-security/network">
    provider 連線失敗時，繼續檢查代理、NO_PROXY 和企業證書。
  </Card>
  <Card title="配置模型供應商" href="/zh-Hant/docs/opencode/official/03-models/providers">
    provider 和模型 ID 問題從這裡重新核對。
  </Card>
  <Card title="安裝外掛" href="/zh-Hant/docs/opencode/official/02-agents-skills/plugins">
    如果停用外掛後恢復正常，回到外掛頁重新檢查載入和安全邊界。
  </Card>
</Cards>

## 官方資料

- [OpenCode troubleshooting](https://opencode.ai/docs/troubleshooting/)
- [OpenCode network](https://opencode.ai/docs/network/)
- [OpenCode providers](https://opencode.ai/docs/providers/)
- [OpenCode CLI](https://opencode.ai/docs/cli/)
