Поиск неисправностей

Распространенные проблемы и способы их решения.

Чтобы устранить проблемы с opencode, начните с проверки журналов и локальных данных, которые он хранит на диске.

Журналы

Лог-файлы записываются в:

macOS/Linux: ~/.local/share/opencode/log/
Windows: нажмите WIN+R и вставьте %USERPROFILE%\.local\share\opencode\log.

Файлам журналов присваиваются имена с метками времени (например, 2025-01-09T123456.log), и сохраняются 10 последних файлов журналов.

Вы можете установить уровень журнала с помощью CLI-параметра --log-level, чтобы получить более подробную информацию об отладке. Например, opencode --log-level DEBUG.

Хранилище

opencode хранит данные сеанса и другие данные приложения на диске по адресу:

macOS/Linux: ~/.local/share/opencode/
Windows: нажмите WIN+R и вставьте %USERPROFILE%\.local\share\opencode.

Этот каталог содержит:

auth.json – данные аутентификации, такие как ключи API и токены OAuth.
log/ – журналы приложений.
project/ — данные, специфичные для проекта, такие как данные сеанса и сообщения.
- Если проект находится в репозитории Git, он хранится в ./<project-slug>/storage/.
- Если это не репозиторий Git, он хранится в ./global/storage/.

opencode Desktop запускает локальный сервер opencode (сопутствующий модуль opencode-cli) в фоновом режиме. Большинство проблем вызвано неправильно работающим плагином, поврежденным кешем или неверными настройками сервера.

Быстрые проверки

Полностью закройте и перезапустите приложение.
Если приложение отображает экран с ошибкой, нажмите Перезапустить и скопируйте сведения об ошибке.
Только для macOS: меню OpenCode -> Обновить веб-просмотр (помогает, если пользовательский интерфейс пуст или завис).

Отключить плагины

Если настольное приложение дает сбой при запуске, зависает или ведет себя странно, начните с отключения плагинов.

Проверьте глобальную конфигурацию

Откройте файл глобальной конфигурации и найдите ключ plugin.

macOS/Linux: ~/.config/opencode/opencode.jsonc (или ~/.config/opencode/opencode.json)
macOS/Linux (более ранние версии): ~/.local/share/opencode/opencode.jsonc
Windows: нажмите WIN+R и вставьте %USERPROFILE%\.config\opencode\opencode.jsonc.

Если у вас настроены плагины, временно отключите их, удалив ключ или установив для него пустой массив:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [],
}

Проверьте каталоги плагинов

opencode также может загружать локальные плагины с диска. Временно переместите их в сторону (или переименуйте папку) и перезапустите настольное приложение:

Глобальные плагины
- macOS/Linux: ~/.config/opencode/plugins/
- Windows: нажмите WIN+R и вставьте %USERPROFILE%\.config\opencode\plugins.
Плагины проекта (только если вы используете конфигурацию для каждого проекта)
- <your-project>/.opencode/plugins/

Если приложение снова начнет работать, повторно включите плагины по одному, чтобы определить, какой из них вызывает проблему.

Очистить кеш

Если отключение плагинов не помогает (или установка плагина зависла), очистите кеш, чтобы opencode мог его пересобрать.

Полностью закройте opencode Desktop.
Удалите каталог кэша:

macOS: Finder -> Cmd+Shift+G -> вставить ~/.cache/opencode.
Linux: удалите ~/.cache/opencode (или запустите rm -rf ~/.cache/opencode).
Windows: нажмите WIN+R и вставьте %USERPROFILE%\.cache\opencode.

Перезапустите рабочий стол opencode.

Исправить проблемы с подключением к серверу

opencode Desktop может либо запустить собственный локальный сервер (по умолчанию), либо подключиться к настроенному вами URL-адресу сервера.

Если вы видите диалоговое окно Ошибка подключения (или приложение никогда не выходит за пределы заставки), проверьте URL-адрес пользовательского сервера.

Очистите URL-адрес сервера по умолчанию для рабочего стола.

На главном экране щелкните имя сервера (с точкой состояния), чтобы открыть окно выбора сервера. В разделе Сервер по умолчанию нажмите Очистить.

Удалите `server.port`/`server.hostname` из вашей конфигурации.

Если ваш opencode.json(c) содержит раздел server, временно удалите его и перезапустите настольное приложение.

Проверьте переменные среды

Если в вашей среде установлен OPENCODE_PORT, настольное приложение попытается использовать этот порт для локального сервера.

Отмените настройку OPENCODE_PORT (или выберите свободный порт) и перезапустите.

Linux: проблемы с Wayland/X11

В Linux некоторые настройки Wayland могут вызывать пустые окна или ошибки компоновщика.

Если вы используете Wayland, а приложение не работает или вылетает, попробуйте запустить с помощью OC_ALLOW_WAYLAND=1.
Если это усугубляет ситуацию, удалите его и попробуйте вместо этого запустить сеанс X11.

Windows: среда выполнения WebView2.

