---
read_when:
    - Раздел устранения неполадок направил вас сюда для более глубокой диагностики
    - Вам нужны стабильные разделы руководства, структурированные по симптомам и содержащие точные команды
sidebarTitle: Troubleshooting
summary: Подробное руководство по устранению неполадок Gateway, каналов, автоматизации, узлов и браузера
title: Устранение неполадок
x-i18n:
    generated_at: "2026-07-13T18:11:03Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 24
    provider: openai
    source_hash: f53064a0d42e601ec1a1904fc9d0e8ebb9def7a2fb9d2579c7f10ca675b8f7fd
    source_path: gateway/troubleshooting.md
    workflow: 16
---

Это подробное руководство. Для быстрой первичной диагностики сначала перейдите к разделу [/help/troubleshooting](/ru/help/troubleshooting).

## Последовательность команд

Выполняйте в следующем порядке:

```bash
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
```

Признаки исправной работы:

- `openclaw gateway status` показывает `Runtime: running`, `Connectivity probe: ok` и строку `Capability: ...`.
- `openclaw doctor` не сообщает о блокирующих проблемах конфигурации или службы.
- `openclaw channels status --probe` показывает актуальное состояние транспорта для каждой учётной записи и, где поддерживается, `works` или `audit ok`.

## После обновления

Используйте этот раздел, если обновление завершилось, но Gateway не работает, каналы пусты или вызовы моделей завершаются ошибками 401.

```bash
openclaw status --all
openclaw update status --json
openclaw gateway status --deep
openclaw doctor --fix
openclaw gateway restart
```

Проверьте следующее:

- `Update restart` в `openclaw status` / `openclaw status --all`. Для ожидающих или неудачных передач указывается следующая команда, которую нужно выполнить.
- `plugin load failed: dependency tree corrupted; run openclaw doctor --fix` в разделе Channels: конфигурация канала по-прежнему существует, но регистрация плагина завершилась ошибкой до загрузки канала.
- Ошибки 401 провайдера после повторной аутентификации: `openclaw doctor --fix` проверяет устаревшие локальные для агентов копии данных OAuth-аутентификации и удаляет их, чтобы все агенты использовали текущий общий профиль.

## Конфликтующие установки и защита от более новой конфигурации

Используйте этот раздел, если служба Gateway неожиданно останавливается после обновления или журналы показывают, что один исполняемый файл `openclaw` старее версии, которая последней записала `openclaw.json`.

OpenClaw помечает записи конфигурации значением `meta.lastTouchedVersion`. Команды только для чтения могут просматривать конфигурацию, записанную более новой версией OpenClaw, однако более старый исполняемый файл отказывается выполнять изменения процессов и служб. Блокируются следующие действия: запуск, остановка, перезапуск и удаление службы Gateway, принудительная переустановка службы, запуск Gateway в режиме службы и очистка порта `gateway --force`.

```bash
which openclaw
openclaw --version
openclaw gateway status --deep
openclaw config get meta.lastTouchedVersion
```

<Steps>
  <Step title="Исправьте PATH">
    Исправьте `PATH`, чтобы `openclaw` указывал на более новую установку, а затем повторите действие.
  </Step>
  <Step title="Переустановите службу Gateway">
    Переустановите требуемую службу Gateway из более новой установки:

    ```bash
    openclaw gateway install --force
    openclaw gateway restart
    ```

  </Step>
  <Step title="Удалите устаревшие обёртки">
    Удалите устаревшие записи системного пакета или старых обёрток, которые всё ещё указывают на старый исполняемый файл `openclaw`.
  </Step>
</Steps>

<Warning>
Только для намеренного перехода на более раннюю версию или аварийного восстановления задайте `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1` для одной команды. При обычной работе не задавайте эту переменную.
</Warning>

## Несоответствие протокола после отката

Используйте этот раздел, если после перехода на более раннюю версию или отката в журналах продолжает появляться `protocol mismatch`. Работает более старый Gateway, но более новый локальный клиентский процесс продолжает переподключаться с диапазоном версий протокола, который этот Gateway не поддерживает.

```bash
openclaw --version
which -a openclaw
openclaw gateway status --deep
openclaw doctor --deep
openclaw logs --follow
```

Проверьте следующее:

- `protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n>` в журналах Gateway.
- `Established clients:` в `openclaw gateway status --deep` или `Gateway clients` в `openclaw doctor --deep`: активные TCP-клиенты, подключённые к порту Gateway, с PID и командными строками, если операционная система позволяет их получить.
- Клиентский процесс, командная строка которого указывает на более новую установку или обёртку OpenClaw, с которой был выполнен откат.

Исправление:

1. Остановите или перезапустите устаревший клиентский процесс OpenClaw, указанный в `gateway status --deep`.
2. Перезапустите приложения или обёртки со встроенным OpenClaw: локальные панели управления, редакторы, вспомогательные процессы серверов приложений или длительно работающие оболочки `openclaw logs --follow`.
3. Повторно выполните `openclaw gateway status --deep` или `openclaw doctor --deep` и убедитесь, что PID устаревшего клиента исчез.

Не пытайтесь заставить более старый Gateway принимать более новый несовместимый протокол. Повышение версии протокола защищает контракт обмена данными; восстановление после отката требует очистки процессов и версий.

## Символическая ссылка на Skill пропущена как выход за пределы пути

Используйте этот раздел, если журналы содержат:

```text
Пропуск пути Skill за пределами настроенного корневого каталога: ... причина=symlink-escape
```

Каждый корневой каталог Skill является границей изоляции. Символическая ссылка в `~/.agents/skills`, `<workspace>/.agents/skills`, `<workspace>/skills` или `~/.openclaw/skills` пропускается, если её фактическая цель находится за пределами этого корневого каталога, кроме случаев, когда цель явно объявлена доверенной.

Проверьте ссылку:

```bash
ls -l ~/.agents/skills/<name>
realpath ~/.agents/skills/<name>
openclaw config get skills.load
```

Если цель указана намеренно, настройте как непосредственный корневой каталог Skill, так и разрешённую цель символической ссылки:

