Из документации по неполадкам

Как чинить типичные проблемы OpenCode

Официальные шаги восстановления для пустого окна рабочего стола, сломанного провайдера и отчётов антивируса Windows, которые всё ещё появляются в трекере задач. Делайте по порядку.

Рабочий стол не запускается

Большинство падений даёт плагин, испорченный кэш или свой URL сервера. Рядом по-прежнему CLI OpenCode.

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 нажмите имя сервера (точка статуса) и очистите URL сервера по умолчанию через Clear.
2. Удалите любой блок server.port или server.hostname из opencode.json и перезапустите.
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 при первом запуске распаковывает нативные зависимости во временный каталог. Эвристики принимают это за упакованное вредоносное ПО. Сопровождающие подписали CLI и рабочий стол с v1.3.4. Более поздние сборки npm на части машин всё равно срабатывали.

1. Берите подписанный exe рабочего стола со download.html, а не старую установку npm i -g opencode-ai.
2. Сверьте SHA256 файла opencode-desktop-win-x64.exe с 7e6e4bca1b243609172fa580520e72ed240627fc9c36a80763a6f29bd64b698f.
3. Если Defender уже отправил случайно названную DLL из Temp в карантин, восстанавливайте файл только после совпадения хеша, затем добавьте в исключения папку установки OpenCode (не весь Temp).
4. Не отключайте Smart App Control. SAC игнорирует исключения Defender. Настоящее исправление: подписанная сборка.
5. Если какое-то время нужно остаться на npm, закрепите известную рабочую версию, а не давайте автообновлению стянуть следующую. В трекере задач описано, как автообновление снова ломало рабочий pin.

Windows через WSL

1. Установите WSL по собственному руководству Microsoft.
2. В терминале WSL выполните скрипт установки, затем cd /mnt/c/Users/YourName/project и opencode.
3. Для Desktop плюс WSL: opencode serve --hostname 0.0.0.0 --port 4096, затем подключите приложение к http://localhost:4096. Задайте OPENCODE_SERVER_PASSWORD, когда слушаете 0.0.0.0.
4. Если диск Windows кажется медленным, держите клон на файловой системе Linux (например ~/code/).

Буфер обмена Linux и Wayland

1. X11: установите xclip или xsel.
2. Wayland: установите wl-clipboard. OpenCode предпочитает его, когда видит Wayland.
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.