04 - Устранение неполадок
OpenCode использует клиент-серверную архитектуру. Фоновый сервер владеет сессиями, плагинами, разрешениями и другим состоянием приложения. Начните с определения, находится ли проблема в клиенте, общем сервере или конкретном проекте.
Проверка фонового сервиса
Покажите текущую информацию о сервере:
opencode service status
Проверьте, что его API работает нормально:
opencode api get /api/info
Если сервис завис или работает некорректно, перезапустите его:
opencode service restart
Вы также можете остановить и запустить его явно:
opencode service stop opencode service start
Разрешение источника браузера
Если клиент браузера с другого источника не может подключиться из-за CORS, добавьте источник клиента в конфигурацию сервиса:
opencode service set cors http://192.168.1.10:3001 opencode service get cors
Используйте точный HTTP или HTTPS источник, включая порт при необходимости, без пути или завершающего слэша. Чтобы разрешить несколько источников, передайте разделённый запятыми список как один аргумент; пробелы вокруг каждого источника обрезаются:
opencode service set cors "http://192.168.1.10:3001, https://app.example.com"
service get cors выводит JSON-массив. Удалите настроенный список с помощью:
opencode service unset cors
Установка или удаление конфигурации сервиса останавливает фоновый сервис. Его следующий запуск подхватит новую конфигурацию; используйте opencode service start для явного запуска.
Для сервера в foreground повторите --cors для каждого дополнительного разрешённого источника:
opencode serve --cors http://192.168.1.10:3001 --cors https://app.example.com
С serve --service предоставленные флаги --cors переопределяют сохранённый список для этого процесса. Без этих флагов сервисный режим использует сохранённый список. CORS не изменяет адрес прослушивания и не обходит аутентификацию сервера.
Проверка API
Команда api использует локальное обнаружение сервиса и поток аутентификации. Она принимает либо HTTP-метод и путь, либо ID операции OpenAPI.
См. справку по API для всех конечных точек и ID операций.
Передайте тело JSON-запроса с помощью --data или -d, и добавьте заголовки с помощью --header или -H.
Чтение логов
Установленные сборки записывают логи в:
~/.local/share/opencode/log/opencode.log
Отслеживайте лог при воспроизведении проблемы:
tail -f ~/.local/share/opencode/log/opencode.log
Каждая строка включает ID процесса run и поле role. Используйте role=server для сессии, провайдера, плагина, разрешения и активности инструментов.
grep 'role=server' ~/.local/share/opencode/log/opencode.log grep 'run=8fc3b1d5' ~/.local/share/opencode/log/opencode.log
Создание снимка кучи
Создайте снимок памяти (кучи) работающего фонового сервера на любой платформе:
opencode debug heap-dump
Команда ждёт, пока снимок не будет завершён, затем выводит его путь:
/home/me/.local/share/opencode/log/heap-48213-2026-10-23T013012345Z.heapsnapshot
Запишите его в другое место с помощью --directory. Сервер создаст директорию, если её нет:
opencode debug heap-dump --directory ./snapshots
- Он использует только сервер, который уже запущен. Он никогда не запускает, не заменяет и не перезапускает его.
- Используйте --server <url>, чтобы захватить сервер, который вы запустили с opencode serve. Установите OPENCODE_PASSWORD, если он есть. --directory тогда — путь на машине сервера.
- Откройте файл в панели Memory Chrome DevTools.
В десктопном приложении
Запустите Capture heap snapshots из палитры команд. Он создаёт одну папку в вашей папке Загрузки со снимком каждой части приложения, а также разбивку памяти, которую снимок не может показать:
opencode-heap-2026-10-23T013012345Z/ memory.json где находится память, на процесс, в MiB: начните отсюда memory-infra.json трассировка дампа памяти Chromium; откройте в https://ui.perfetto.dev heap-48213-….heapsnapshot собственный сервер десктопа window-1-48390.heapsnapshot по одному на окно приложения main-48102.heapsnapshot главный процесс десктопа gpu.json GPU и драйвер manifest.json процессы, PIDs и память до и после; записывается последним
- Снимок кучи содержит только объекты JavaScript и страницу. Изображения, макет, композиторные слои и память GPU находятся в memory.json и memory-infra.json.
- Удалённые серверы не захватываются. Вместо этого используйте opencode debug heap-dump на той машине.
- Сервер записывает свой снимок прямо в папку, поэтому ничего большого не перемещается или не копируется.
- Вкладки браузера не включены, потому что их снимки содержат содержимое посещённых вами страниц.
Захват CPU и профилей памяти
На macOS и Linux вы можете отправить сигнал работающему процессу OpenCode для захвата диагностических данных. Получите PID фонового сервера с эндпоинта здоровья:
opencode api get /api/info
Используйте pid из ответа с одним из этих сигналов:
- SIGPROF захватывает десятисекундный CPU-профиль:kill -SIGPROF <pid>Результат записывается в директорию логов как cpu-<pid>-<timestamp>.cpuprofile.
- SIGUSR1 захватывает снимок памяти (кучи):kill -SIGUSR1 <pid>Результат записывается в директорию логов как heap-<pid>-<timestamp>.heapsnapshot.
Дождитесь CPU profile written или heap snapshot written в opencode.log перед открытием файла. Соответствующая запись лога включает его полный путь. Вы можете проверить оба типа файлов в Chrome DevTools.
Файлы сервиса
Общий сервер регистрирует себя по адресу:
~/.local/state/opencode/service.json
Его частная конфигурация сервиса хранится отдельно по адресу:
~/.config/opencode/service.json
База данных обычно находится по адресу:
~/.local/share/opencode/opencode.db
OPENCODE_DB может переопределить расположение базы данных.
Сообщение об ошибке
Включите следующее при сообщении о воспроизводимой проблеме:
- Вывод opencode --version
- Вывод opencode service status
- Наименьшую последовательность шагов, воспроизводящих проблему
- Затрагивает ли проблема общий сервис, конкретный клиент или один проект
- Соответствующие строки логов, включая их поля run и role
Удалите API-ключи, заголовки авторизации, запросы, содержимое файлов и другие конфиденциальные данные перед публикацией логов.
Сообщайте о воспроизводимых проблемах в GitHub Issues.