故障排查

先记录错误和环境，再定位认证、模型、插件或本地服务。缓存目录、凭据与会话数据目录用途不同，不应遇到任何错误就清空全部数据。

日志与本地数据

平台	日志目录	应用数据目录
macOS/Linux	~/.local/share/opencode/log/	~/.local/share/opencode/
Windows	%USERPROFILE%\.local\share\opencode\log	%USERPROFILE%\.local\share\opencode

日志使用时间戳命名，保留最近 10 个文件。opencode --log-level DEBUG 增加细节，启动问题可用 --print-logs 查看终端输出。

应用数据中的 auth.json 保存 API Key、OAuth token 等认证信息；官方排障页还列出 project/ 的会话与消息数据。处理或分享诊断材料前应识别这些文件的用途。

CLI 启动、认证与模型

启动失败先读日志，必要时使用 opencode upgrade 更新。认证失败时在 TUI 重试 /connect，检查密钥有效性和到提供商 API 的网络连接。

遇到 ProviderModelNotFoundError，检查配置是否使用 <providerId>/<modelId>，并运行 opencode models 查看可用项。正确名称仍不等于账户拥有对应订阅或访问权限。

ProviderInitError 可能来自无效或损坏的配置，应先检查提供商设置。官方还给出删除应用数据后重新认证的最后处理方式，但该目录含凭据及会话数据；如需重置，应先保存需要保留的数据并确认影响。

AI_APICallError 也可能与缓存的提供商包不兼容有关。官方说明提供商包按需安装并缓存，可清理 ~/.cache/opencode 后重启重新获取；Windows 对应 %USERPROFILE%\.cache\opencode。这与删除应用数据目录不同。

桌面应用先做可逆隔离

桌面应用后台运行 opencode-cli sidecar。先完全退出并重开；错误页可点击 Restart 并保存错误详情。macOS 的 OpenCode → Reload Webview 可用于界面空白或冻结。

怀疑插件时：

1. 检查全局 ~/.config/opencode/opencode.jsonc 或 opencode.json，暂时移除 plugin 键或设为空数组。
2. 检查 ~/.config/opencode/plugins/ 与项目 .opencode/plugins/，暂时移走或重命名本地插件目录。
3. 重启验证，恢复时逐个启用以找到问题来源。

Windows 全局配置和插件目录位于 %USERPROFILE%\.config\opencode 下。较旧安装还可能在 ~/.local/share/opencode/opencode.jsonc 保留全局配置。

桌面连接失败

桌面默认可自行启动本地服务，也可以连接自定义服务地址。出现 Connection Failed 或持续停留启动页时：

• 在 Home 页点击带状态点的服务名称，在 Server picker 的 Default server 中选择 Clear。
• 暂时移除配置中的 server.port、server.hostname 再重启。
• 检查 OPENCODE_PORT 是否强制了已占用端口，取消它或改用空闲端口。

仍无法从 UI 修复时，官方列出重置桌面保存状态的最后手段：退出后处理 opencode.settings.dat、opencode.global.dat 和 opencode.workspace.*.dat。它们分别涉及默认服务及最近服务/项目等 UI 状态；macOS 在 ~/Library/Application Support 下查找，Linux 在 ~/.local/share 下查找，Windows 在 %APPDATA% 下查找。

平台与通知

Linux Wayland 白屏或崩溃时，官方建议尝试 OC_ALLOW_WAYLAND=1；若更差则去掉它并尝试 X11 会话。Windows 桌面需要 WebView2 Runtime，文件与终端性能问题可尝试 WSL。

Linux 剪贴板工具按环境选择：Wayland 使用 wl-clipboard，X11 使用 xclip 或 xsel。OpenCode 会优先检测 Wayland 的工具，否则按 xclip、xsel 顺序查找；无图形环境的虚拟显示方案见官方排障原文。

桌面系统通知需要操作系统允许 OpenCode 通知，并且应用窗口当前未聚焦。若问题仍未解决，先搜索官方仓库已有 Issue，再附有用的错误信息与复现步骤反馈。