docs/docs/uk/gateway/diagnostics.md

read_when	summary	title	x-i18n
Підготовка звіту про помилку або запиту на підтримку Налагодження аварійних завершень Gateway, перезапусків, тиску на пам’ять або завеликих корисних навантажень Перегляд того, які діагностичні дані записуються або приховуються	Створюйте діагностичні пакети Gateway для звітів про помилки, якими можна ділитися	Експорт діагностики	generated_at model provider source_hash source_path workflow 2026-05-03T18:32:10Z gpt-5.5 openai f6cf8e00fe8033e339b5c947ce3dd10fdee736048a358ad3a0c2ccb77e939f4b gateway/diagnostics.md 16

OpenClaw може створити локальний zip-архів діагностики для звітів про помилки. Він поєднує санітизований стан Gateway, справність, журнали, форму конфігурації та нещодавні події стабільності без payload.

Ставтеся до діагностичних пакетів як до секретів, доки не переглянете їх. Вони спроєктовані так, щоб пропускати або редагувати payload і облікові дані, але все одно узагальнюють локальні журнали Gateway і стан середовища виконання на рівні хоста.

Швидкий старт

openclaw gateway diagnostics export

Команда виводить шлях до записаного zip-архіву. Щоб вибрати шлях:

openclaw gateway diagnostics export --output openclaw-diagnostics.zip

Для автоматизації:

openclaw gateway diagnostics export --json

Команда чату

Власники можуть використовувати /diagnostics [note] у чаті, щоб запросити локальний експорт Gateway. Використовуйте це, коли помилка сталася в реальній розмові й потрібен один звіт для підтримки, який можна скопіювати та вставити:

1. Надішліть /diagnostics у розмові, де ви помітили проблему. Додайте коротку нотатку, якщо це допоможе, наприклад /diagnostics bad tool choice.
2. OpenClaw надсилає преамбулу діагностики й просить одне явне підтвердження exec. Підтвердження запускає openclaw gateway diagnostics export --json. Не підтверджуйте діагностику через правило allow-all.
3. Після підтвердження OpenClaw відповідає звітом для вставлення, який містить локальний шлях до пакета, підсумок маніфесту, нотатки про приватність і відповідні ідентифікатори сеансів.

У групових чатах власник усе ще може запускати /diagnostics, але OpenClaw не публікує діагностичні деталі назад у спільний чат. Він надсилає преамбулу, запити підтвердження, результат експорту Gateway і розбивку сеансів/потоків Codex власнику через приватний маршрут підтвердження. Група отримує лише коротке сповіщення про те, що діагностичний процес було надіслано приватно. Якщо OpenClaw не може знайти приватний маршрут до власника, команда завершується безпечною відмовою і просить власника запустити її з DM.

Коли активний сеанс OpenClaw використовує нативний OpenAI Codex harness, те саме підтвердження exec також охоплює завантаження відгуку OpenAI для потоків середовища виконання Codex, про які знає OpenClaw. Це завантаження є окремим від локального zip-архіву Gateway і з'являється лише для сеансів Codex harness. Перед підтвердженням запит пояснює, що підтвердження діагностики також надішле відгук Codex, але він не перелічує ідентифікатори сеансів або потоків Codex. Після підтвердження відповідь у чаті перелічує канали, ідентифікатори сеансів OpenClaw, ідентифікатори потоків Codex і локальні команди відновлення для потоків, надісланих на сервери OpenAI. Якщо ви відхилите або проігноруєте підтвердження, OpenClaw не запускає експорт, не надсилає відгук Codex і не виводить ідентифікатори Codex.

Це робить типовий цикл налагодження Codex коротким: помітили неправильну поведінку в Telegram, Discord або іншому каналі, запустили /diagnostics, один раз підтвердили, поділилися звітом із підтримкою, а потім локально запустили виведену команду codex resume <thread-id>, якщо хочете самостійно перевірити нативний потік Codex. Див. Codex harness для цього процесу перевірки.

Що містить експорт

Zip-архів містить:

• summary.md: зручний для читання огляд для підтримки.
• diagnostics.json: машинозчитуваний підсумок конфігурації, журналів, стану, справності та даних стабільності.
• manifest.json: метадані експорту й список файлів.
• Санітизовану форму конфігурації та несекретні деталі конфігурації.
• Санітизовані підсумки журналів і нещодавні відредаговані рядки журналів.
• Найкращі можливі знімки стану й справності Gateway.
• stability/latest.json: найновіший збережений пакет стабільності, коли доступний.

Експорт корисний навіть тоді, коли Gateway несправний. Якщо Gateway не може відповісти на запити стану або справності, локальні журнали, форма конфігурації та найновіший пакет стабільності все одно збираються, коли доступні.

Модель приватності

Діагностика спроєктована так, щоб нею можна було ділитися. Експорт зберігає операційні дані, які допомагають налагодженню, як-от:

• назви підсистем, ідентифікатори Plugin, ідентифікатори провайдерів, ідентифікатори каналів і налаштовані режими
• коди стану, тривалості, кількість байтів, стан черги та показники пам'яті
• санітизовані метадані журналів і відредаговані операційні повідомлення
• форму конфігурації та несекретні налаштування функцій

Експорт пропускає або редагує:

• текст чатів, промпти, інструкції, тіла webhook і результати інструментів
• облікові дані, API-ключі, токени, cookies і секретні значення
• необроблені тіла запитів або відповідей
• ідентифікатори облікових записів, ідентифікатори повідомлень, необроблені ідентифікатори сеансів, імена хостів і локальні імена користувачів

Коли повідомлення журналу схоже на текст payload користувача, чату, промпта або інструмента, експорт зберігає лише факт пропуску повідомлення та кількість байтів.

Реєстратор стабільності

Gateway за замовчуванням записує обмежений потік стабільності без payload, коли діагностику ввімкнено. Він призначений для операційних фактів, а не для вмісту.

Той самий діагностичний heartbeat записує зразки активності, коли Gateway продовжує працювати, але event loop Node.js або CPU здаються перевантаженими. Ці події diagnostic.liveness.warning містять затримку event loop, використання event loop, співвідношення ядер CPU та кількість активних/очікувальних/поставлених у чергу сеансів. Неактивні зразки залишаються в телеметрії на рівні info. Зразки активності стають попередженнями Gateway лише тоді, коли робота очікує або стоїть у черзі, або коли активна робота збігається зі сталою затримкою event loop. Тимчасові піки максимальної затримки під час загалом справної фонової роботи залишаються в журналах debug. Вони самі по собі не перезапускають Gateway.

Перевірити активний реєстратор:

openclaw gateway stability
openclaw gateway stability --type payload.large
openclaw gateway stability --json

Перевірити найновіший збережений пакет стабільності після фатального завершення, тайм-ауту завершення роботи або помилки запуску після перезапуску:

openclaw gateway stability --bundle latest

Створити zip-архів діагностики з найновішого збереженого пакета:

openclaw gateway stability --bundle latest --export

Збережені пакети розміщуються в ~/.openclaw/logs/stability/, коли події існують.

Корисні опції

openclaw gateway diagnostics export \
  --output openclaw-diagnostics.zip \
  --log-lines 5000 \
  --log-bytes 1000000

• --output <path>: записати в конкретний шлях zip-архіву.
• --log-lines <count>: максимальна кількість санітизованих рядків журналу для включення.
• --log-bytes <bytes>: максимальна кількість байтів журналу для перевірки.
• --url <url>: WebSocket URL Gateway для знімків стану й справності.
• --token <token>: токен Gateway для знімків стану й справності.
• --password <password>: пароль Gateway для знімків стану й справності.
• --timeout <ms>: тайм-аут знімків стану й справності.
• --no-stability-bundle: пропустити пошук збереженого пакета стабільності.
• --json: вивести машинозчитувані метадані експорту.

Вимкнути діагностику

Діагностику ввімкнено за замовчуванням. Щоб вимкнути реєстратор стабільності та збір діагностичних подій:

{
  diagnostics: {
    enabled: false,
  },
}

Вимкнення діагностики зменшує деталізацію звіту про помилку. Це не впливає на звичайне журналювання Gateway.

Пов'язане

• Перевірки справності
• CLI Gateway
• Протокол Gateway
• Журналювання
• Експорт OpenTelemetry — окремий процес для потокової передачі діагностики до колектора