来自排查文档
修复常见的 OpenCode 问题
官方恢复步骤，覆盖桌面白屏、服务商失败，以及 issue tracker 上反复出现的 Windows 杀毒报告。请按顺序做。
Desktop 无法启动
大多数崩溃来自插件、损坏的缓存或自定义服务器 URL。sidecar 仍是 OpenCode CLI。
- 1. 完全退出再启动。如果看到错误屏幕，使用 Restart 并复制详情。
- 2. 在 macOS 上打开 OpenCode 菜单，界面空白或冻结时用 Reload Webview。
- 3. 打开
%USERPROFILE%\.config\opencode\opencode.jsonc（或 ~/.config/opencode/opencode.jsonc），把"plugin": []设好。 - 4. 把
%USERPROFILE%\.config\opencode\plugins以及任何.opencode/plugins/文件夹移开，再启动。 - 5. 删除
%USERPROFILE%\.cache\opencode（或 ~/.cache/opencode）缓存后再启动。 - 6. 在 Windows 上如果窗口是空白的，请安装或更新 Microsoft Edge WebView2。
Connection Failed 或启动画面卡住
- 1. 在 Home 屏幕点击服务器名（状态点），Clear 默认服务器 URL。
- 2. 从 opencode.json 删除任何
server.port或server.hostname块，再启动。 - 3. 如果
OPENCODE_PORT指向被占用的端口，请取消设置。
服务商错误
ProviderModelNotFoundError
- 1. 确认你已用
/connect完成认证。 - 2. 模型写成
provider/model，例如openai/gpt-4.1或openrouter/google/gemini-2.5-flash。 - 3. 运行
opencode models，选一个实际出现的名称。
ProviderInitError
- 1. 确认 opencode.json 里的服务商配置块。
- 2. 如果仍坏着，删除
%USERPROFILE%\.local\share\opencode（或 ~/.local/share/opencode）。 - 3. 再运行一次
/connect。
AI_APICallError
- 1. 清除
%USERPROFILE%\.cache\opencode里的服务商包缓存。 - 2. 重启，让 OpenCode 重新安装它缓存在本地的 OpenAI、Anthropic 或 Google 包。
Windows 杀毒与 Smart App Control
这类投诉会以 Wacatac、Kaspersky PDM 和 Event 3077 出现。OpenCode 首次启动时会把原生依赖解压到临时目录。启发式引擎把这当成加壳恶意软件。维护者从 v1.3.4 起为 CLI 和桌面签名。之后的 npm 构建仍会绊倒部分机器。
- 1. 优先使用 download.html 上已签名的桌面 exe，而不是较旧的
npm i -g opencode-ai安装。 - 2. 把
opencode-desktop-win-x64.exe的 SHA256 与7e6e4bca1b243609172fa580520e72ed240627fc9c36a80763a6f29bd64b698f比对。 - 3. 如果 Defender 已经隔离了 Temp 下随机命名的 DLL，只有哈希匹配后再还原该文件，然后把 OpenCode 安装文件夹（不是整个 Temp）加入排除项。
- 4. 不要关闭 Smart App Control。SAC 会忽略 Defender 排除项。真正的修复是已签名构建。
- 5. 如果暂时必须继续用 npm，请钉住已知可用的版本，别让 autoupdate 拉到下一版。issue tracker 记录过 autoupdate 再次弄坏已经钉住的可用版本。
通过 WSL 使用 Windows
- 1. 按 Microsoft 自己的指南安装 WSL。
- 2. 在 WSL 终端运行安装脚本，然后
cd /mnt/c/Users/YourName/project并运行opencode。 - 3. Desktop 加 WSL：运行
opencode serve --hostname 0.0.0.0 --port 4096，再把应用连到 http://localhost:4096。绑定 0.0.0.0 时请设置OPENCODE_SERVER_PASSWORD。 - 4. 如果 Windows 盘感觉慢，优先把克隆放在 Linux 文件系统下（例如 ~/code/）。
Linux 剪贴板与 Wayland
- 1. X11：安装 xclip 或 xsel。
- 2. Wayland：安装 wl-clipboard。检测到 Wayland 时 OpenCode 会优先用它。
- 3. Wayland 上窗口空白或崩溃：用
OC_ALLOW_WAYLAND=1启动。如果更糟，去掉该变量并改用 X11 会话。
入门文档里的最佳实践
- 提交 AGENTS.md
- 运行
/init后提交该文件，让每次会话都看到同样的架构说明。 - 先 Plan，再 Build
- 多文件改动时 Tab 进入 Plan。迭代计划。只有要写入时再 Tab 回 Build。
- 点名文件
- 用
@，不要说“那个认证文件”。入门示例指向 packages/functions 下的具体路径。 - 先看日志
- Windows：Win+R，然后打开
%USERPROFILE%\.local\share\opencode\log。macOS/Linux：~/.local/share/opencode/log/。使用opencode --log-level DEBUG或--print-logs。