> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateway

Gateway — это сервер WebSocket OpenClaw (каналы, узлы, сеансы, хуки). Все приведённые ниже подкоманды находятся в пространстве имён `openclaw gateway ...`.

> [card] [Обнаружение Bonjour](https://docs2.openclaw.ai/ru/gateway/bonjour.md)
>
> Настройка локального mDNS и глобального DNS-SD.

> [card] [Обзор обнаружения](https://docs2.openclaw.ai/ru/gateway/discovery.md)
>
> Как OpenClaw объявляет шлюзы и находит их.

> [card] [Конфигурация](https://docs2.openclaw.ai/ru/gateway/configuration.md)
>
> Ключи конфигурации Gateway верхнего уровня.

## Запуск Gateway

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway
openclaw gateway run   # эквивалентная явная форма
```

> [accordion] Поведение при запуске
>
> * Не запускается, если `gateway.mode=local` не задан в `~/.openclaw/openclaw.json`. Для разовых запусков и разработки используйте `--allow-unconfigured`; этот параметр обходит проверку, не записывая и не исправляя конфигурацию.
> * `openclaw onboard --mode local` и `openclaw setup` записывают `gateway.mode=local`. Если файл конфигурации существует, но `gateway.mode` отсутствует, конфигурация считается повреждённой или перезаписанной, и Gateway не пытается самостоятельно определить `local` — повторно выполните первоначальную настройку, задайте ключ вручную или передайте `--allow-unconfigured`.
> * Привязка не только к loopback-интерфейсу без аутентификации блокируется.
> * Значения `--bind` `lan`, `tailnet` и `custom` сейчас разрешаются только через IPv4; при самостоятельной настройке хоста только с IPv6 перед Gateway требуется дополнительный компонент или прокси с IPv4.
> * `SIGUSR1` при наличии разрешения запускает перезапуск внутри процесса. `commands.restart` (по умолчанию включён) управляет отправленным извне `SIGUSR1`; задайте значение `false`, чтобы блокировать ручные перезапуски с помощью сигналов ОС, сохранив возможность перезапуска через команду `gateway restart`, инструмент Gateway, а также применение или обновление конфигурации.
> * `SIGINT`/`SIGTERM` останавливают процесс, но не восстанавливают пользовательское состояние терминала. Если CLI обёрнут в TUI или используется ввод в необработанном режиме, восстановите терминал самостоятельно перед завершением работы.

### Параметры

**--port \<port>** `number`

Порт WebSocket (по умолчанию берётся из конфигурации или переменной среды; обычно `18789`).

**--bind \<mode>** `string`

Режим привязки: `loopback` (по умолчанию), `lan`, `tailnet`, `auto`, `custom`.

**--token \<token>** `string`

Общий токен для `connect.params.auth.token`. По умолчанию используется `OPENCLAW_GATEWAY_TOKEN`, если он задан.

**--auth \<mode>** `string`

Режим аутентификации: `none`, `token`, `password`, `trusted-proxy`.

**--password \<password>** `string`

Пароль для `--auth password`.

**--password-file \<path>** `string`

Читать пароль Gateway из файла.

**--tailscale \<mode>** `string`

Предоставление доступа через Tailscale: `off`, `serve`, `funnel`.

**--tailscale-reset-on-exit** `boolean`

Сбросить конфигурацию Tailscale serve/funnel при завершении работы.

**--allow-unconfigured** `boolean`

Запустить без обязательной проверки `gateway.mode=local`. Только для разовой начальной настройки и разработки; конфигурация не сохраняется и не исправляется.

**--dev** `boolean`

Создать конфигурацию и рабочую область для разработки, если они отсутствуют (без `BOOTSTRAP.md`).

**--reset** `boolean`

Сбросить конфигурацию для разработки, учётные данные, сеансы и рабочую область. Требуется `--dev`.

**--force** `boolean`

Перед запуском завершить любой существующий процесс, прослушивающий целевой порт.

**--verbose** `boolean`

Подробное журналирование в stdout/stderr.

**--cli-backend-logs** `boolean`

Показывать в консоли только журналы серверной части CLI (также включает stdout/stderr).

**--ws-log \<style>** `string` (default: auto)

Стиль журнала WebSocket: `auto`, `full`, `compact`.

**--compact** `boolean`

Псевдоним для `--ws-log compact`.

**--raw-stream** `boolean`

Записывать необработанные события потока модели в JSONL.

**--raw-stream-path \<path>** `string`

Путь к JSONL необработанного потока.

`--claude-cli-logs` — устаревший псевдоним для `--cli-backend-logs`.

Для `--bind custom` задайте в `gateway.customBindHost` адрес IPv4. Любой адрес, кроме `127.0.0.1` или `0.0.0.0`, также требует `127.0.0.1` на том же порту для клиентов на этом же хосте; запуск завершается ошибкой, если хотя бы один из слушателей не может выполнить привязку. Подстановочный адрес `0.0.0.0` не добавляет отдельный обязательный псевдоним. При самостоятельной настройке хоста только с IPv6 перед Gateway требуется дополнительный компонент или прокси с IPv4.

## Перезапуск Gateway

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway restart
openclaw gateway restart --safe
openclaw gateway restart --safe --skip-deferral
openclaw gateway restart --force
openclaw gateway restart --wait 30s
```

`--safe` запрашивает у работающего Gateway предварительную проверку активных задач и планирует один объединённый перезапуск после их завершения. Ожидание ограничено параметром `gateway.reload.deferralTimeoutMs` (по умолчанию 5 минут / `300000`); после исчерпания лимита перезапуск выполняется принудительно. Задайте `deferralTimeoutMs: 0`, чтобы вместо принудительного перезапуска ждать неограниченно долго, периодически выводя предупреждения о незавершённых задачах. `--safe` нельзя использовать вместе с `--force` или `--wait`.

`--skip-deferral` обходит проверку отложенного перезапуска из-за активных задач при безопасном перезапуске, поэтому Gateway перезапускается немедленно даже при наличии заявленных блокирующих факторов. Для него требуется `--safe` — используйте этот параметр, если откладывание зависло из-за неконтролируемой задачи.

`--wait <duration>` переопределяет лимит ожидания завершения задач для обычного, небезопасного перезапуска. Принимает значение в миллисекундах без суффикса или с суффиксами единиц `ms`, `s`, `m`, `h`, `d` (например, `30s`, `5m`, `1h30m`); `--wait 0` задаёт неограниченное ожидание. Несовместим с `--force` и `--safe`.

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

> [!WARNING]
>
> Указанный непосредственно `--password` может отображаться в локальном списке процессов. Предпочтительно использовать `--password-file`, переменную среды или `gateway.auth.password` на основе SecretRef.

### Профилирование Gateway

* `OPENCLAW_GATEWAY_STARTUP_TRACE=1` записывает длительность этапов запуска, включая задержку `eventLoopMax` для каждого этапа и длительность построения таблиц поиска плагинов (индекс установленных компонентов, реестр манифестов, планирование запуска, построение карты владельцев).
* `OPENCLAW_GATEWAY_RESTART_TRACE=1` записывает относящиеся к перезапуску строки `restart trace:`: обработку сигналов, ожидание завершения активных задач, этапы остановки, следующий запуск, время готовности и показатели памяти.
* `OPENCLAW_DIAGNOSTICS=timeline` вместе с `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>` записывает в режиме максимальных усилий хронологию диагностики запуска в формате JSONL для внешних стендов контроля качества (эквивалент конфигурации `diagnostics.flags: ["timeline"]`; путь по-прежнему задаётся только через переменную среды). Добавьте `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1`, чтобы включить выборки цикла событий.
* `pnpm build`, а затем `pnpm test:startup:gateway -- --runs 5 --warmup 1` измеряют производительность запуска Gateway через собранную точку входа CLI: первый вывод процесса, `/healthz`, `/readyz`, длительность этапов трассировки запуска, задержку цикла событий и время построения таблиц поиска плагинов.
* `pnpm build`, а затем `pnpm test:restart:gateway -- --case skipChannels --runs 1 --restarts 5` измеряют производительность внутрипроцессного перезапуска в macOS или Linux (в Windows не поддерживается; для перезапуска требуется `SIGUSR1`). Используется `SIGUSR1`; в дочернем процессе включаются обе трассировки и записываются следующие `/healthz`, следующие `/readyz`, время недоступности, время готовности, CPU, RSS и показатели трассировки перезапуска.
* `/healthz` проверяет работоспособность процесса; `/readyz` проверяет готовность к использованию. Рассматривайте строки трассировки и результаты измерений как сигнал для определения ответственного компонента, а не как полный вывод о производительности на основе одного интервала или замера.

## Запрос к работающему Gateway

Все команды запросов используют RPC через WebSocket.

> [tab] Режимы вывода
>
> * По умолчанию: удобочитаемый вывод (с цветами в TTY).
> * `--json`: машиночитаемый JSON (без оформления и индикатора выполнения).
> * `--no-color` (или `NO_COLOR=1`): отключить ANSI, сохранив удобочитаемую компоновку.

> [tab] Общие параметры
>
> * `--url <url>`: URL WebSocket для Gateway.
> * `--token <token>`: токен Gateway.
> * `--password <password>`: пароль Gateway.
> * `--timeout <ms>`: время ожидания или лимит времени (значение по умолчанию зависит от команды; см. описание каждой команды ниже).
> * `--expect-final`: ожидать «окончательного» ответа (вызовы агента).

> [!NOTE]
>
> Если задан `--url`, CLI не использует резервные учётные данные из конфигурации или переменных среды. Передайте `--token` или `--password` явно. Отсутствие явно заданных учётных данных является ошибкой.

### `gateway health`

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway health --url ws://127.0.0.1:18789
openclaw gateway health --port 18789
```

`/healthz` — проверка работоспособности процесса: она завершается, как только сервер способен ответить по HTTP. `/readyz` строже и продолжает сообщать о неготовности, пока запускаемые вспомогательные процессы плагинов, каналы или настроенные хуки ещё переходят в рабочее состояние. Подробные локальные или аутентифицированные ответы `/readyz` содержат диагностический блок `eventLoop` (задержка, загрузка, отношение к числу ядер CPU, флаг `degraded`).

**--port \<port>** `number`

Обращаться к локальному Gateway на loopback-интерфейсе через этот порт. Для данного вызова переопределяет `OPENCLAW_GATEWAY_URL` и `OPENCLAW_GATEWAY_PORT`.

### `gateway usage-cost`

Получить сводки расходов на использование из журналов сеансов.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway usage-cost
openclaw gateway usage-cost --days 7
openclaw gateway usage-cost --agent work --json
openclaw gateway usage-cost --all-agents
openclaw gateway usage-cost --json
```

**--days \<days>** `number` (default: 30)

Количество учитываемых дней.

**--agent \<id>** `string`

Ограничить сводку одним идентификатором настроенного агента.

**--all-agents** `boolean`

Объединить данные всех настроенных агентов. Нельзя использовать вместе с `--agent`.

### `gateway stability`

Получить последние данные диагностического регистратора стабильности из работающего Gateway.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway stability
openclaw gateway stability --type payload.large
openclaw gateway stability --bundle latest
openclaw gateway stability --bundle latest --export
openclaw gateway stability --json
```

**--limit \<limit>** `number` (default: 25)

Максимальное количество включаемых последних событий (не более `1000`).

**--type \<type>** `string`

Фильтровать по типу диагностического события, например `payload.large` или `diagnostic.memory.pressure`.

**--since-seq \<seq>** `number`

Включать только события после указанного номера диагностической последовательности.

**--bundle \[path]** `string`

Читать сохранённый пакет данных о стабильности вместо обращения к работающему Gateway. `--bundle latest` (или отдельный `--bundle`) выбирает новейший пакет в каталоге состояния; также можно напрямую передать путь к JSON-файлу пакета.

**--export** `boolean`

Записать ZIP-архив с диагностическими данными для передачи службе поддержки вместо вывода сведений о стабильности.

**--output \<path>** `string`

Путь вывода для `--export`.

> [accordion] Конфиденциальность и поведение пакета
>
> * Записи сохраняют операционные метаданные: названия событий, количества, размеры в байтах, показатели памяти, состояние очереди и сеанса, идентификаторы одобрений, названия каналов и плагинов, а также отредактированные сводки сеансов. Они не содержат текст чата, тела Webhook, результаты инструментов, необработанные тела запросов и ответов, токены, файлы cookie, секретные значения, имена хостов и необработанные идентификаторы сеансов. Установите `diagnostics.enabled: false`, чтобы полностью отключить средство записи.
> * При фатальном завершении Gateway, тайм-ауте остановки или сбое запуска после перезапуска тот же диагностический снимок записывается в `~/.openclaw/logs/stability/openclaw-stability-*.json`, если средство записи содержит события. Просмотрите новейший пакет с помощью `openclaw gateway stability --bundle latest`; `--limit`, `--type` и `--since-seq` также применяются к выводу пакета.

### `gateway diagnostics export`

Создаёт локальный ZIP-архив диагностики, предназначенный для отчётов об ошибках. Модель конфиденциальности и содержимое пакета описаны в разделе [Экспорт диагностики](https://docs2.openclaw.ai/ru/gateway/diagnostics.md).

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway diagnostics export
openclaw gateway diagnostics export --output openclaw-diagnostics.zip
openclaw gateway diagnostics export --json
```

**--output \<path>** `string`

Путь к выходному ZIP-архиву. По умолчанию создаётся экспорт для службы поддержки в каталоге состояния.

**--log-lines \<count>** `number` (default: 5000)

Максимальное количество включаемых очищенных строк журнала.

**--log-bytes \<bytes>** `number` (default: 1000000)

Максимальный объём журнала в байтах для проверки.

**--url \<url>** `string`

URL WebSocket Gateway для снимка работоспособности.

**--token \<token>** `string`

Токен Gateway для снимка работоспособности.

**--password \<password>** `string`

Пароль Gateway для снимка работоспособности.

**--timeout \<ms>** `number` (default: 3000)

Тайм-аут снимка состояния и работоспособности.

**--no-stability-bundle** `boolean`

Пропустить поиск сохранённого пакета стабильности.

**--json** `boolean`

Вывести записанный путь, размер и манифест в формате JSON.

Экспорт объединяет в пакет: `manifest.json` (перечень файлов), `summary.md` (сводка Markdown), `diagnostics.json` (сводка верхнего уровня по конфигурации, журналам, обнаружению, стабильности, состоянию и работоспособности), `config/sanitized.json`, `status/gateway-status.json`, `health/gateway-health.json`, `logs/openclaw-sanitized.jsonl` и `stability/latest.json`, если пакет существует.

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

### `gateway status`

Показывает службу Gateway (launchd/systemd/schtasks), а также необязательную проверку подключения и аутентификации.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway status
openclaw gateway status --json
openclaw gateway status --require-rpc
```

**--url \<url>** `string`

Добавить явную цель проверки. Настроенная удалённая цель и localhost по-прежнему проверяются.

**--token \<token>** `string`

Аутентификация по токену для проверки.

**--password \<password>** `string`

Аутентификация по паролю для проверки.

**--timeout \<ms>** `number` (default: 10000)

Тайм-аут проверки.

**--no-probe** `boolean`

Пропустить проверку подключения (показать только службу).

**--deep** `boolean`

Также сканировать службы системного уровня.

**--require-rpc** `boolean`

Расширить проверку подключения до проверки чтения и завершить работу с ненулевым кодом при её сбое. Нельзя использовать вместе с `--no-probe`.

> [accordion] Семантика состояния
>
> * Остаётся доступной для диагностики, даже если локальная конфигурация CLI отсутствует или недействительна.
> * Вывод по умолчанию подтверждает состояние службы, подключение WebSocket и возможность аутентификации, видимую во время рукопожатия, но не операции чтения, записи или администрирования.
> * Проверки не вносят изменений при первой аутентификации устройства: они повторно используют существующий кэшированный токен устройства, если он есть, но никогда не создают новую идентичность устройства CLI или запись сопряжения только для чтения исключительно для проверки состояния.
> * По возможности разрешает настроенные SecretRef аутентификации для проверки. Если обязательный SecretRef не разрешён, `--json` сообщает `rpc.authWarning` при сбое подключения или аутентификации проверки; явно передайте `--token`/`--password` либо исправьте источник секрета. После успешного завершения проверки предупреждения о неразрешённой аутентификации подавляются.
> * Вывод JSON содержит `gateway.version`, если его сообщает работающий Gateway; `--require-rpc` может использовать данные RPC `status.runtimeVersion`, если проверка рукопожатия не может предоставить метаданные версии.
> * Используйте `--require-rpc` в скриптах и автоматизации, когда работающей прослушивающей службы недостаточно и также требуется работоспособность RPC с областью чтения.
> * `--deep` сканирует дополнительные установки launchd/systemd/schtasks; если найдено несколько служб, похожих на Gateway, человекочитаемый вывод показывает рекомендации по очистке (обычно следует запускать один Gateway на каждом компьютере) и, когда применимо, сообщает о недавней передаче перезапуска диспетчером.
> * `--deep` также выполняет проверку конфигурации с учётом плагинов (`pluginValidation: "full"`) и показывает предупреждения манифеста плагина (например, об отсутствии метаданных конфигурации канала). Значение `gateway status` по умолчанию сохраняет быстрый путь только для чтения, пропускающий проверку плагинов.
> * Человекочитаемый вывод содержит разрешённый путь к файлу журнала, а также пути и сведения о действительности конфигурации CLI и службы, чтобы упростить диагностику расхождений профиля или каталога состояния.

> [accordion] Проверки расхождения аутентификации Linux systemd
>
> * Проверки расхождения аутентификации службы считывают из юнита как `Environment=`, так и `EnvironmentFile=` (включая `%h`, пути в кавычках, несколько файлов и необязательные файлы `-`).
> * Разрешает SecretRef `gateway.auth.token` с помощью объединённого окружения среды выполнения (сначала окружение команды службы, затем резервное окружение процесса).
> * Проверки расхождения токенов пропускают разрешение токена конфигурации, если аутентификация по токену фактически не активна (`gateway.auth.mode` явно имеет значение `password`/`none`/`trusted-proxy` либо режим не задан, пароль может иметь приоритет и ни один кандидат на токен не может получить приоритет).

### `gateway probe`

Команда «отладить всё». Она всегда проверяет:

* настроенный удалённый Gateway (если задан) и
* localhost (интерфейс обратной связи), **даже если настроен удалённый Gateway**.

Передача `--url` добавляет эту явную цель перед обеими остальными. В человекочитаемом выводе цели обозначаются как `URL (explicit)`, `Remote (configured)` / `Remote (configured, inactive)` и `Local loopback`.

> [!NOTE]
>
> Если доступно несколько целей проверки, выводятся все. SSH-туннель, URL TLS/прокси и настроенный удалённый URL могут указывать на один и тот же Gateway даже при разных транспортных портах; `multiple_gateways` предназначен для доступных шлюзов, которые различаются или чья идентичность неоднозначна. Запуск нескольких шлюзов поддерживается для изолированных профилей (например, резервного бота), но в большинстве установок работает один Gateway.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway probe
openclaw gateway probe --json
openclaw gateway probe --port 18789
```

**--port \<port>** `number`

Использовать этот порт для локальной цели проверки через интерфейс обратной связи и удалённого порта SSH-туннеля. Без `--url` выбирается только локальная цель через интерфейс обратной связи вместо URL среды настроенного Gateway, порта окружения или удалённых целей.

> [accordion] Интерпретация
>
> * `Reachable: yes` означает, что хотя бы одна цель приняла подключение WebSocket.
> * `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` сообщает, что проверке удалось подтвердить об аутентификации, отдельно от доступности.
> * `Read probe: ok` означает, что подробные вызовы RPC с областью чтения (`health`/`status`/`system-presence`/`config.get`) также завершились успешно.
> * `Read probe: limited - missing scope: operator.read` означает, что подключение выполнено успешно, но RPC с областью чтения ограничен. Это отображается как **ухудшенная** доступность, а не полный сбой.
> * `Read probe: failed` после `Connect: ok` означает, что WebSocket подключился, но последующая диагностика чтения завершилась по тайм-ауту или со сбоем — это также **ухудшенное состояние**, а не недоступность.
> * Как и `gateway status`, проверка повторно использует существующие кэшированные данные аутентификации устройства, но не создаёт идентичность устройства или состояние сопряжения при первом использовании.
> * Код завершения ненулевой только в том случае, если ни одна проверенная цель недоступна.

> [accordion] Вывод JSON
>
> Верхний уровень:
>
> * `ok`: хотя бы одна цель доступна.
> * `degraded`: хотя бы одна цель приняла подключение, но не завершила полную подробную диагностику RPC.
> * `capability`: лучшая возможность среди доступных целей (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope` или `unknown`).
> * `primaryTargetId`: лучшая цель, которую следует считать активной, в следующем порядке: явный URL, SSH-туннель, настроенная удалённая цель, локальный интерфейс обратной связи.
> * `warnings[]`: записи предупреждений по мере возможности с `code`, `message` и необязательным `targetIds`.
> * `network`: подсказки URL для локального интерфейса обратной связи и tailnet, полученные из текущей конфигурации и сетевых параметров хоста.
> * `discovery.timeoutMs` / `discovery.count`: фактический бюджет обнаружения и количество результатов, использованные в этом проходе проверки.
>
> Для каждой цели (`targets[].connect`): `ok` (доступность и классификация ухудшенного состояния), `rpcOk` (успешность полного подробного RPC), `scopeLimited` (сбой подробного RPC из-за отсутствия области оператора).
>
> Для каждой цели (`targets[].auth`): `role` и `scopes`, указанные в `hello-ok`, если доступны, а также отображаемая классификация `capability`.

> [accordion] Распространённые коды предупреждений
>
> * `ssh_tunnel_failed`: не удалось настроить SSH-туннель; команда перешла к прямым проверкам.
> * `multiple_gateways`: были доступны разные идентичности Gateway либо OpenClaw не смог подтвердить, что доступные цели являются одним и тем же Gateway. SSH-туннель, URL прокси или настроенный удалённый URL к одному и тому же Gateway не вызывают это предупреждение.
> * `auth_secretref_unresolved`: настроенный SecretRef аутентификации не удалось разрешить для цели, проверка которой завершилась сбоем.
> * `probe_scope_limited`: подключение WebSocket выполнено успешно, но проверка чтения была ограничена из-за отсутствия `operator.read`.
> * `local_tls_runtime_unavailable`: локальный TLS Gateway включён, но OpenClaw не удалось загрузить отпечаток локального сертификата.

#### Удалённое подключение по SSH (аналог режима приложения Mac)

Режим приложения macOS "Remote over SSH" использует локальное перенаправление порта, чтобы удалённый Gateway, доступный только через интерфейс обратной связи, стал доступен по адресу `ws://127.0.0.1:<port>`.

Эквивалент для CLI:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway probe --ssh user@gateway-host
```

**--ssh \<target>** `string`

`user@host` или `user@host:port` (порт по умолчанию — `22`).

**--ssh-identity \<path>** `string`

Файл идентификации.

**--ssh-auto** `boolean`

Выбрать первый обнаруженный хост Gateway в качестве цели SSH из разрешённой конечной точки обнаружения (`local.` и настроенный глобальный домен, если он задан). Подсказки только из TXT игнорируются.

Настройки конфигурации по умолчанию (необязательно): `gateway.remote.sshTarget`, `gateway.remote.sshIdentity`.

### `gateway call <method>`

Низкоуровневая вспомогательная функция RPC.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway call status
openclaw gateway call logs.tail --params '{"limit": 200}'
```

**--params \<json>** `string` (default: \{})

Строка с объектом JSON для параметров.

**--url \<url>** `string`

URL WebSocket для Gateway.

**--token \<token>** `string`

Токен Gateway.

**--password \<password>** `string`

Пароль Gateway.

**--timeout \<ms>** `number` (default: 10000)

Лимит времени ожидания.

**--expect-final** `boolean`

В основном предназначено для RPC в стиле агентов, которые передают промежуточные события перед окончательными данными.

**--json** `boolean`

Машиночитаемый вывод JSON.

> [!NOTE]
>
> `--params` должен быть допустимым JSON, а каждый метод проверяет собственную структуру параметров (лишние поля и поля с неверными именами отклоняются).

## Управление службой Gateway

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall
```

### Установка с обёрткой

Используйте `--wrapper`, когда управляемая служба должна запускаться через другой исполняемый файл, например через промежуточный модуль диспетчера секретов или вспомогательную программу запуска от имени другого пользователя. Обёртка получает обычные аргументы Gateway и отвечает за последующий вызов через exec файла `openclaw` или Node с этими аргументами.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
cat > ~/.local/bin/openclaw-doppler <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
exec doppler run --project my-project --config production -- openclaw "$@"
EOF
chmod +x ~/.local/bin/openclaw-doppler

openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force
openclaw gateway restart
```

Обёртку также можно задать через окружение. `gateway install` проверяет, что путь указывает на исполняемый файл, записывает обёртку в `ProgramArguments` службы и сохраняет `OPENCLAW_WRAPPER` в окружении службы для последующих принудительных переустановок, обновлений и исправлений с помощью doctor.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force
openclaw doctor
```

Чтобы удалить сохранённую обёртку, очистите `OPENCLAW_WRAPPER` при переустановке:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_WRAPPER= openclaw gateway install --force
openclaw gateway restart
```

> [accordion] Параметры команд
>
> * `gateway status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
> * `gateway install`: `--port`, `--runtime <node>` (по умолчанию: `node`), `--token`, `--wrapper <path>`, `--force`, `--json`
> * `gateway restart`: `--safe`, `--skip-deferral`, `--force`, `--wait <duration>`, `--json`
> * `gateway uninstall|start`: `--json`
> * `gateway stop`: `--disable`, `--json`

> [accordion] Поведение жизненного цикла
>
> * Используйте `gateway restart` для перезапуска управляемой службы. Не объединяйте `gateway stop` и `gateway start` в цепочку вместо перезапуска.
> * В macOS команда `gateway stop` по умолчанию использует `launchctl bootout`, что удаляет LaunchAgent из текущего сеанса загрузки без сохранения состояния отключения: автоматическое восстановление KeepAlive остаётся активным при будущих сбоях, а `gateway start` повторно включает службу без ручного выполнения `launchctl enable`. Передайте `--disable`, чтобы надолго отключить KeepAlive и RunAtLoad и не допустить повторного запуска Gateway до следующего явного выполнения `gateway start`; используйте этот вариант, если остановка вручную должна сохраняться после перезагрузок.
> * Команды жизненного цикла принимают `--json` для использования в сценариях.

> [accordion] Аутентификация и SecretRef при установке
>
> * Когда для аутентификации по токену требуется токен, а `gateway.auth.token` управляется через SecretRef, `gateway install` проверяет возможность разрешения SecretRef, но не сохраняет разрешённый токен в метаданных окружения службы.
> * Если для аутентификации по токену требуется токен, а настроенный SecretRef токена не разрешается, установка завершается с отказом вместо сохранения резервного токена в виде обычного текста.
> * Для аутентификации по паролю в `gateway run` предпочитайте `OPENCLAW_GATEWAY_PASSWORD`, `--password-file` или `gateway.auth.password` на основе SecretRef, а не встроенное значение `--password`.
> * В режиме автоматического определения аутентификации доступный только в оболочке `OPENCLAW_GATEWAY_PASSWORD` не отменяет требования к токену при установке; при установке управляемой службы используйте постоянную конфигурацию (`gateway.auth.password` или параметр конфигурации `env`).
> * Если настроены и `gateway.auth.token`, и `gateway.auth.password`, а `gateway.auth.mode` не задан, установка блокируется до явного выбора режима.

## Обнаружение шлюзов (Bonjour)

`gateway discover` выполняет поиск маяков Gateway (`_openclaw-gw._tcp`).

* Многоадресный DNS-SD: `local.`
* Одноадресный DNS-SD (глобальный Bonjour): выберите домен (например, `openclaw.internal.`) и настройте раздельный DNS и DNS-сервер; см. раздел [Bonjour](https://docs2.openclaw.ai/ru/gateway/bonjour.md).

Маяк объявляют только шлюзы, на которых включено обнаружение Bonjour (по умолчанию).

Подсказки TXT в каждом маяке: `role` (подсказка о роли шлюза), `transport` (подсказка о транспорте, например `gateway`), `gatewayPort` (порт WebSocket, обычно `18789`), `tailnetDns` (имя хоста MagicDNS, если доступно), `gatewayTls` / `gatewayTlsSha256` (включение TLS и отпечаток сертификата). `sshPort` и `cliPath` публикуются только в режиме полного обнаружения (`discovery.mdns.mode: "full"`; по умолчанию используется `"minimal"`, при котором они не публикуются — в этом случае клиенты по умолчанию используют порт `22` для целевых узлов SSH).

### `gateway discover`

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway discover
```

**--timeout \<ms>** `number` (default: 2000)

Время ожидания для каждой команды (обзор/разрешение).

**--json** `boolean`

Машиночитаемый вывод (также отключает оформление и индикатор выполнения).

Примеры:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway discover --timeout 4000
openclaw gateway discover --json | jq '.beacons[].wsUrl'
```

> [!NOTE]
>
> * Сканирует `local.`, а также настроенный глобальный домен, если он включён.
> * `wsUrl` в выводе JSON формируется из разрешённой конечной точки службы, а не только из подсказок TXT, таких как `lanHost` или `tailnetDns`.
> * `discovery.mdns.mode` управляет публикацией `sshPort`/`cliPath` как в mDNS `local.`, так и в глобальном DNS-SD (см. выше).

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

* [Справочник CLI](https://docs2.openclaw.ai/ru/cli.md)
* [Практическое руководство по Gateway](https://docs2.openclaw.ai/ru/gateway.md)