From the troubleshooting doc

Fix common OpenCode problems

Official recovery steps for a blank desktop window, a failed provider, and the Windows antivirus reports that keep showing up on the issue tracker. Do them in order.

Desktop will not start

Most crashes are a plugin, a bad cache, or a custom server URL. The sidecar is still the OpenCode CLI.

1. Fully quit and relaunch. If you see an error screen, use Restart and copy the details.
2. On macOS use OpenCode menu, then Reload Webview when the UI is blank or frozen.
3. Open %USERPROFILE%\.config\opencode\opencode.jsonc (or ~/.config/opencode/opencode.jsonc) and set "plugin": [].
4. Move %USERPROFILE%\.config\opencode\plugins and any .opencode/plugins/ folder aside, then relaunch.
5. Delete the cache at %USERPROFILE%\.cache\opencode (or ~/.cache/opencode) and start again.
6. On Windows, if the window is blank, install or update Microsoft Edge WebView2.

Connection Failed or a stuck splash

1. On the Главная screen click the server name (status dot) and Clear the default server URL.
2. Remove any server.port or server.hostname block from opencode.json and relaunch.
3. Unset OPENCODE_PORT if it is pointing at a busy port.

Provider errors

ProviderModelNotFoundError

1. Check that you authenticated with /connect.
2. Reference models as provider/model, such as openai/gpt-4.1 or openrouter/google/gemini-2.5-flash.
3. Run opencode models and pick a name that actually appears.

ProviderInitError

1. Confirm the provider block in opencode.json.
2. If it stays broken, delete %USERPROFILE%\.local\share\opencode (or ~/.local/share/opencode).
3. Run /connect again.

AI_APICallError

1. Clear the provider package cache at %USERPROFILE%\.cache\opencode.
2. Restart so OpenCode reinstalls the OpenAI, Anthropic, or Google packages it caches locally.

Windows antivirus and Smart App Control

This is the complaint that shows up as Wacatac, Kaspersky PDM, and Event 3077. OpenCode extracts native dependencies into a temp directory on first launch. Heuristic engines treat that as packed malware. Maintainers signed CLI and desktop from v1.3.4. Later npm builds still tripped some machines.

1. Prefer the signed desktop exe from download.html over an older npm i -g opencode-ai drop.
2. Compare SHA256 of opencode-desktop-win-x64.exe to 7e6e4bca1b243609172fa580520e72ed240627fc9c36a80763a6f29bd64b698f.
3. If Defender already quarantined a randomly named DLL under Temp, restore that file only after the hash matches, then add the OpenCode install folder (not all of Temp) as an exclusion.
4. Do not disable Smart App Control. SAC ignores Defender exclusions. A signed build is the actual fix.
5. If you must stay on npm for a while, pin a known-good version instead of letting autoupdate pull the next one. The issue tracker documented autoupdate re-breaking a working pin.

Windows via WSL

1. Install WSL from Microsoft’s own guide.
2. In the WSL terminal run the install script, then cd /mnt/c/Users/YourName/project and opencode.
3. For Desktop plus WSL: opencode serve --hostname 0.0.0.0 --port 4096, then connect the app to http://localhost:4096. Set OPENCODE_SERVER_PASSWORD when you bind 0.0.0.0.
4. Prefer a clone under the Linux filesystem (for example ~/code/) when a Windows drive feels slow.

Linux clipboard and Wayland

1. X11: install xclip or xsel.
2. Wayland: install wl-clipboard. OpenCode prefers it when it detects Wayland.
3. Blank or crashing window on Wayland: launch with OC_ALLOW_WAYLAND=1. If that is worse, drop the variable and use an X11 session.

Best practices from the intro

Commit AGENTS.md: After /init, check the file in so every session sees the same architecture notes.
Plan, then Build: Tab into Plan for a multi-file change. Iterate on the plan. Tab back to Build only when you want writes.
Name the files: Use @ instead of “the auth file”. The intro example points at a concrete path under packages/functions.
Read the logs first: Windows: Win+R, then %USERPROFILE%\.local\share\opencode\log. macOS/Linux: ~/.local/share/opencode/log/. Use opencode --log-level DEBUG or --print-logs.