本页汇总 OpenCode 最常见的故障排查方法：查看日志文件、清理缓存、处理 ProviderInitError 和 AI_APICallError、修复 Linux 剪贴板问题，以及桌面端的插件排查和 WebView2 问题。遇到问题时，先看日志再动手是最省时的路径。

遇到问题时，先从日志文件入手，再按对应章节处理。

---

日志文件位置

系统	路径
macOS/Linux	~/.local/share/opencode/log/
Windows	按 Win+R 输入 %USERPROFILE%\.local\share\opencode\log

日志文件以时间戳命名（如 2025-01-09T123456.log），最多保留最近 10 个文件。

需要更详细的调试信息时，可以在启动时指定日志级别：

opencode --log-level DEBUG

---

本地数据存储位置

系统	路径
macOS/Linux	~/.local/share/opencode/
Windows	按 Win+R 输入 %USERPROFILE%\.local\share\opencode

目录结构：

• auth.json — API 密钥、OAuth token 等认证数据
• log/ — 应用日志
• project/ — 项目会话数据
  • Git 仓库内：./<project-slug>/storage/
  • 非 Git 目录：./global/storage/

---

桌面端故障排查

快速自查

• 完全退出后重新启动
• 如果出现错误屏幕，点击 Restart 并复制错误详情
• macOS 专属：OpenCode 菜单 → Reload Webview（解决界面空白/卡住问题）

---

插件导致的崩溃

启动后崩溃、卡住或行为异常，首先怀疑插件问题。

第一步：检查全局配置文件中的插件

打开配置文件（路径见下表），找到 plugin 字段，临时清空：

系统	配置路径
macOS/Linux	~/.config/opencode/opencode.jsonc
Windows	%USERPROFILE%\.config\opencode\opencode.jsonc

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

第二步：检查本地插件目录

目录	路径
全局插件 macOS/Linux	~/.config/opencode/plugins/
全局插件 Windows	%USERPROFILE%\.config\opencode\plugins
项目插件	<项目目录>/.opencode/plugins/

临时重命名整个文件夹，重启后确认是否恢复正常。逐一还原插件，定位问题插件。

---

清理缓存

插件排查无效，或插件安装卡住时，清除缓存后重启：

1. 完全退出桌面端
2. 删除缓存目录：
   • macOS：Finder → Cmd+Shift+G → ~/.cache/opencode
   • Linux：rm -rf ~/.cache/opencode
   • Windows：Win+R → %USERPROFILE%\.cache\opencode
3. 重启桌面端

---

服务器连接失败

出现 Connection Failed 弹窗或卡在启动画面时：

从界面清除自定义服务器 URL：主页 → 点击左上角服务器名称 → Default server 区域 → 点击 Clear

从配置文件移除 server 配置：如果 opencode.json 中有 server 字段，临时删除后重启。

检查环境变量：如果设置了 OPENCODE_PORT，桌面端会尝试连接该端口，确保端口未被占用或取消该变量。

---

Linux：Wayland / X11 问题

• 界面空白或崩溃：尝试加 OC_ALLOW_WAYLAND=1 启动
• 加了反而更差：去掉，改用 X11 会话运行

---

Windows：WebView2 运行时

Windows 桌面端依赖 Microsoft Edge WebView2 Runtime。空白窗口或无法启动时，安装/更新 WebView2 后重试。

---

常见错误解决

OpenCode 无法启动

1. 查看日志文件中的错误信息
2. 用 --print-logs 选项直接在终端查看输出
3. 执行 opencode upgrade 确保版本最新

---

认证失败

1. 在 TUI 中执行 /connect 重新认证
2. 检查 API 密钥是否有效
3. 确认网络允许连接到对应 provider 的 API

---

找不到模型（ProviderModelNotFoundError）

模型引用格式必须是 <providerId>/<modelId>：

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

运行 opencode models 查看当前账户可用的模型列表。

---

ProviderInitError

配置无效或被损坏时出现。

1. 参照 providers 文档 确认 provider 配置正确
2. 如果问题持续，清除已存储的配置数据后重新认证：

   rm -rf ~/.local/share/opencode

   Windows：Win+R → 删除 %USERPROFILE%\.local\share\opencode

---

AI_APICallError（provider 包版本问题）

OpenCode 会动态下载并缓存 provider 包（OpenAI、Anthropic、Google 等）。清除缓存可以强制重新下载最新版：

rm -rf ~/.cache/opencode

Windows：Win+R → 删除 %USERPROFILE%\.cache\opencode

清除后重启，OpenCode 会自动安装最新版 provider 包。

---

Linux 复制粘贴不可用

需要安装剪贴板工具：

X11 系统：

apt install -y xclip
# 或
apt install -y xsel

Wayland 系统：

apt install -y wl-clipboard

无头/远程环境：

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

OpenCode 会自动检测是否处于 Wayland 环境，优先使用 wl-clipboard，否则按顺序尝试 xclip 和 xsel。

---

寻求帮助

如果以上方法都无法解决问题：

• GitHub Issues：github.com/anomalyco/opencode/issues（提交前先搜索是否已有相同问题）
• Discord：opencode.ai/discord

---

常见问题

Q: 日志文件太多占空间怎么办？

A: OpenCode 自动只保留最近 10 个日志文件，不需要手动清理。如果你设置了 DEBUG 级别且日志量很大，可以临时切回默认级别。

Q: 清缓存后还是报 ProviderInitError，怎么办？

A: 在清除 ~/.local/share/opencode 之前，先备份 auth.json（里面有你的 API 密钥配置），清除后把备份恢复回去，避免重新填写密钥。

Q: Windows 桌面端白屏，安装 WebView2 后仍不行？

A: 先确认 WebView2 版本是否为最新（在 Windows 设置 → 应用中搜索"WebView2"）。如果已是最新，尝试重置桌面端存储文件（见上方"重置桌面端存储"步骤）。