Русский
Документация
Устранение неполадок

Устранение неполадок

Типичные проблемы и способы их решения.

Для отладки проблем с OpenCode начните с проверки логов и локальных данных, которые он хранит на диске.

Логи

Файлы логов записываются в:

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

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

Вы можете задать уровень логирования с помощью параметра командной строки --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) в фоновом режиме. Большинство проблем вызвано неисправным плагином, повреждённым кэшем или неправильной настройкой сервера.

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

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

Отключение плагинов

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

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

Откройте файл глобальной конфигурации и найдите ключ 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 мог пересобрать его.

  1. Полностью закройте OpenCode Desktop.
  2. Удалите каталог кэша:
  • macOS: Finder -> Cmd+Shift+G -> вставьте ~/.cache/opencode
  • Linux: удалите ~/.cache/opencode (или выполните rm -rf ~/.cache/opencode)
  • Windows: нажмите WIN+R и вставьте %USERPROFILE%\.cache\opencode
  1. Перезапустите OpenCode Desktop.

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

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

Если вы видите диалог «Connection Failed» (или приложение так и не проходит дальше заставки), проверьте наличие пользовательского URL сервера.

Очистка URL сервера по умолчанию настольного приложения

На главном экране щёлкните по имени сервера (с индикатором состояния), чтобы открыть селектор серверов. В разделе Default server нажмите Clear.

Удалите 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 требует WebView2 Runtime от Microsoft Edge. Если приложение открывается с пустым окном или не запускается, установите/обновите WebView2 и попробуйте снова.

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

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

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

OpenCode Desktop показывает системные уведомления, только когда:

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

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

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

  1. Закройте OpenCode Desktop.
  2. Найдите и удалите эти файлы (они находятся в каталоге данных приложения 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:

  1. Сообщайте о проблемах на GitHub Лучший способ сообщить об ошибках или запросить функции — через наш репозиторий GitHub: github.com/anomalyco/opencode/issues (opens in a new tab) Прежде чем создавать новую задачу, поищите среди существующих задач, не сообщалось ли уже о вашей проблеме.
  2. Присоединяйтесь к нашему Discord Для помощи в реальном времени и обсуждения с сообществом присоединяйтесь к нашему серверу Discord: opencode.ai/discord (opens in a new tab)

Типичные проблемы

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

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

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

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

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

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

  1. Проверьте, что вы аутентифицировались у провайдера
  2. Убедитесь, что имя модели в вашей конфигурации указано правильно
  3. Некоторые модели могут требовать особого доступа или подписок

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

Примеры:

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

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

ProviderInitError

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

Чтобы решить это:

  1. Сначала проверьте, что ваш провайдер настроен правильно, следуя руководству по провайдерам

  2. Если проблема сохраняется, попробуйте очистить сохранённую конфигурацию:

    rm -rf ~/.local/share/opencode

    В Windows нажмите WIN+R и удалите: %USERPROFILE%\.local\share\opencode

  3. Повторно аутентифицируйтесь у вашего провайдера с помощью команды /connect в TUI.

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

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

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

  1. Очистите кэш пакетов провайдеров:

    rm -rf ~/.cache/opencode

    В Windows нажмите WIN+R и удалите: %USERPROFILE%\.cache\opencode

  2. Перезапустите opencode, чтобы переустановить последние пакеты провайдеров

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

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

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

Для систем X11:

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

Для систем Wayland:

apt install -y wl-clipboard

Для headless-окружений:

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.

Корпоративная версияWindows (WSL)