В Windows для opencode Desktop требуется Microsoft Edge WebView2 Runtime. Если приложение открывается в пустом окне или не запускается, установите/обновите WebView2 и повторите попытку.

Windows: общие проблемы с производительностью

Если вы испытываете низкую производительность, проблемы с доступом к файлам или проблемы с terminal в Windows, попробуйте использовать WSL (подсистема Windows для Linux). WSL предоставляет среду Linux, которая более эффективно работает с функциями opencode.

Уведомления не отображаются

opencode Desktop отображает системные уведомления только в следующих случаях:

уведомления для opencode включены в настройках вашей ОС, и
окно приложения не в фокусе.

Сбросить хранилище настольных приложений (последнее средство)

Если приложение не запускается и вы не можете очистить настройки из пользовательского интерфейса, сбросьте сохраненное состояние настольного приложения.

Закройте рабочий стол opencode.
Найдите и удалите эти файлы (они находятся в каталоге данных приложения opencode Desktop):

opencode.settings.dat (URL-адрес сервера по умолчанию для рабочего стола)
opencode.global.dat и opencode.workspace.*.dat (состояние пользовательского интерфейса, например, недавние серверы/проекты)

Чтобы быстро найти каталог:

macOS: Finder -> Cmd+Shift+G -> ~/Library/Application Support (затем найдите имена файлов, указанные выше)
Linux: найдите в ~/.local/share имена файлов, указанные выше.
Windows: нажмите WIN+R -> %APPDATA% (затем найдите имена файлов, указанные выше).

Получение помощи

Если у вас возникли проблемы с opencode:

Сообщайте о проблемах на GitHub

Лучший способ сообщить об ошибках или запросить новые функции — через наш репозиторий GitHub:

github.com/anomalyco/opencode/issues

Прежде чем создавать новую проблему, выполните поиск по существующим проблемам, чтобы узнать, не сообщалось ли уже о вашей проблеме.
Присоединяйтесь к нашему Discord

Для получения помощи в режиме реального времени и обсуждения в сообществе присоединяйтесь к нашему серверу Discord:

opencode.ai/discord

Общие проблемы

Вот некоторые распространенные проблемы и способы их решения.

opencode не запускается

Проверьте журналы на наличие сообщений об ошибках
Попробуйте запустить --print-logs, чтобы увидеть вывод в terminal.
Убедитесь, что у вас установлена последняя версия opencode upgrade.

Проблемы аутентификации

Попробуйте выполнить повторную аутентификацию с помощью команды /connect в TUI.
Убедитесь, что ваши ключи API действительны
Убедитесь, что ваша сеть разрешает подключения к API провайдера.

Модель недоступна

Убедитесь, что вы прошли аутентификацию у провайдера
Проверьте правильность названия модели в вашей конфигурации.
Для некоторых моделей может потребоваться специальный доступ или подписка.

Если вы столкнулись с ProviderModelNotFoundError, вы, скорее всего, ошибаетесь. ссылка на модель где-то. На модели следует ссылаться следующим образом: <providerId>/<modelId>.

Примеры:

openai/gpt-4.1
openrouter/google/gemini-2.5-flash
opencode/kimi-k2

Чтобы выяснить, к каким моделям у вас есть доступ, запустите opencode models.

Провидеринитеррор

Если вы столкнулись с ошибкой ProviderInitError, скорее всего, у вас неверная или поврежденная конфигурация.

Чтобы решить эту проблему:

Сначала убедитесь, что ваш провайдер настроен правильно, следуя руководству провайдеров
Если проблема не устранена, попробуйте очистить сохраненную конфигурацию:
Окно терминала
```
rm -rf ~/.local/share/opencode
```
В Windows нажмите WIN+R и удалите: %USERPROFILE%\.local\share\opencode.
Повторно выполните аутентификацию у своего провайдера, используя команду /connect в TUI.

AI_APICallError и проблемы с пакетом провайдера

Если вы столкнулись с ошибками вызова API, это может быть связано с устаревшими пакетами провайдера. opencode динамически устанавливает пакеты провайдеров (OpenAI, Anthropic, Google и т. д.) по мере необходимости и кэширует их локально.

Чтобы решить проблемы с пакетом поставщика:

Очистите кеш пакетов провайдера:
Окно терминала
```
rm -rf ~/.cache/opencode
```
В Windows нажмите WIN+R и удалите: %USERPROFILE%\.cache\opencode.
Перезапустите opencode, чтобы переустановить последние пакеты поставщиков.

Это заставит opencode загружать самые последние версии пакетов провайдеров, что часто решает проблемы совместимости с параметрами модели и изменениями API.

Копирование/вставка не работает в Linux

Для работы функций копирования/вставки пользователям Linux необходимо установить одну из следующих утилит буфера обмена:

Для систем X11:

apt install -y xclip
# or
apt install -y xsel

Для систем Wayland:

apt install -y wl-clipboard

Для безголовых сред:

apt install -y xvfb
# and run:
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0

opencode определит, используете ли вы Wayland и предпочитаете wl-clipboard, в противном случае он попытается найти инструменты буфера обмена в порядке: xclip и xsel.