Усунення несправностей

• model_not_found із локальним сервером у стилі MLX/vLLM → перевірте, що baseUrl містить /v1, api є "openai-completions" для бекендів /v1/chat/completions, а models.providers.<provider>.models[].id є простим локальним ідентифікатором провайдера. Виберіть його один раз із префіксом провайдера, наприклад mlx/mlx-community/Qwen3-30B-A3B-6bit; запис каталогу залиште як mlx-community/Qwen3-30B-A3B-6bit.
• messages[...].content: invalid type: sequence, expected a string → бекенд відхиляє структуровані частини вмісту Chat Completions. Виправлення: встановіть models.providers.<provider>.models[].compat.requiresStringContent: true.
• incomplete turn detected ... stopReason=stop payloads=0 → бекенд завершив запит Chat Completions, але не повернув видимого користувачу тексту асистента для цього ходу. OpenClaw один раз повторює replay-safe порожні OpenAI-сумісні ходи; сталі збої зазвичай означають, що бекенд видає порожній/нетекстовий вміст або пригнічує текст фінальної відповіді.
• прямі крихітні запити успішні, але запуски агента OpenClaw падають через аварії бекенду/моделі (наприклад Gemma в деяких збірках inferrs) → транспорт OpenClaw, імовірно, уже правильний; бекенд падає на більшій формі промпта runtime агента.
• збої зменшуються після вимкнення інструментів, але не зникають → схеми інструментів були частиною навантаження, але залишкова проблема все ще в місткості upstream-моделі/сервера або помилці бекенду.

1. Установіть compat.requiresStringContent: true для бекендів Chat Completions, які приймають лише рядки.
2. Установіть compat.supportsTools: false для моделей/бекендів, які не можуть надійно обробляти поверхню схем інструментів OpenClaw.
3. За можливості зменште навантаження промпта: менший bootstrap робочої області, коротша історія сесії, легша локальна модель або бекенд із сильнішою підтримкою довгого контексту.
4. Якщо крихітні прямі запити й далі проходять, а ходи агента OpenClaw досі падають усередині бекенду, розглядайте це як upstream-обмеження сервера/моделі й подайте туди відтворення з прийнятою формою payload.

• device identity required → незахищений контекст або відсутня автентифікація пристрою.
• origin not allowed → браузерний Origin відсутній у gateway.controlUi.allowedOrigins (або ви підключаєтеся з не-loopback походження браузера без явного allowlist).
• device nonce required / device nonce mismatch → клієнт не завершує challenge-based потік автентифікації пристрою (connect.challenge + device.nonce).
• device signature invalid / device signature expired → клієнт підписав неправильний payload (або застарілу часову мітку) для поточного handshake.
• AUTH_TOKEN_MISMATCH з canRetryWithDeviceToken=true → клієнт може виконати одну довірену повторну спробу з кешованим токеном пристрою.
• Ця повторна спроба з кешованим токеном повторно використовує кешований набір scope, збережений разом зі сполученим токеном пристрою. Виклики з явним deviceToken / явними scopes натомість зберігають запитаний набір scope.
• За межами цього шляху повторної спроби пріоритет автентифікації connect такий: спочатку явний спільний токен/пароль, потім явний deviceToken, потім збережений токен пристрою, потім bootstrap-токен.
• На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого {scope, ip} серіалізуються до того, як обмежувач записує збій. Тому дві погані одночасні повторні спроби від того самого клієнта можуть показати retry later на другій спробі замість двох простих невідповідностей.
• too many failed authentication attempts (retry later) від browser-origin loopback-клієнта → повторні збої від того самого нормалізованого Origin тимчасово заблоковані; інше localhost-походження використовує окремий bucket.
• повторні unauthorized після цієї повторної спроби → розходження спільного токена/токена пристрою; оновіть конфігурацію токена й за потреби повторно схваліть/ротируйте токен пристрою.
• gateway connect failed: → неправильний хост/порт/url-ціль.