```json5
{
  skills: {
    load: {
      extraDirs: ["~/Projects/manager/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
  },
}
```

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

Не используйте слишком широкие цели, например `~`, `/` или всю синхронизируемую папку проекта. Ограничьте `allowSymlinkTargets` фактическим корневым каталогом Skill, содержащим доверенные каталоги `SKILL.md`.

Если применение изменений в Skill Workshop также должно выполнять запись через эти доверенные символические ссылки на пути Skills в рабочем пространстве, включите `skills.workshop.allowSymlinkTargetWrites`. Оставьте этот параметр отключённым для общих корневых каталогов Skills, доступных только для чтения.

См. также:

- [Конфигурация Skills](/ru/tools/skills-config#symlinked-skill-roots)
- [Примеры конфигурации](/ru/gateway/configuration-examples#symlinked-sibling-skill-repo)

## Для длинного контекста Anthropic требуется дополнительное использование при ошибке 429

Используйте этот раздел, если журналы или сообщения об ошибках содержат: `HTTP 429: rate_limit_error: Extra usage is required for long context requests`.

```bash
openclaw logs --follow
openclaw models status
openclaw config get agents.defaults.models
```

Проверьте следующее:

- Выбранная модель Anthropic поддерживает общедоступный контекст 1M для Claude 4.x (Opus 4.6/4.7/4.8, Sonnet 4.6) либо конфигурация модели всё ещё содержит устаревший параметр `params.context1m: true`.
- Текущие учётные данные Anthropic не дают права использовать длинный контекст.
- Запросы завершаются ошибкой только в длинных сеансах или запусках модели, которым требуется контекст 1M.

Варианты исправления:

<Steps>
  <Step title="Используйте стандартное окно контекста">
    Переключитесь на модель со стандартным окном контекста или удалите устаревший параметр `context1m` из старой
    конфигурации модели, которая не поддерживает общедоступный контекст 1M.
  </Step>
  <Step title="Используйте подходящие учётные данные">
    Используйте учётные данные Anthropic, позволяющие выполнять запросы с длинным контекстом, или перейдите на ключ API Anthropic.
  </Step>
  <Step title="Настройте резервные модели">
    Настройте резервные модели, чтобы запуски продолжались при отклонении запросов Anthropic с длинным контекстом.
  </Step>
</Steps>

См. также:

- [Anthropic](/ru/providers/anthropic)
- [Использование токенов и затраты](/ru/reference/token-use)
- [Почему Anthropic возвращает HTTP 429?](/ru/help/faq-first-run#why-am-i-seeing-http-429-ratelimiterror-from-anthropic)

## Блокировка ответов 403 вышестоящей системой

Используйте этот раздел, если вышестоящий поставщик LLM возвращает общую ошибку `403`, например `Your request was blocked`.

Не предполагайте, что причина всегда заключается в конфигурации OpenClaw. Ответ может поступать от вышестоящего уровня безопасности, например CDN, WAF, правила управления ботами или обратного прокси перед конечной точкой, совместимой с OpenAI.

```bash
openclaw status
openclaw gateway status
openclaw logs --follow
```

Проверьте следующее:

- Несколько моделей одного поставщика завершаются одинаковой ошибкой.
- Вместо обычной ошибки API поставщика возвращается HTML или общий текст системы безопасности.
- На стороне поставщика зарегистрированы события безопасности с тем же временем запроса.
- Минимальный прямой запрос `curl` выполняется успешно, а обычные запросы в формате SDK завершаются ошибкой.

Если данные указывают на блокировку WAF/CDN, сначала исправьте фильтрацию на стороне поставщика. Предпочтительно настроить узкое правило разрешения или пропуска для пути API, который использует OpenClaw, и не отключать защиту для всего сайта.

<Warning>
Успешное выполнение минимального запроса `curl` не гарантирует, что реальные запросы в стиле SDK пройдут через тот же вышестоящий уровень безопасности.
</Warning>

См. также:

- [Конечные точки, совместимые с OpenAI](/ru/gateway/configuration-reference#openai-compatible-endpoints)
- [Настройка поставщиков](/ru/providers)
- [Журналы](/ru/logging)

## Локальный сервер, совместимый с OpenAI, проходит прямые проверки, но запуски агента завершаются ошибкой

Используйте этот раздел, если:

- `curl ... /v1/models` работает.
- Минимальные прямые вызовы `/v1/chat/completions` работают.
- Запуски моделей OpenClaw завершаются ошибкой только при обычных шагах агента.

```bash
curl http://127.0.0.1:1234/v1/models
curl http://127.0.0.1:1234/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"<id>","messages":[{"role":"user","content":"привет"}],"stream":false}'
openclaw infer model run --model <provider/model> --prompt "привет" --json
openclaw logs --follow
```

Проверьте следующее:

- Минимальные прямые вызовы выполняются успешно, но запуски OpenClaw завершаются ошибкой только при более крупных запросах.
- Ошибки `model_not_found` или 404, хотя прямой запрос `/v1/chat/completions` работает с тем же идентификатором модели без префикса.
- Ошибки сервера о том, что `messages[].content` должен быть строкой.
- Периодические предупреждения `incomplete turn detected ... stopReason=stop payloads=0` при использовании локального сервера, совместимого с OpenAI.
- Сбои сервера, возникающие только при большом числе токенов запроса или полных запросах среды выполнения агента.

<AccordionGroup>
  <Accordion title="Распространённые признаки">
    - `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`.
    - `validation.keys` или допустимые ключи сообщений, например `["role","content"]`: сервер отклоняет метаданные повторного воспроизведения в стиле OpenAI в сообщениях Chat Completions. Исправление: задайте `models.providers.<provider>.models[].compat.strictMessageKeys: true`.
    - `incomplete turn detected ... stopReason=stop payloads=0`: сервер обработал запрос Chat Completions, но не вернул видимого пользователю текста ассистента для этого шага. OpenClaw один раз повторяет безопасные для повторного воспроизведения пустые шаги, совместимые с OpenAI; постоянные ошибки обычно означают, что сервер возвращает пустое или нетекстовое содержимое либо подавляет текст окончательного ответа.
    - Минимальные прямые запросы выполняются успешно, но запуски агента OpenClaw приводят к сбоям сервера или модели (например, Gemma в некоторых сборках `inferrs`): вероятно, транспорт OpenClaw уже настроен правильно, а сервер не справляется с более сложной структурой запроса среды выполнения агента.
    - После отключения инструментов число ошибок уменьшается, но они не исчезают: схемы инструментов создавали часть нагрузки, однако оставшаяся проблема по-прежнему связана с ресурсами вышестоящей модели или сервера либо с ошибкой сервера.

  </Accordion>
  <Accordion title="Варианты исправления">
    1. Задайте `compat.requiresStringContent: true` для серверов Chat Completions, принимающих только строки.
    2. Задайте `compat.strictMessageKeys: true` для строгих серверов Chat Completions, которые принимают в каждом сообщении только `role` и `content`.
    3. Задайте `compat.supportsTools: false` для моделей или серверов, которые не могут надёжно обрабатывать схемы инструментов OpenClaw.
    4. По возможности снизьте нагрузку запросов: уменьшите начальный контекст рабочего пространства, сократите историю сеанса, используйте менее ресурсоёмкую локальную модель или сервер с более эффективной поддержкой длинного контекста.
    5. Если минимальные прямые запросы продолжают выполняться успешно, а шаги агента OpenClaw по-прежнему приводят к сбою внутри сервера, считайте это ограничением вышестоящего сервера или модели и отправьте его разработчикам пример воспроизведения с принятой структурой полезной нагрузки.
  </Accordion>
</AccordionGroup>

См. также:

- [Конфигурация](/ru/gateway/configuration)
- [Локальные модели](/ru/gateway/local-models)
- [OpenAI-совместимые конечные точки](/ru/gateway/configuration-reference#openai-compatible-endpoints)

## Нет ответов

Если каналы работают, но ничего не отвечает, проверьте маршрутизацию и политики, прежде чем что-либо переподключать.

```bash
openclaw status
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw config get channels
openclaw logs --follow
```

Проверьте:

- Ожидание сопряжения для отправителей личных сообщений.
- Ограничение по упоминанию в группе (`requireMention`, `mentionPatterns`).
- Несоответствия спискам разрешений канала или группы.

Распространённые признаки:

- `drop guild message (mention required` → сообщение группы игнорируется до упоминания.
- `pairing request` → отправителю требуется одобрение.
- `blocked` / `allowlist` → отправитель или канал отфильтрован политикой.

См. также:

- [Устранение неполадок каналов](/ru/channels/troubleshooting)
- [Группы](/ru/channels/groups)
- [Сопряжение](/ru/channels/pairing)

## Подключение панели управления и интерфейса управления

Если панель управления или интерфейс управления не подключается, проверьте URL, режим аутентификации и предположения о безопасном контексте.

```bash
openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json
```

Проверьте:

- Правильность URL проверки и URL панели управления.
- Несоответствие режима аутентификации или токена между клиентом и Gateway.
- Использование HTTP там, где требуется идентификация устройства.

Если после обновления локальный браузер не может подключиться к `127.0.0.1:18789`, сначала восстановите локальную службу Gateway и убедитесь, что она обслуживает панель управления:

```bash
openclaw gateway restart
lsof -i :18789
curl http://127.0.0.1:18789
```

Если `curl` возвращает HTML OpenClaw, Gateway работает, а оставшаяся проблема, вероятно, связана с кешем браузера, старой глубокой ссылкой или устаревшим состоянием вкладки. Откройте `http://127.0.0.1:18789` напрямую и переходите со страницы панели управления. Если после перезапуска служба не остаётся запущенной, выполните `openclaw gateway start` и снова проверьте `openclaw gateway status`.

<AccordionGroup>
  <Accordion title="Признаки проблем с подключением и аутентификацией">
    - `device identity required` → небезопасный контекст или отсутствие аутентификации устройства.
    - `origin not allowed` → браузерный `Origin` отсутствует в `gateway.controlUi.allowedOrigins` (либо подключение выполняется из браузера с источником не на loopback-интерфейсе без явного списка разрешений).
    - `device nonce required` / `device nonce mismatch` → клиент не завершает процедуру аутентификации устройства на основе запроса (`connect.challenge` + `device.nonce`).
    - `device signature invalid` / `device signature expired` → клиент подписал неверную полезную нагрузку (или использовал устаревшую временную метку) для текущего рукопожатия.
    - `AUTH_TOKEN_MISMATCH` с `canRetryWithDeviceToken=true` → клиент может выполнить одну доверенную повторную попытку с кешированным токеном устройства.
    - При этой повторной попытке с кешированным токеном повторно используется кешированный набор областей доступа, сохранённый вместе с токеном сопряжённого устройства. Вызывающие стороны, явно задающие `deviceToken` / `scopes`, вместо этого сохраняют запрошенный набор областей доступа.
    - `AUTH_SCOPE_MISMATCH` → токен устройства распознан, но его одобренные области доступа не охватывают этот запрос на подключение; повторно сопрягите устройство или одобрите запрошенный контракт областей доступа вместо ротации общего токена Gateway.
    - Вне этого пути повторной попытки приоритет аутентификации подключения таков: сначала явно заданный общий токен или пароль, затем явно заданный `deviceToken`, затем сохранённый токен устройства и, наконец, загрузочный токен.
    - В асинхронном пути интерфейса управления Tailscale Serve неудачные попытки для одного и того же `{scope, ip}` сериализуются до того, как ограничитель зарегистрирует сбой. Поэтому при двух одновременных неудачных повторных попытках одного клиента во второй попытке может появиться `retry later` вместо двух обычных сообщений о несоответствии.
    - `too many failed authentication attempts (retry later)` от loopback-клиента с браузерным источником → повторяющиеся сбои для того же нормализованного `Origin` временно блокируются; другой источник localhost использует отдельную корзину.
    - Повторяющийся `unauthorized` после этой повторной попытки → рассинхронизация общего токена и токена устройства; обновите конфигурацию токена и при необходимости повторно одобрите или ротируйте токен устройства.
    - `gateway connect failed:` → неверный целевой хост, порт или URL.

  </Accordion>
</AccordionGroup>

### Краткая карта кодов подробностей аутентификации

Используйте `error.details.code` из неудачного ответа `connect`, чтобы выбрать следующее действие:

| Код подробностей             | Значение                                                                                                                                                                                     | Рекомендуемое действие                                                                                                                                                                                                                                                                   |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_TOKEN_MISSING`         | Клиент не отправил обязательный общий токен.                                                                                                                                                 | Вставьте или задайте токен в клиенте и повторите попытку. Для путей панели управления: `openclaw config get gateway.auth.token`, затем вставьте его в настройки интерфейса управления.                                                                                                                           |
| `AUTH_TOKEN_MISMATCH`        | Общий токен не совпал с токеном аутентификации Gateway.                                                                                                                                      | Если `canRetryWithDeviceToken=true`, разрешите одну доверенную повторную попытку. При повторных попытках с кешированным токеном повторно используются сохранённые одобренные области доступа; вызывающие стороны с явными `deviceToken` / `scopes` сохраняют запрошенные области доступа. Если сбой сохраняется, выполните [контрольный список восстановления после рассинхронизации токенов](/ru/cli/devices#token-drift-recovery-checklist). |
| `AUTH_DEVICE_TOKEN_MISMATCH` | Кешированный токен отдельного устройства устарел или отозван.                                                                                                                               | Ротируйте или повторно одобрите токен устройства с помощью [CLI устройств](/ru/cli/devices), затем подключитесь снова.                                                                                                                                                                      |
| `AUTH_SCOPE_MISMATCH`        | Токен устройства действителен, но его одобренная роль или области доступа не охватывают этот запрос на подключение.                                                                          | Повторно сопрягите устройство или одобрите запрошенный контракт областей доступа; не рассматривайте это как рассинхронизацию общего токена.                                                                                                                                               |
| `PAIRING_REQUIRED`           | Идентификация устройства требует одобрения. Проверьте `error.details.reason` на наличие `not-paired`, `scope-upgrade`, `role-upgrade` или `metadata-upgrade` и используйте `requestId` / `remediationHint`, если они присутствуют. | Одобрите ожидающий запрос: `openclaw devices list`, затем `openclaw devices approve <requestId>`. Для повышения областей доступа или роли используется та же процедура после проверки запрошенного доступа.                                                                                                        |

<Note>
Прямые вызовы RPC локального серверного компонента через loopback-интерфейс, аутентифицированные общим токеном или паролем Gateway, не должны зависеть от базового набора областей доступа сопряжённого устройства CLI. Если субагенты или другие внутренние вызовы по-прежнему завершаются с ошибкой `scope-upgrade`, убедитесь, что вызывающая сторона использует `client.id: "gateway-client"` и `client.mode: "backend"` и не задаёт принудительно явный `deviceIdentity` или токен устройства.
</Note>

Проверка миграции аутентификации устройств v2:

```bash
openclaw --version
openclaw doctor
openclaw gateway status
```

Если в журналах отображаются ошибки одноразового значения или подписи, обновите подключающийся клиент и проверьте его:

<Steps>
  <Step title="Дождитесь connect.challenge">
    Клиент ожидает выданный Gateway `connect.challenge`.
  </Step>
  <Step title="Подпишите полезную нагрузку">
    Клиент подписывает полезную нагрузку, привязанную к запросу.
  </Step>
  <Step title="Отправьте одноразовое значение устройства">
    Клиент отправляет `connect.params.device.nonce` с тем же одноразовым значением запроса.
  </Step>
</Steps>

Если доступ к `openclaw devices rotate` / `revoke` / `remove` неожиданно отклонён:

- Сеансы с токеном сопряжённого устройства могут управлять только **собственным** устройством, если вызывающая сторона также не имеет `operator.admin`.
- `openclaw devices rotate --scope ...` может запрашивать только те операторские области доступа, которыми уже обладает сеанс вызывающей стороны.

См. также:

- [Конфигурация](/ru/gateway/configuration) (режимы аутентификации Gateway)
- [Интерфейс управления](/ru/web/control-ui)
- [Устройства](/ru/cli/devices)
- [Удалённый доступ](/ru/gateway/remote)
- [Аутентификация через доверенный прокси](/ru/gateway/trusted-proxy-auth)

## Служба Gateway не запущена

Используйте этот раздел, если служба установлена, но процесс не остаётся запущенным.

```bash
openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep   # также сканировать службы системного уровня
```

Проверьте:

- `Runtime: stopped` с подсказками о завершении.
- Несоответствие конфигурации службы (`Config (cli)` и `Config (service)`).
- Конфликты портов или прослушивателей.
- Дополнительные установки launchd/systemd/schtasks при использовании `--deep`.
- Подсказки по очистке `Other gateway-like services detected (best effort)`.

<AccordionGroup>
  <Accordion title="Распространённые признаки">
    - `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 (токен или пароль либо настроенный доверенный прокси).
    - `another gateway instance is already listening` / `EADDRINUSE` → конфликт портов.
    - `Other gateway-like services detected (best effort)` → существуют устаревшие или параллельные модули launchd/systemd/schtasks. В большинстве конфигураций на одном компьютере должен работать один Gateway; если вам всё же требуется несколько, изолируйте порты, конфигурацию, состояние и рабочее пространство. См. [/gateway#multiple-gateways-same-host](/ru/gateway#multiple-gateways-same-host).
    - `System-level OpenClaw gateway service detected` от doctor → существует системный модуль systemd, а служба уровня пользователя отсутствует. Удалите или отключите дубликат, прежде чем разрешить doctor установить пользовательскую службу, либо задайте `OPENCLAW_SERVICE_REPAIR_POLICY=external`, если предполагаемым супервизором является системный модуль.
    - `Gateway service port does not match current gateway config` → установленный супервизор по-прежнему закрепляет старый `--port`. Выполните `openclaw doctor --fix` или `openclaw gateway install --force`, затем перезапустите службу Gateway.

  </Accordion>
</AccordionGroup>

См. также:

- [Фоновое выполнение и инструмент процессов](/ru/gateway/background-process)
- [Конфигурация](/ru/gateway/configuration)
- [Doctor](/ru/gateway/doctor)

## Gateway в macOS незаметно перестаёт отвечать, а затем возобновляет работу после взаимодействия с панелью управления

Используйте этот раздел, если каналы (Telegram, WhatsApp и т. д.) на хосте macOS перестают отвечать на время от нескольких минут до нескольких часов, а Gateway, судя по всему, возобновляет работу сразу после открытия Control UI, подключения по SSH или иного взаимодействия с хостом. Обычно в `openclaw status` нет явных признаков проблемы, поскольку к моменту проверки Gateway уже снова работает.

```bash
ls ~/.openclaw/logs/stability/ | tail -5
openclaw gateway stability --bundle latest
pmset -g log | grep -iE "sleep|wake|maintenance" | tail -50
launchctl print gui/$UID/ai.openclaw.gateway | grep -E "state|last exit|runs"
```

Обратите внимание на следующее:

- Один или несколько пакетов `*-uncaught_exception.json` в `~/.openclaw/logs/stability/`, где для `error.code` указан временный код сетевой ошибки, например `ENETDOWN`, `ENETUNREACH`, `EHOSTUNREACH` или `ECONNREFUSED`.
- Строки `pmset -g log`, например `Entering Sleep state due to 'Maintenance Sleep'` или `en0 driver is slow (msg: WillChangeState to 0)`, совпадающие по времени с аварийными завершениями. Power Nap / Maintenance Sleep ненадолго переводит драйвер Wi-Fi в состояние 0; любой исходящий запрос `connect()`, попавший в этот интервал, может завершиться ошибкой `ENETDOWN` даже на хосте, который в остальное время имеет полноценное сетевое подключение.
- Вывод `launchctl print`, показывающий `state = not running` с несколькими недавними `runs` и кодом выхода, особенно если интервал между аварийным завершением и следующим запуском составляет около часа, а не несколько секунд. После серии аварийных завершений launchd в macOS применяет недокументированный механизм защиты от повторных запусков, из-за которого `KeepAlive=true` может игнорироваться до тех пор, пока внешний триггер — например интерактивный вход, подключение панели управления или `launchctl kickstart` — не активирует его повторно.

Типичные признаки:

- Пакет стабильности, в котором значение `error.code` равно `ENETDOWN` или родственному коду, а стек вызовов указывает на Node `net` `lookupAndConnect` / `Socket.connect`. OpenClaw `2026.5.26` и более новых версий классифицирует такие ошибки как безопасные временные сетевые ошибки, поэтому они больше не передаются необработанному обработчику верхнего уровня; если вы используете более старую версию, сначала обновитесь.
- Длительные периоды бездействия, которые заканчиваются сразу после подключения к Control UI или входа на хост по SSH: именно видимая пользователю активность повторно запускает механизм повторного запуска launchd, а не какие-либо действия панели управления с Gateway.
- Счётчик `runs`, увеличивающийся в течение дня без соответствующей строки `received SIG*; shutting down` в `~/Library/Logs/openclaw/gateway.log`: при штатном завершении регистрируется сигнал, а при временных аварийных завершениях — нет.

Что делать:

1. **Обновите Gateway**, если используете версию старше `2026.5.26`. После обновления последующие ошибки `ENETDOWN` будут регистрироваться как предупреждения, а не завершать процесс.
2. **Сократите активность режима обслуживания во сне** на Mac mini и настольных хостах, предназначенных для постоянной работы в качестве серверов:

   ```bash
   sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0
   ```

   Это значительно уменьшает, но не устраняет полностью, нестабильность драйвера. Независимо от этих флагов система всё ещё может выполнять некоторые переходы в режим обслуживания во сне для поддержки TCP keepalive и mDNS.

3. **Добавьте сторожевую проверку работоспособности**, чтобы в будущем быстро обнаруживать серии аварийных завершений, после которых launchd прекращает повторные запуски:

   ```bash
   # Пример проверки работоспособности с учётом launchd, подходящей для cron или LaunchAgent с интервалом 5 минут
   state=$(launchctl print gui/$UID/ai.openclaw.gateway 2>/dev/null | awk -F'= ' '/state =/ {print $2; exit}')
   if [ "$state" != "running" ]; then
     launchctl kickstart -k gui/$UID/ai.openclaw.gateway
   fi
   ```

   Задача состоит в том, чтобы извне повторно активировать механизм повторного запуска; одного `KeepAlive=true` после серии аварийных завершений в macOS недостаточно.

См. также:

- [Примечания о платформе macOS](/ru/platforms/macos)
- [Журналирование](/ru/logging)
- [Doctor](/ru/gateway/doctor)

## Цикл супервизора launchd в macOS при дублирующихся LaunchAgent для Gateway и Node

Используйте этот раздел, если установка в macOS перезапускается каждые несколько секунд, проверки работоспособности `openclaw`
попеременно показывают доступность и недоступность, а отправка сообщений через каналы останавливается,
хотя служба, судя по всему, работает.

Такое наблюдалось в старых установках, где одновременно были активны LaunchAgent `ai.openclaw.gateway` и
`ai.openclaw.node`, каждый из которых внедрял
`OPENCLAW_LAUNCHD_LABEL`. В таком состоянии OpenClaw может обнаружить управление со стороны launchd,
попытаться передать перезапуск обратно launchd и попасть в быстрый цикл
`EADDRINUSE`/повторного запуска вместо работы одного стабильного процесса Gateway.

```bash
for i in 1 2 3 4; do
  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'
  sleep 10
done

openclaw gateway status --deep
openclaw node status
launchctl print gui/$UID/ai.openclaw.gateway | grep -E 'state|last exit|runs'
tail -n 80 ~/Library/Logs/openclaw/gateway.log
```

Обратите внимание на следующее:

- Несколько PID Gateway в течение 30-секундной выборки вместо одного стабильного
  процесса.
- `EADDRINUSE`, `another gateway instance is already listening` или повторяющиеся
  строки перезапуска/передачи управления в `gateway.log`.
- Одновременно загружены `~/Library/LaunchAgents/ai.openclaw.gateway.plist` и
  `~/Library/LaunchAgents/ai.openclaw.node.plist` на хосте,
  где должна работать только одна управляемая служба Gateway.

Что делать:

1. Если на этом хосте должна работать только служба Gateway, удалите управляемую службу Node
   с помощью OpenClaw. **Пропустите этот шаг**, если вы активно используете службу Node
   для удалённых функций Node: её удаление остановит работу этих функций
   на данном хосте:

   ```bash
   openclaw node uninstall
   ```

2. Установите постоянную оболочку Gateway, которая очищает унаследованные маркеры launchd
   перед запуском OpenClaw. Используйте поддерживаемый параметр `--wrapper`; не
   редактируйте сгенерированный файл в `~/.openclaw/service-env/`, поскольку при
   переустановке и обновлении службы, а также восстановлении через Doctor этот файл создаётся заново:

   ```bash
   mkdir -p ~/.local/bin
   cat >~/.local/bin/openclaw-launchd-workaround <<'EOF'
   #!/bin/sh
   set -eu
   unset OPENCLAW_LAUNCHD_LABEL LAUNCH_JOB_LABEL LAUNCH_JOB_NAME XPC_SERVICE_NAME || true
   exec openclaw "$@"
   EOF
   chmod 700 ~/.local/bin/openclaw-launchd-workaround

   openclaw gateway install \
     --wrapper ~/.local/bin/openclaw-launchd-workaround \
     --force
   ```

   `gateway install` сохраняет путь к оболочке при принудительных переустановках,
   обновлениях и восстановлении через Doctor.

3. Убедитесь, что Gateway работает стабильно и обслуживает RPC, а не просто прослушивает порт:

   ```bash
   openclaw gateway status --deep --require-rpc

   for i in 1 2 3 4; do
     ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'
     sleep 10
   done
   ```

   В выборке PID должен отображаться один стабильный процесс вместо постоянно сменяющегося набора
   PID, а обработка входящих сообщений каналов должна возобновиться.

4. После обновления до версии, в которой исправлен основной цикл с двумя LaunchAgent,
   удалите обходное решение и переустановите обычную управляемую службу:

   ```bash
   OPENCLAW_WRAPPER= openclaw gateway install --force
   rm ~/.local/bin/openclaw-launchd-workaround
   ```

См. также:

- [Примечания о платформе macOS](/ru/platforms/mac/bundled-gateway)
- [Doctor](/ru/gateway/doctor)
- [CLI Gateway](/ru/cli/gateway)

## Gateway завершает работу при высоком потреблении памяти

Используйте этот раздел, если Gateway исчезает под нагрузкой, супервизор сообщает о перезапуске в стиле OOM или в журналах упоминается `critical memory pressure bundle written`.

```bash
openclaw gateway status --deep
openclaw logs --follow
openclaw gateway stability --bundle latest
openclaw gateway diagnostics export
```

Обратите внимание на следующее:

- `Reason: diagnostic.memory.pressure.critical` в последнем пакете стабильности.
- `Memory pressure:` с `critical/rss_threshold`, `critical/heap_threshold` или `critical/rss_growth`.
- Значения `V8 heap:`, близкие к пределу кучи.
- Записи `Largest session files:`, например `agents/<agent>/sessions/<session>.jsonl` или `sessions/<session>.jsonl`.
- Счётчики памяти cgroup Linux, если Gateway работает внутри контейнера или службы с ограничением памяти.

Типичные признаки:

- `critical memory pressure bundle written` появляется незадолго до перезапуска → OpenClaw сохранил пакет стабильности перед OOM. Проверьте его с помощью `openclaw gateway stability --bundle latest`.
- `memory pressure: level=critical ... memoryPressureSnapshot=disabled` появляется в журналах Gateway → OpenClaw обнаружил критическую нехватку памяти, но создание снимка стабильности перед OOM отключено.
- `Largest session files:` указывает на очень большой отредактированный путь к расшифровке → сократите сохраняемую историю сеансов, проверьте рост сеансов или переместите старые расшифровки из активного хранилища перед перезапуском.
- Количество использованных байтов `V8 heap:` близко к пределу кучи → снизьте нагрузку от запросов и сеансов, сократите количество параллельных задач или увеличьте предел кучи Node только после подтверждения ожидаемого характера нагрузки.
- `Memory pressure: critical/rss_growth` → объём памяти быстро увеличился в пределах одного интервала выборки. Проверьте последние журналы на наличие крупного импорта, неконтролируемого вывода инструмента, повторяющихся попыток или пакета поставленных в очередь задач агента.
- В журналах появляется критическая нехватка памяти, но пакет отсутствует → это поведение по умолчанию. Установите `diagnostics.memoryPressureSnapshot: true`, чтобы при будущих событиях критической нехватки памяти сохранялся пакет стабильности перед OOM.

Пакет стабильности не содержит полезной нагрузки. Он включает эксплуатационные сведения о памяти и отредактированные относительные пути к файлам, но не текст сообщений, тела Webhook, учётные данные, токены, файлы cookie или необработанные идентификаторы сеансов. Вместо копирования необработанных журналов прикладывайте к отчётам об ошибках экспорт диагностики.

См. также:

- [Состояние Gateway](/ru/gateway/health)
- [Экспорт диагностики](/ru/gateway/diagnostics)
- [Сеансы](/ru/cli/sessions)

## Gateway отклонил недопустимую конфигурацию

Используйте этот раздел, если запуск Gateway завершается с ошибкой `Invalid config` или в журналах горячей перезагрузки указано, что недопустимое изменение было пропущено.

```bash
openclaw logs --follow
openclaw config file
openclaw config validate
openclaw doctor
```

Обратите внимание на следующее:

- `Invalid config at ...`
- `config reload skipped (invalid config): ...`
- `Config write rejected: ...`
- Файл `openclaw.json.rejected.*` с меткой времени рядом с активной конфигурацией.
- Файл `openclaw.json.clobbered.*` с меткой времени, если `doctor --fix` исправил некорректное прямое изменение.
- OpenClaw сохраняет последние 32 файла `.clobbered.*` для каждого пути конфигурации и удаляет более старые при ротации.

<AccordionGroup>
  <Accordion title="Что произошло">
    - Конфигурация не прошла проверку при запуске, горячей перезагрузке или записи, выполняемой OpenClaw.
    - Запуск Gateway завершается с запретом продолжения вместо перезаписи `openclaw.json`.
    - Горячая перезагрузка пропускает недопустимые внешние изменения и сохраняет текущую конфигурацию среды выполнения активной.
    - Операции записи OpenClaw отклоняют недопустимые или разрушительные данные до фиксации и сохраняют `.rejected.*`.
    - Восстановлением управляет `openclaw doctor --fix`. Он может удалить префиксы, не относящиеся к JSON, или восстановить последнюю заведомо исправную копию, сохранив отклонённые данные как `.clobbered.*`.
    - Если для одного пути конфигурации выполняется много восстановлений, OpenClaw удаляет старые файлы `.clobbered.*` при ротации, чтобы последние восстановленные данные оставались доступными.

  </Accordion>
  <Accordion title="Проверка и восстановление">
    ```bash
    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
    ```
  </Accordion>
  <Accordion title="Распространённые признаки">
    - `.clobbered.*` существует → doctor сохранил повреждённое внешнее изменение при восстановлении активной конфигурации.
    - `.rejected.*` существует → запись конфигурации, выполняемая OpenClaw, не прошла проверку схемы или защиту от затирания перед фиксацией.
    - `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` → кандидат содержал скрытые заполнители секретов, например `***`.

  </Accordion>
  <Accordion title="Варианты исправления">
    1. Выполните `openclaw doctor --fix`, чтобы doctor восстановил конфигурацию с добавленным префиксом или затёртую конфигурацию либо вернул последнюю заведомо исправную версию.
    2. Скопируйте только нужные ключи из `.clobbered.*` или `.rejected.*`, затем примените их с помощью `openclaw config set` или `config.patch`.
    3. Перед перезапуском выполните `openclaw config validate`.
    4. При ручном редактировании сохраняйте полную конфигурацию JSON5, а не только частичный объект, который нужно изменить.
  </Accordion>
</AccordionGroup>

Связанные материалы:

- [Конфигурация](/ru/cli/config)
- [Конфигурация: горячая перезагрузка](/ru/gateway/configuration#config-hot-reload)
- [Конфигурация: строгая проверка](/ru/gateway/configuration#strict-validation)
- [Doctor](/ru/gateway/doctor)

## Предупреждения проверки Gateway

Используйте этот раздел, если `openclaw gateway probe` достигает какого-либо адреса, но по-прежнему выводит блок предупреждений.

```bash
openclaw gateway probe
openclaw gateway probe --json
openclaw gateway probe --ssh user@gateway-host
```

Проверьте:

- `warnings[].code` и `primaryTargetId` в выводе JSON.
- Относится ли предупреждение к резервному подключению через SSH, нескольким шлюзам, отсутствующим областям доступа или неразрешённым ссылкам аутентификации.

Распространённые признаки:

- `SSH tunnel failed to start; falling back to direct probes.` → настройка SSH завершилась ошибкой, но команда всё равно попыталась использовать непосредственно настроенные адреса или адреса обратной петли.
- `multiple reachable gateway identities detected` → ответили разные шлюзы либо OpenClaw не удалось доказать, что доступные адреса ведут к одному шлюзу. SSH-туннель, URL прокси или настроенный удалённый URL к одному и тому же шлюзу считается одним шлюзом с несколькими транспортами, даже если порты транспортов различаются.
- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → подключение установлено, но подробный RPC ограничен областью доступа; выполните сопряжение идентификатора устройства или используйте учётные данные с `operator.read`.
- `Gateway accepted the WebSocket connection, but follow-up read diagnostics failed` → подключение установлено, но полный набор диагностических RPC завершился по тайм-ауту или с ошибкой. Считайте Gateway доступным, но с ограниченной диагностикой; сравните `connect.ok` и `connect.rpcOk` в выводе `--json`.
- `Capability: pairing-pending` или `gateway closed (1008): pairing required` → шлюз ответил, но этому клиенту всё ещё требуется сопряжение или одобрение перед получением обычного операторского доступа.
- Текст предупреждения о неразрешённой ссылке SecretRef `gateway.auth.*` / `gateway.remote.*` → данные аутентификации были недоступны в этом пути выполнения команды для целевого адреса, подключение к которому завершилось ошибкой.

Связанные материалы:

- [Gateway](/ru/cli/gateway)
- [Несколько шлюзов на одном хосте](/ru/gateway#multiple-gateways-same-host)
- [Удалённый доступ](/ru/gateway/remote)

## Канал подключён, но сообщения не передаются

Если канал подключён, но обмен сообщениями не работает, сосредоточьтесь на политиках, разрешениях и правилах доставки конкретного канала.

```bash
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw status --deep
openclaw logs --follow
openclaw config get channels
```

Проверьте:

- Политику личных сообщений (`pairing`, `allowlist`, `open`, `disabled`).
- Список разрешённых групп и требования к упоминаниям.
- Отсутствующие разрешения или области доступа API канала.

Распространённые признаки:

- `mention required` → сообщение проигнорировано политикой упоминаний в группах.
- `pairing` / записи трассировки об ожидании одобрения → отправитель не одобрен.
- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → проблема с аутентификацией или разрешениями канала.

Связанные материалы:

- [Устранение неполадок каналов](/ru/channels/troubleshooting)
- [Discord](/ru/channels/discord)
- [Telegram](/ru/channels/telegram)
- [WhatsApp](/ru/channels/whatsapp)

## Доставка Cron и Heartbeat

Если Cron или Heartbeat не выполнился либо не доставил сообщение, сначала проверьте состояние планировщика, а затем целевой адрес доставки.

```bash
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow
```

Проверьте:

- Включён ли Cron и указано ли время следующего пробуждения.
- Состояние истории запусков задания (`ok`, `skipped`, `error`).
- Причины пропуска Heartbeat (`quiet-hours`, `requests-in-flight`, `cron-in-progress`, `lanes-busy`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`).

<AccordionGroup>
  <Accordion title="Распространённые признаки">
    - `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` существует, но содержит только пустые строки, комментарии, заголовки, ограждения или заготовку пустого контрольного списка, поэтому OpenClaw пропускает обращение к модели.
    - `heartbeat skipped` вместе с `reason=no-tasks-due` → `HEARTBEAT.md` содержит блок `tasks:`, но ни одна из задач не должна выполняться на этом такте.
    - `heartbeat: unknown accountId` → недопустимый идентификатор учётной записи для целевого адреса доставки Heartbeat.
    - `heartbeat skipped` вместе с `reason=dm-blocked` → целевой адрес Heartbeat разрешился в назначение типа личного сообщения, когда `agents.defaults.heartbeat.directPolicy` (или переопределение для отдельного агента) имеет значение `block`.

  </Accordion>
</AccordionGroup>

Связанные материалы:

- [Heartbeat](/ru/gateway/heartbeat)
- [Запланированные задачи](/ru/automation/cron-jobs)
- [Запланированные задачи: устранение неполадок](/ru/automation/cron-jobs#troubleshooting)

## Node сопряжён, но инструмент не работает

Если Node сопряжён, но инструменты не работают, отдельно проверьте состояние переднего плана, разрешений и одобрений.

```bash
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
openclaw status
```

Проверьте:

- Находится ли Node в сети и предоставляет ли ожидаемые возможности.
- Предоставлены ли разрешения ОС на доступ к камере, микрофону, местоположению и экрану.
- Состояние одобрений выполнения и списка разрешённых команд.

Распространённые признаки:

- `NODE_BACKGROUND_UNAVAILABLE` → приложение Node должно находиться на переднем плане.
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → отсутствует разрешение ОС.
- `SYSTEM_RUN_DENIED: approval required` → ожидается одобрение выполнения.
- `SYSTEM_RUN_DENIED: allowlist miss` → команда заблокирована списком разрешённых команд.

Связанные материалы:

- [Одобрения выполнения](/ru/tools/exec-approvals)
- [Устранение неполадок Node](/ru/nodes/troubleshooting)
- [Узлы](/ru/nodes/index)

## Инструмент браузера не работает

Используйте этот раздел, если действия инструмента браузера завершаются ошибкой, хотя сам Gateway исправен.

```bash
openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw logs --follow
openclaw doctor
```

Проверьте:

- Задано ли значение `plugins.allow` и включает ли оно `browser`.
- Допустим ли путь к исполняемому файлу браузера.
- Доступен ли профиль CDP.
- Доступен ли локальный Chrome для профилей `existing-session` / `user`.

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

  </Accordion>
  <Accordion title="Признаки проблем Chrome MCP или существующего сеанса">
    - `Could not find DevToolsActivePort for chrome` → существующему сеансу Chrome MCP пока не удалось подключиться к выбранному каталогу данных браузера. Откройте страницу проверки браузера, включите удалённую отладку, оставьте браузер открытым, одобрите первый запрос на подключение и повторите попытку. Если состояние выполненного входа не требуется, предпочтительно использовать управляемый профиль `openclaw`.
    - `No browser 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 ответила, но WebSocket CDP всё равно не удалось открыть.

  </Accordion>
  <Accordion title="Признаки проблем с элементами, снимками экрана или загрузкой файлов">
    - `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 либо используйте управляемый профиль браузера или профиль CDP, если требуется пользовательский тайм-аут.
    - `response body is not supported for existing-session profiles yet.` → для `responsebody` по-прежнему требуется управляемый браузер или необработанный профиль CDP.
    - Устаревшие переопределения области просмотра, тёмного режима, локали или автономного режима в профилях только для подключения либо удалённых профилях CDP → выполните `openclaw browser stop --browser-profile <name>`, чтобы закрыть активный сеанс управления и освободить состояние эмуляции Playwright/CDP без перезапуска всего Gateway.

  </Accordion>
</AccordionGroup>

Связанные материалы:

- [Браузер под управлением OpenClaw](/ru/tools/browser)
- [Устранение неполадок браузера](/ru/tools/browser-linux-troubleshooting)

## Если после обновления что-то внезапно перестало работать

Большинство неполадок после обновления связано с расхождением конфигурации или с тем, что теперь применяются более строгие значения по умолчанию.

<AccordionGroup>
  <Accordion title="1. Поведение аутентификации и переопределения URL изменилось">
    ```bash
    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` → конечная точка доступна, но аутентификация настроена неверно.

  </Accordion>
  <Accordion title="2. Ограничения привязки и аутентификации стали строже">
    ```bash
    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.

  </Accordion>
  <Accordion title="3. Состояние сопряжения и идентификации устройства изменилось">
    ```bash
    openclaw devices list
    openclaw pairing list --channel <channel> [--account <id>]
    openclaw logs --follow
    openclaw doctor
    ```

    Что проверить:

    - Ожидающие подтверждения устройств для панели управления или узлов.
    - Ожидающие подтверждения сопряжения в личных сообщениях после изменений политики или идентификации.

    Типичные признаки:

    - `device identity required` → требования аутентификации устройства не выполнены.
    - `pairing required` → отправитель или устройство должны быть одобрены.

  </Accordion>
</AccordionGroup>

Если после проверок конфигурация сервиса и среда выполнения по-прежнему не согласованы, переустановите метаданные сервиса из того же каталога профиля и состояния:

```bash
openclaw gateway install --force
openclaw gateway restart
```

См. также:

- [Аутентификация](/ru/gateway/authentication)
- [Фоновое выполнение и инструмент управления процессами](/ru/gateway/background-process)
- [Сопряжение Node](/ru/gateway/pairing)

## См. также

- [Doctor](/ru/gateway/doctor)
- [Часто задаваемые вопросы](/ru/help/faq)
- [Руководство по эксплуатации Gateway](/ru/gateway)
