Если что-то не так

ZubrCode устроен как клиент и сервер: фоновая служба владеет сессиями, плагинами, разрешениями и другим состоянием. Сначала определите, где проблема — в клиенте, в общей службе или в конкретном проекте.

Проверьте фоновую службу

Покажите информацию о сервере:

zubrcode service status

Проверьте, что его API в порядке:

zubrcode api get /api/info

Если служба зависла или отвечает нехорошо — перезапустите её:

zubrcode service restart

Можно явно остановить и запустить:

zubrcode service stop
zubrcode service start

Разрешите origin браузера

Если браузерный клиент с другого origin не подключается из-за CORS, добавьте его в конфигурацию службы:

zubrcode service set cors http://192.168.1.10:3001
zubrcode service get cors

Указывайте точный origin по HTTP или HTTPS, с портом при необходимости, без пути и завершающего слэша. Несколько origin — списком через запятую одним аргументом:

zubrcode service set cors "http://192.168.1.10:3001, https://app.example.com"

Снять настройку: zubrcode service unset cors. Изменение конфигурации службы останавливает её; следующий запуск подхватит новую — запустите явно zubrcode service start.

Для сервера на переднем плане повторите --cors для каждого origin:

zubrcode serve --cors http://192.168.1.10:3001 --cors https://app.example.com

Логи

Путь к каталогу логов покажет:

zubrcode debug paths log

Следите за логом, воспроизводя проблему (в каталоге логов — файлы *.log):

tail -f "$(zubrcode debug paths log)"/*.log

В каждой строке есть идентификатор запуска run и поле role. Для активности сессий, провайдеров, плагинов, разрешений и инструментов ищите role=server:

grep 'role=server' "$(zubrcode debug paths log)"/*.log
grep 'run=8fc3b1d5' "$(zubrcode debug paths log)"/*.log

Профили CPU и памяти

На macOS и Linux работающему процессу можно подать сигнал, чтобы снять диагностику. PID фонового сервера — в ответе /api/info. SIGPROF снимает десятисекундный профиль CPU (файл cpu-<pid>-<timestamp>.cpuprofile в каталоге логов), SIGUSR1 — снимок кучи (heap-<pid>-<timestamp>.heapsnapshot):

kill -SIGPROF <pid>
kill -SIGUSR1 <pid>

Дождитесь CPU profile written или heap snapshot written в логе: запись укажет полный путь файла. Оба формата открываются в Chrome DevTools.

Служебные файлы

Все пути (данные, конфигурация, кеш, состояние, база) покажет:

zubrcode debug paths

Путь к базе данных — zubrcode debug paths db; переменная OPENCODE_DB переносит базу в другое место.

Частые ошибки

Сообщение или симптом	Что делать
«Нет ключа ZuBrIQ или он недействителен»	`zubrcode auth login zubriq` или задайте `ZUBRIQ_API_KEY` (ключ — zubriq.by/chat → Настройки → API-ключи)
«У организации закончился баланс или лимит ключа»	Пополните баланс: zubriq.by/chat → Настройки → Биллинг
`403 key not allowed to access model`	Ключ выпущен на уровень без этой модели: проверьте уровень ключа в настройках чата (API-ключи) или выберите `zubr-coder`
`zubrcode: command not found`	Добавьте `~/.local/bin` в `PATH` и откройте новый терминал
Не загружаются правила, команды или навыки	Проверьте путь и имя файла (Инструкции, Навыки); ID берутся из пути, регистр важен
Конфигурация не применяется	Посмотрите источники конфигурации — `zubrcode debug config`; более общие файлы перекрываются более локальными (Конфигурация)

Свой раннер

Симптом	Причина и что делать
`Вход не удался`	вход не подтверждён за 10 минут или нажата «Отмена» — запустите снова и откройте напечатанную ссылку (на любом устройстве) либо задайте `ZUBRIQ_API_KEY`
`Регистрация не удалась: консоль ответила 401`	ключ отозван или чужой — `zubrcode auth login zubriq` или новый ключ в кабинете
`… ответила 402` (`no_balance`)	на балансе организации нет средств — пополните его: zubriq.by/chat → Настройки → Биллинг
`… ответила 409`	у вас уже 3 живых сессии — остановите лишнюю в чате
`… ответила 503`	раннеры выключены в этой среде (стейдж) — используйте zubriq.by
`[relay] relay отверг подключение` в цикле	сессию остановили в чате или истёк её срок — перезапустите `zubrcode remote`
`локальный zubrcode serve не поднялся за минуту`	порт `4180` занят — задайте другой: `--port 4181`
в чате «Раннер на ZubrCode 1.x — обновите»	на машине старый ZubrCode — `zubrcode upgrade`, затем перезапустите `zubrcode remote`
в чате `403 key not allowed to access model`	ключ выпущен на уровень без `zubr-coder` — проверьте уровень ключа

Подробнее — Свой раннер.

Сообщить о проблеме

Когда проблема воспроизводится, приложите к обращению в поддержку:

вывод zubrcode --version;
вывод zubrcode service status;
самую короткую последовательность шагов, которая воспроизводит проблему;
что затронуто: общая служба, конкретный клиент или один проект;
подходящие строки лога с полями run и role.

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