• Gateway start blocked: set gateway.mode=local або existing config is missing gateway.mode → локальний режим Gateway не ввімкнено, або файл конфігурації було перезаписано й він утратив gateway.mode. Виправлення: задайте gateway.mode="local" у своїй конфігурації або повторно запустіть openclaw onboard --mode local / openclaw setup, щоб повторно проставити очікувану конфігурацію локального режиму. Якщо ви запускаєте OpenClaw через Podman, типовий шлях конфігурації: ~/.openclaw/openclaw.json.
• refusing to bind gateway ... without auth → прив’язка не до loopback без чинного шляху автентифікації Gateway (токен/пароль або trusted-proxy, де налаштовано).
• another gateway instance is already listening / EADDRINUSE → конфлікт порту.
• Other gateway-like services detected (best effort) → існують застарілі або паралельні юніти launchd/systemd/schtasks. Більшість налаштувань має тримати один Gateway на машину; якщо вам потрібно більше ніж один, ізолюйте порти + конфігурацію/стан/робочий простір. Див. /gateway#multiple-gateways-same-host.
• System-level OpenClaw gateway service detected від doctor → існує системний юніт systemd, тоді як сервіс рівня користувача відсутній. Видаліть або вимкніть дублікат перед тим, як дозволити doctor установити користувацький сервіс, або задайте OPENCLAW_SERVICE_REPAIR_POLICY=external, якщо системний юніт є потрібним supervisor.
• Gateway service port does not match current gateway config → установлений supervisor усе ще фіксує старий --port. Запустіть openclaw doctor --fix або openclaw gateway install --force, потім перезапустіть сервіс Gateway.

• Конфігурація не пройшла валідацію під час запуску, гарячого перезавантаження або запису, яким володіє OpenClaw.
• Запуск Gateway завершується закрито замість переписування openclaw.json.
• Гаряче перезавантаження пропускає недійсні зовнішні редагування та залишає поточну runtime-конфігурацію активною.
• Записи, якими володіє OpenClaw, відхиляють недійсні/руйнівні payload перед commit і зберігають .rejected.*.
• openclaw doctor --fix володіє ремонтом. Він може видалити не-JSON префікси або відновити останню відому справну копію, зберігаючи відхилений payload як .clobbered.*.

CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head
diff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"
openclaw config validate
openclaw doctor

• .clobbered.* існує → doctor зберіг зламане зовнішнє редагування під час ремонту активної конфігурації.
• .rejected.* існує → запис конфігурації, яким володіє OpenClaw, не пройшов перевірки схеми або clobber перед commit.
• Config write rejected: → запис намагався прибрати потрібну структуру, різко зменшити файл або зберегти недійсну конфігурацію.
• config reload skipped (invalid config): → пряме редагування не пройшло валідацію та було проігнороване запущеним Gateway.
• Invalid config at ... → запуск завершився помилкою до завантаження сервісів Gateway.
• missing-meta-vs-last-good, gateway-mode-missing-vs-last-good або size-drop-vs-last-good:* → запис, яким володіє OpenClaw, було відхилено, бо він утратив поля або розмір порівняно з останньою відомою справною резервною копією.
• Config last-known-good promotion skipped → кандидат містив замасковані placeholders секретів, як-от ***.

1. Запустіть openclaw doctor --fix, щоб doctor відремонтував конфігурацію з префіксом/clobbered або відновив останню відому справну.
2. Скопіюйте лише потрібні ключі з .clobbered.* або .rejected.*, потім застосуйте їх за допомогою openclaw config set або config.patch.
3. Запустіть openclaw config validate перед перезапуском.
4. Якщо редагуєте вручну, зберігайте повну конфігурацію JSON5, а не лише частковий об’єкт, який хотіли змінити.

• cron: scheduler disabled; jobs will not run automatically → Cron вимкнено.
• cron: timer tick failed → збій такту планувальника; перевірте помилки файлів/журналів/середовища виконання.
• heartbeat skipped з reason=quiet-hours → поза вікном активних годин.
• heartbeat skipped з reason=empty-heartbeat-file → HEARTBEAT.md існує, але містить лише порожні рядки / markdown-заголовки, тому OpenClaw пропускає виклик моделі.
• heartbeat skipped з reason=no-tasks-due → HEARTBEAT.md містить блок tasks:, але жодне із завдань не має виконуватися на цьому такті.
• heartbeat: unknown accountId → недійсний ідентифікатор облікового запису для цілі доставки Heartbeat.
• heartbeat skipped з reason=dm-blocked → ціль Heartbeat визначено як призначення в стилі DM, тоді як agents.defaults.heartbeat.directPolicy (або перевизначення для агента) встановлено в block.

