---
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="/docs/opencode/official/00-getting-started/cli">
    CLI 报错时先回到命令入口和日志参数。
  </Card>
  <Card title="配置网络" href="/docs/opencode/official/05-security/network">
    provider 连接失败时，继续检查代理、NO_PROXY 和企业证书。
  </Card>
  <Card title="配置模型供应商" href="/docs/opencode/official/03-models/providers">
    provider 和模型 ID 问题从这里重新核对。
  </Card>
  <Card title="安装插件" href="/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/)
