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

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

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

Для отладки проблем с 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 (помогает, если UI пустой/завис).

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

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

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

Откройте ваш глобальный файл конфигурации и найдите ключ 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 в настройках вашей ОС, и
  • окно приложения не в фокусе.

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

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

  1. Закройте OpenCode Desktop.
  2. Найдите и удалите эти файлы (они находятся в директории данных приложения OpenCode Desktop):
  • opencode.settings.dat (URL сервера по умолчанию для десктопа)
  • opencode.global.dat и opencode.workspace.*.dat (состояние UI, такое как недавние серверы/проекты)

Чтобы быстро найти директорию:

  • 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)

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

  2. Присоединяйтесь к нашему Discord

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

    opencode.ai/discord (opens in a new tab)

Распространённые проблемы

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

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

  • Проверьте логи на наличие сообщений об ошибках
  • Попробуйте запустить с --print-logs, чтобы увидеть вывод в терминале
  • Убедитесь, что у вас последняя версия с помощью 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

Если вы столкнулись с 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
# или
apt install -y xsel

Для систем Wayland:

apt install -y wl-clipboard

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

apt install -y xvfb
# и запустите:
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0

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

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