> ## 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.

> [card] [Углублённое устранение неполадок](https://docs2.openclaw.ai/ru/gateway/troubleshooting.md)
>
> Диагностика по симптомам с точными последовательностями команд и сигнатурами журналов.

> [card] [Конфигурация](https://docs2.openclaw.ai/ru/gateway/configuration.md)
>
> Руководство по настройке на основе задач и полный справочник по конфигурации.

> [card] [Управление секретами](https://docs2.openclaw.ai/ru/gateway/secrets.md)
>
> Контракт SecretRef, поведение снимка среды выполнения и операции миграции и перезагрузки.

> [card] [Контракт плана секретов](https://docs2.openclaw.ai/ru/gateway/secrets-plan-contract.md)
>
> Точные правила цели/пути `secrets apply` и поведение профиля аутентификации, использующего только ссылки.

## Локальный запуск за 5 минут

**1. Запустите Gateway**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway --port 18789
# отладочные данные и трассировка дублируются в стандартный ввод-вывод
openclaw gateway --port 18789 --verbose
# принудительно завершить процесс, прослушивающий выбранный порт, затем запустить
openclaw gateway --force
```

**2. Проверьте работоспособность службы**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway status
openclaw status
openclaw logs --follow
```

Базовые признаки нормальной работы: `Runtime: running`, `Connectivity probe: ok` и строка `Capability`, соответствующая ожидаемому значению. Используйте `openclaw gateway status --require-rpc` для проверки RPC с областью чтения, а не только доступности.

**3. Проверьте готовность каналов**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw channels status --probe
```

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

> [!NOTE]
>
> Перезагрузка конфигурации Gateway отслеживает путь к активному файлу конфигурации (определяемый из профиля и стандартных параметров состояния либо из `OPENCLAW_CONFIG_PATH`, если он задан). Режим по умолчанию — `gateway.reload.mode="hybrid"`. После первой успешной загрузки запущенный процесс обслуживает активный снимок конфигурации в памяти; успешная перезагрузка атомарно заменяет этот снимок.

## Модель среды выполнения

* Один постоянно работающий процесс для маршрутизации, плоскости управления и подключений каналов.
* Один мультиплексированный порт для:
  * управления и RPC через WebSocket
  * HTTP API (`/v1/models`, `/v1/embeddings`, `/v1/chat/completions`, `/v1/responses`, `/tools/invoke`)
  * HTTP-маршрутов плагинов, например необязательного `/api/v1/admin/rpc`
  * интерфейса управления и хуков
* Режим привязки по умолчанию: `loopback`. В обнаруженной контейнерной среде фактическое значение по умолчанию — `auto` (разрешается в `0.0.0.0` для перенаправления портов), если не активен режим serve/funnel Tailscale, который всегда принудительно использует `loopback`.
* По умолчанию требуется аутентификация. Конфигурации с общим секретом используют `gateway.auth.token` / `gateway.auth.password` (или `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`), а конфигурации обратного прокси не через loopback могут использовать `gateway.auth.mode: "trusted-proxy"`.

## Эндпоинты, совместимые с OpenAI

Наиболее значимая поверхность совместимости OpenClaw:

* `GET /v1/models`
* `GET /v1/models/{id}`
* `POST /v1/embeddings`
* `POST /v1/chat/completions`
* `POST /v1/responses`

Почему этот набор важен:

* Большинство интеграций Open WebUI, LobeChat и LibreChat сначала проверяют `/v1/models`.
* Многие конвейеры RAG и памяти ожидают `/v1/embeddings`.
* Клиенты, ориентированные на агентов, всё чаще предпочитают `/v1/responses`.

`/v1/models` в первую очередь ориентирован на агентов: он возвращает `openclaw`, `openclaw/default` и `openclaw/<agentId>` для каждого настроенного агента. `openclaw/default` — стабильный псевдоним, всегда сопоставляемый с настроенным агентом по умолчанию. Отправляйте `x-openclaw-model`, когда требуется переопределить серверного поставщика или модель; в противном случае управление сохраняют обычные настройки модели и эмбеддингов выбранного агента.

Все эти эндпоинты работают на основном порту Gateway и используют ту же доверенную границу аутентификации оператора, что и остальная часть HTTP API Gateway.

Административный HTTP RPC (`POST /api/v1/admin/rpc`) — это отдельный, по умолчанию отключённый маршрут плагина для инструментов хоста, которые не могут использовать RPC через WebSocket. См. [Административный HTTP RPC](https://docs2.openclaw.ai/ru/plugins/admin-http-rpc.md).

### Приоритет порта и привязки

| Параметр | Порядок разрешения |
| - | - |
| Порт Gateway | `--port` → `OPENCLAW_GATEWAY_PORT` → `gateway.port` → `18789` |
| Режим привязки | CLI/переопределение → `gateway.bind` → `loopback` (или `auto` в контейнерах) |

Установленные службы Gateway записывают разрешённое значение `--port` в метаданные супервизора. После изменения `gateway.port` выполните `openclaw doctor --fix` или `openclaw gateway install --force`, чтобы launchd/systemd/schtasks запускал процесс на новом порту.

При запуске Gateway использует тот же фактический порт и режим привязки для формирования локальных источников интерфейса управления при привязках не к loopback. Например, `--bind lan --port 3000` добавляет `http://localhost:3000` и `http://127.0.0.1:3000` до выполнения проверки среды выполнения. Явно добавьте все источники удалённых браузеров, например HTTPS-адреса прокси, в `gateway.controlUi.allowedOrigins`.

### Режимы горячей перезагрузки

| `gateway.reload.mode` | Поведение |
| - | - |
| `off` | Без перезагрузки конфигурации |
| `hot` | Применять только изменения, безопасные для горячей перезагрузки |
| `restart` | Перезапускать при изменениях, требующих перезагрузки |
| `hybrid` (по умолчанию) | Применять без перезапуска, когда это безопасно, и перезапускать при необходимости |

## Набор команд оператора

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway status
openclaw gateway status --deep   # добавляет проверку служб на уровне системы
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor
```

`gateway status --deep` предназначен для дополнительного обнаружения служб (LaunchDaemons/системных модулей systemd/schtasks), а не для более глубокой проверки работоспособности RPC.

## Несколько экземпляров Gateway на одном хосте

В большинстве установок следует запускать один Gateway на машину. Один Gateway может обслуживать несколько агентов и каналов. Несколько экземпляров Gateway нужны только тогда, когда вы намеренно хотите обеспечить изоляцию или использовать резервного бота.

Полезные проверки:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway status --deep
openclaw gateway probe
```

Ожидаемое поведение:

* `gateway status --deep` может сообщать `Other gateway-like services detected (best effort)` и выводить рекомендации по очистке, если сохраняются устаревшие установки launchd/systemd/schtasks.
* `gateway probe` может предупреждать о `multiple reachable gateway identities`, когда отвечают разные экземпляры Gateway или когда OpenClaw не может доказать, что доступные цели являются одним и тем же Gateway. SSH-туннель, URL-адрес прокси или настроенный удалённый URL-адрес к одному Gateway представляют собой один Gateway с несколькими транспортами, даже если транспортные порты различаются.
* Если это сделано намеренно, изолируйте порты, конфигурацию и состояние, а также корневые каталоги рабочих пространств для каждого Gateway.

Контрольный список для каждого экземпляра:

* Уникальный `gateway.port`
* Уникальный `OPENCLAW_CONFIG_PATH`
* Уникальный `OPENCLAW_STATE_DIR`
* Уникальный `agents.defaults.workspace`

Пример:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002
```

Подробная настройка: [/gateway/multiple-gateways](https://docs2.openclaw.ai/ru/gateway/multiple-gateways.md).

## Удалённый доступ

Предпочтительно: Tailscale/VPN.
Резервный вариант: SSH-туннель.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
ssh -N -L 18789:127.0.0.1:18789 user@gateway-host
```

Затем подключайте клиенты локально к `ws://127.0.0.1:18789`.

> [!WARNING]
>
> SSH-туннели не позволяют обойти аутентификацию Gateway. При аутентификации с общим секретом клиенты даже через туннель
> должны отправлять `token`/`password`. В режимах с передачей удостоверения
> запрос всё равно должен удовлетворять требованиям соответствующего пути аутентификации.

См.: [Удалённый Gateway](https://docs2.openclaw.ai/ru/gateway/remote.md), [Аутентификация](https://docs2.openclaw.ai/ru/gateway/authentication.md), [Tailscale](https://docs2.openclaw.ai/ru/gateway/tailscale.md).

## Надзор и жизненный цикл службы

Для надёжности на уровне производственной среды используйте запуск под управлением супервизора.

> [tab] macOS (launchd)
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> openclaw gateway install
> openclaw gateway status
> openclaw gateway restart
> openclaw gateway stop
> ```
>
> Используйте `openclaw gateway restart` для перезапуска. Не используйте последовательный вызов `openclaw gateway stop` и `openclaw gateway start` вместо перезапуска.
>
> В macOS `gateway stop` по умолчанию использует `launchctl bootout`. Это удаляет LaunchAgent из текущего сеанса загрузки без постоянного отключения, поэтому автоматическое восстановление KeepAlive продолжает работать после непредвиденных сбоев, а `gateway start` корректно включает службу повторно. Чтобы постоянно запрещать автоматический повторный запуск после перезагрузок, передайте `--disable`: `openclaw gateway stop --disable`.
>
> Метки LaunchAgent: `ai.openclaw.gateway` (по умолчанию) или `ai.openclaw.<profile>` (именованный профиль). `openclaw doctor` проверяет и исправляет расхождения конфигурации службы.

> [tab] Linux (пользовательская служба systemd)
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> openclaw gateway install
> systemctl --user enable --now openclaw-gateway[-<profile>].service
> openclaw gateway status
> ```
>
> Чтобы служба продолжала работать после выхода из системы, включите lingering:
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> sudo loginctl enable-linger $(whoami)
> ```
>
> На сервере без графической среды также убедитесь, что задан `XDG_RUNTIME_DIR` (`export XDG_RUNTIME_DIR=/run/user/$(id -u)`), прежде чем повторять команды `systemctl --user`.
>
> Пример пользовательского модуля для случая, когда требуется нестандартный путь установки:
>
> ```ini theme={"theme":{"light":"min-light","dark":"min-dark"}}
> [Unit]
> Description=Gateway OpenClaw
> After=network-online.target
> Wants=network-online.target
> StartLimitBurst=5
> StartLimitIntervalSec=60
>
> [Service]
> ExecStart=/usr/local/bin/openclaw gateway --port 18789
> Restart=always
> RestartSec=5
> RestartPreventExitStatus=78
> TimeoutStopSec=30
> TimeoutStartSec=30
> SuccessExitStatus=0 143
> OOMPolicy=continue
> KillMode=control-group
>
> [Install]
> WantedBy=default.target
> ```

> [tab] Windows (нативный режим)
>
> ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
> openclaw gateway install
> openclaw gateway status --json
> openclaw gateway restart
> openclaw gateway stop
> ```
>
> Управляемый запуск в Windows использует запланированную задачу с именем `OpenClaw Gateway`
> (или `OpenClaw Gateway (<profile>)` для именованных профилей). Если в создании запланированной задачи
> отказано, OpenClaw использует средство запуска из пользовательской папки автозагрузки,
> которое указывает на `gateway.cmd` в каталоге состояния.

> [tab] Linux (системная служба)
>
> Используйте системный модуль для многопользовательских и постоянно работающих хостов.
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> sudo systemctl daemon-reload
> sudo systemctl enable --now openclaw-gateway[-<profile>].service
> ```
>
> Используйте то же содержимое службы, что и для пользовательского модуля, но установите его в
> `/etc/systemd/system/openclaw-gateway[-<profile>].service` и скорректируйте
> `ExecStart=`, если исполняемый файл `openclaw` находится в другом месте.
>
> Не разрешайте `openclaw doctor --fix` также устанавливать пользовательскую службу Gateway для того же профиля и порта. Doctor отказывается от такой автоматической установки, если обнаруживает системную службу Gateway OpenClaw; используйте `OPENCLAW_SERVICE_REPAIR_POLICY=external`, когда жизненным циклом управляет системный модуль.

При ошибках недопустимой конфигурации процесс завершается с кодом `78`. Системные модули systemd в Linux используют `RestartPreventExitStatus=78`, чтобы прекратить повторные запуски до исправления конфигурации. В launchd и планировщике заданий Windows нет эквивалентного правила остановки по коду завершения, поэтому Gateway также сохраняет историю быстрых некорректных запусков и после повторяющихся сбоев запуска подавляет автоматический запуск учётных записей каналов и поставщиков. В этом безопасном режиме плоскость управления всё равно запускается для проверки и исправления, горячая перезагрузка конфигурации и `secrets.reload` не выполняют автоматический перезапуск каналов, а явный запрос оператора `channels.start` может отменить это ограничение.

## Быстрый запуск профиля разработки

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status
```

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

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

* Первым кадром клиента должен быть `connect`.
* Gateway возвращает кадр `hello-ok` с `snapshot` (`presence`, `health`, `stateVersion`, `uptimeMs`), а также ограничениями `policy` (`maxPayload`, `maxBufferedBytes`, `tickIntervalMs`).
* `hello-ok.features.methods` / `events` — это консервативный список для обнаружения, а не
  автоматически созданный перечень всех доступных для вызова вспомогательных маршрутов.
* Запросы: `req(method, params)` → `res(ok/payload|error)`.
* К распространённым событиям относятся `connect.challenge`, `agent`, `chat`,
  `session.message`, `session.operation`, `session.tool`, включаемые по желанию
  `session.approval`, `sessions.changed`, `presence`, `tick`, `health`,
  `heartbeat`, события жизненного цикла сопряжения и подтверждения, а также `shutdown`.

Запуски агента выполняются в два этапа:

1. Немедленное подтверждение принятия (`status:"accepted"`)
2. Итоговый ответ о завершении (`status:"ok"|"error"`), между ними передаются потоковые события `agent`.

Полную документацию протокола см. в разделе [Протокол Gateway](https://docs2.openclaw.ai/ru/gateway/protocol.md).

## Операционные проверки

### Доступность

* Откройте WS-соединение и отправьте `connect`.
* Ожидайте ответ `hello-ok` со снимком состояния.

### Готовность

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway status
openclaw channels status --probe
openclaw health
```

### Восстановление после пропусков

События не воспроизводятся повторно. При пропусках в последовательности обновите состояние (`health`, `system-presence`), прежде чем продолжить.

## Типичные признаки сбоев

| Признак | Вероятная проблема |
| - | - |
| `refusing to bind gateway ... without auth` | Привязка не к loopback-интерфейсу без допустимого способа аутентификации Gateway |
| `another gateway instance is already listening` / `EADDRINUSE` | Конфликт портов |
| `Gateway start blocked: set gateway.mode=local` | В конфигурации задан удалённый режим либо в повреждённой конфигурации отсутствует `gateway.mode` |
| `unauthorized` при подключении | Несоответствие параметров аутентификации клиента и Gateway |

Полные последовательности диагностики см. в разделе [Устранение неполадок Gateway](https://docs2.openclaw.ai/ru/gateway/troubleshooting.md).

## Гарантии безопасности

* Клиенты протокола Gateway немедленно завершают работу с ошибкой, если Gateway недоступен (без неявного перехода к прямому каналу).
* Недопустимые первые кадры и первые кадры, не предназначенные для подключения, отклоняются, после чего соединение закрывается.
* При корректном завершении работы перед закрытием сокета отправляется событие `shutdown`.

## Связанные разделы

* [Конфигурация](https://docs2.openclaw.ai/ru/gateway/configuration.md)
* [Устранение неполадок Gateway](https://docs2.openclaw.ai/ru/gateway/troubleshooting.md)
* [Фоновый процесс](https://docs2.openclaw.ai/ru/gateway/background-process.md)
* [Состояние системы](https://docs2.openclaw.ai/ru/gateway/health.md)
* [Doctor](https://docs2.openclaw.ai/ru/gateway/doctor.md)
* [Аутентификация](https://docs2.openclaw.ai/ru/gateway/authentication.md)
* [Удалённый доступ](https://docs2.openclaw.ai/ru/gateway/remote.md)
* [Управление секретами](https://docs2.openclaw.ai/ru/gateway/secrets.md)