• unknown command "browser" або unknown command 'browser' → вбудований Plugin браузера виключено через plugins.allow.
• інструмент браузера відсутній / недоступний, хоча browser.enabled=true → plugins.allow виключає browser, тому Plugin ніколи не завантажився.
• Failed to start Chrome CDP on port → процес браузера не вдалося запустити.
• browser.executablePath not found → налаштований шлях недійсний.
• browser.cdpUrl must be http(s) or ws(s) → налаштована CDP URL-адреса використовує непідтримувану схему, як-от file: або ftp:.
• browser.cdpUrl has invalid port → налаштована CDP URL-адреса має неправильний порт або порт поза допустимим діапазоном.
• Playwright is not available in this gateway build; '<feature>' is unsupported. → у поточному встановленні Gateway бракує основної залежності середовища виконання браузера; перевстановіть або оновіть OpenClaw, а потім перезапустіть Gateway. ARIA-знімки й базові знімки сторінок усе ще можуть працювати, але навігація, AI-знімки, знімки елементів за CSS-селектором і експорт PDF залишаються недоступними.

• Could not find DevToolsActivePort for chrome → Chrome MCP existing-session ще не зміг під’єднатися до вибраного каталогу даних браузера. Відкрийте сторінку інспектування браузера, увімкніть віддалене налагодження, тримайте браузер відкритим, схваліть перший запит на під’єднання, а потім повторіть спробу. Якщо стан входу не потрібен, надайте перевагу керованому профілю openclaw.
• No Chrome tabs found for profile="user" → профіль під’єднання Chrome MCP не має відкритих локальних вкладок Chrome.
• Remote CDP for profile "<name>" is not reachable → налаштована віддалена CDP-крапка недосяжна з хоста Gateway.
• Browser attachOnly is enabled ... not reachable або Browser attachOnly is enabled and CDP websocket ... is not reachable → профіль лише для під’єднання не має досяжної цілі, або HTTP-крапка відповіла, але CDP WebSocket все одно не вдалося відкрити.

• fullPage is not supported for element screenshots → запит знімка екрана поєднав --full-page з --ref або --element.
• element screenshots are not supported for existing-session profiles; use ref from snapshot. → виклики знімків екрана Chrome MCP / existing-session мають використовувати захоплення сторінки або --ref зі знімка, а не CSS --element.
• existing-session file uploads do not support element selectors; use ref/inputRef. → хукам завантаження Chrome MCP потрібні посилання зі знімка, а не CSS-селектори.
• existing-session file uploads currently support one file at a time. → надсилайте одне завантаження за виклик у профілях Chrome MCP.
• existing-session dialog handling does not support timeoutMs. → хуки діалогів у профілях Chrome MCP не підтримують перевизначення тайм-ауту.
• existing-session type does not support timeoutMs overrides. → пропустіть timeoutMs для act:type у профілях profile="user" / Chrome MCP existing-session або використовуйте керований/CDP-профіль браузера, коли потрібен власний тайм-аут.
• existing-session evaluate does not support timeoutMs overrides. → пропустіть timeoutMs для act:evaluate у профілях profile="user" / Chrome MCP existing-session або використовуйте керований/CDP-профіль браузера, коли потрібен власний тайм-аут.
• response body is not supported for existing-session profiles yet. → responsebody усе ще потребує керованого браузера або сирого CDP-профілю.
• застарілі перевизначення viewport / темного режиму / локалі / офлайн-режиму в attach-only або віддалених CDP-профілях → виконайте openclaw browser stop --browser-profile <name>, щоб закрити активний сеанс керування та звільнити стан емуляції Playwright/CDP без перезапуску всього Gateway.

openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode

Що перевірити:

• Якщо gateway.mode=remote, виклики CLI можуть спрямовуватися на віддалений сервіс, тоді як ваш локальний сервіс працює нормально.
• Явні виклики з --url не повертаються до збережених облікових даних.

Поширені сигнатури:

• gateway connect failed: → неправильна ціль URL.
• unauthorized → кінцева точка досяжна, але автентифікація неправильна.

openclaw config get gateway.bind
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow

Що перевірити:

• Прив’язування не до loopback (lan, tailnet, custom) потребують дійсного шляху автентифікації Gateway: автентифікації за спільним токеном/паролем або правильно налаштованого розгортання trusted-proxy не через loopback.
• Старі ключі на кшталт gateway.token не замінюють gateway.auth.token.

Поширені сигнатури:

• refusing to bind gateway ... without auth → прив’язування не до loopback без дійсного шляху автентифікації Gateway.
• Connectivity probe: failed, коли середовище виконання працює → Gateway активний, але недоступний з поточною автентифікацією/URL.

openclaw devices list
openclaw pairing list --channel <channel> [--account <id>]
openclaw logs --follow
openclaw doctor

Що перевірити:

• Очікувані схвалення пристроїв для панелі керування/nodes.
• Очікувані схвалення спарення DM після змін політики або ідентичності.

Поширені сигнатури:

• device identity required → автентифікація пристрою не задоволена.
• pairing required → відправника/пристрій потрібно схвалити.