故障排查

日志与存储位置

内容	macOS/Linux 路径	Windows
日志	`~/.local/share/opencode/log/`（保留最近 10 个文件）	`%USERPROFILE%\.local\share\opencode\log`
应用数据	`~/.local/share/opencode/`（含 `auth.json`、`log/`、`project/`）	同上路径的 Windows 版本

--log-level DEBUG 获取更详细日志
project/ 下：Git 仓库项目存于 ./<project-slug>/storage/，非 Git 项目存于 ./global/storage/

opencode uninstall（--keep-config/--keep-data/--dry-run/--force）；桌面 App 走系统自带应用管理卸载。

快速检查：完全退出重启；macOS 可用 “Reload Webview” 修复空白/卡死 UI
怀疑插件问题：清空全局配置里的 plugin 字段，或临时移走 ~/.config/opencode/plugins/ 和项目级 .opencode/plugins/ 目录，逐个排查
清缓存：删除 ~/.cache/opencode
连接失败/卡在启动画面：检查是否配置了自定义 server URL（Home 页点服务器名→Server picker→Clear Default server），或 opencode.json(c) 里的 server 段，或环境变量 OPENCODE_PORT
Linux Wayland 问题：空白/崩溃时尝试 OC_ALLOW_WAYLAND=1，若更糟则切 X11
Windows：需要 WebView2 Runtime；性能问题优先切 WSL（见界面与客户端）
通知不显示：需 OS 级通知权限开启 + App 窗口未聚焦
最后手段：删除 opencode.settings.dat/opencode.global.dat/opencode.workspace.*.dat 重置桌面 App 状态

问题	排查步骤
无法启动	查日志 → `--print-logs` 看终端输出 → `opencode upgrade` 确认最新版
认证失败	TUI `/connect` 重新认证 → 检查 API Key 有效性 → 检查网络是否能访问该 Provider
模型不可用/ProviderModelNotFoundError	确认已认证该 Provider → 检查配置里模型名格式是否为 `<providerId>/<modelId>`（如 `openai/gpt-4.1`）→ 用 `opencode models` 查看实际可用模型
ProviderInitError	配置损坏，先核对 Provider 配置 → 仍不行则 `rm -rf ~/.local/share/opencode` 清空重来 → `/connect` 重新认证
AI_APICallError / provider 包问题	Provider 包（OpenAI/Anthropic/Google 等按需动态安装并缓存）过期，`rm -rf ~/.cache/opencode` 清缓存后重启，强制重装最新版
Linux 复制粘贴不工作	X11 装 `xclip`/`xsel`；Wayland 装 `wl-clipboard`；headless 环境用 `xvfb` + 虚拟 DISPLAY