排查故障
汇总 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 问题从这里重新核对。
安装插件
如果禁用插件后恢复正常，回到插件页重新检查加载和安全边界。