Неполадки

Агент не появляется в кабинете

1. api_url должен быть https://<хост-кабинета>/api/v1 без лишнего слэша в конце пути к sync — агент сам добавит /sync/.
2. Токен начинается с wgf_ и не отозван.
3. С машины агента: curl -I "$API_URL/health/" (ожидается ответ платформы).
4. В UI: Test now. unauthorized / forbidden — токен; unreachable — DNS, файрвол, неверный URL.

Online, но каталог пустой

Агент без плагинов шлёт heartbeat с resources: []. Нужен install плагина и enabled: true у source. wg-flow-agent dry-run печатает JSON, который ушёл бы в sync.

Offline через 5 минут

Кабинет считает агента offline, если last_seen_at старше 5 минут. Проверьте, что процесс run жив и интервал не больше разумного (heartbeat идёт по scheduler.sync_interval_seconds).

401 на sync после отзыва токена

Создайте новый токен, пропишите tenant_token, сохраните YAML. Старый wgf_… восстановить нельзя.

Плагин не ставится

plugin marketplace list должен видеть каталог. Агенту нужен тот же api_url / токен, что и для sync (маркетплейс за gateway). В пилоте wheel должен быть загружен в staff-админке.

UI «Failed to fetch»

UI слушает другой интерфейс, чем тот, что открыт в браузере. В Docker задайте WGFLOW_UI_HOST=0.0.0.0 и открывайте http://127.0.0.1:8765 с хоста, куда проброшен порт.

Как обновить агент

1. В локальном UI (0.2.0+) — баннер Update available и чип версии.
2. Docker: docker compose pull && docker compose up -d. YAML и каталог плагинов на volume сохраняются.
3. pip: скачайте новый wheel на Релизах и pip install --upgrade ./wg_flow_agent-…whl.
4. Агенты 0.1.0 баннер не показывают — смотрите страницу релизов вручную.