Посібник з експлуатації Gateway

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

Локальний запуск за 5 хвилин

openclaw gateway --port 18789# налагодження/трасування дублюється у stdioopenclaw gateway --port 18789 --verbose# примусово завершує слухач на вибраному порту, а потім запускаєopenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

Модель виконання

• Один постійно активний процес для маршрутизації, площини керування та з’єднань каналів.
• Один мультиплексований порт для:
  • керування/RPC через WebSocket
  • HTTP API (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • HTTP-маршрутів Plugin, наприклад необов’язкового /api/v1/admin/rpc
  • інтерфейсу керування та хуків
• Стандартний режим прив’язки: loopback. У виявленому контейнерному середовищі фактичне стандартне значення — auto (визначається як 0.0.0.0 для переспрямування портів), якщо не активовано Tailscale serve/funnel, що завжди примусово встановлює 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) — це окремий, стандартно вимкнений маршрут Plugin для інструментів хоста, які не можуть використовувати RPC через WebSocket. Див. Адміністративний HTTP RPC.

Пріоритет порту та прив’язки

Установлені служби 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 до перевірки конфігурації під час виконання. Явно додайте всі джерела віддалених браузерів, наприклад URL-адреси HTTPS-проксі, до gateway.controlUi.allowedOrigins.

Режими гарячого перезавантаження

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

openclaw gateway statusopenclaw gateway status --deep   # додає сканування служб на рівні системиopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

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

Кілька Gateway (на одному хості)

У більшості інсталяцій слід запускати один Gateway на машину. Один Gateway може обслуговувати кілька агентів і каналів. Кілька Gateway потрібні лише для навмисної ізоляції або резервного бота.

Корисні перевірки:

openclaw gateway status --deepopenclaw 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

Приклад:

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002

Докладне налаштування: /gateway/multiple-gateways.

Віддалений доступ

Рекомендовано: Tailscale/VPN. Резервний варіант: SSH-тунель.

ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

Після цього підключайте клієнтів локально до ws://127.0.0.1:18789.

Див.: Віддалений Gateway, Автентифікація, Tailscale.

Нагляд і життєвий цикл служби

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

openclaw gateway installopenclaw gateway statusopenclaw gateway restartopenclaw gateway stop

openclaw gateway installsystemctl --user enable --now openclaw-gateway[-<profile>].serviceopenclaw gateway status

sudo loginctl enable-linger $(whoami)

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.targetStartLimitBurst=5StartLimitIntervalSec=60 [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5RestartPreventExitStatus=78TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143OOMPolicy=continueKillMode=control-group [Install]WantedBy=default.target

openclaw gateway installopenclaw gateway status --jsonopenclaw gateway restartopenclaw gateway stop

sudo systemctl daemon-reloadsudo systemctl enable --now openclaw-gateway[-<profile>].service

У разі помилок неприпустимої конфігурації процес завершується з кодом 78. Модулі systemd у Linux використовують RestartPreventExitStatus=78, щоб припинити повторні запуски, доки конфігурацію не буде виправлено. launchd і планувальник завдань Windows не мають еквівалентного правила зупинки для окремого коду завершення, тому Gateway також зберігає історію швидких некоректних запусків і пригнічує автоматичний запуск облікових записів каналів/провайдерів після повторних помилок запуску. У цьому безпечному режимі площина керування все одно запускається для перевірки й виправлення, гарячі перезавантаження конфігурації та secrets.reload відмовляються автоматично перезапускати канали, а явний запит оператора channels.start може скасувати це пригнічення.

Швидкий шлях для профілю розробки

openclaw --dev setupopenclaw --dev gateway --allow-unconfiguredopenclaw --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.

Операційні перевірки

Працездатність

• Відкрийте WS і надішліть connect.
• Очікуйте відповідь hello-ok зі знімком стану.

Готовність

openclaw gateway statusopenclaw channels status --probeopenclaw health

Відновлення після пропуску

Події не відтворюються повторно. У разі пропусків у послідовності оновіть стан (health, system-presence), перш ніж продовжувати.

Поширені ознаки помилок

Повні послідовності діагностики див. у розділі Усунення несправностей Gateway.

Гарантії безпеки

• Клієнти протоколу Gateway негайно завершують роботу з помилкою, коли Gateway недоступний (без неявного резервного переходу на прямий канал).
• Недійсні перші кадри або кадри, що не призначені для підключення, відхиляються, а з’єднання закривається.
• Під час коректного завершення роботи перед закриттям сокета надсилається подія shutdown.

Пов’язані матеріали

• Конфігурація
• Усунення несправностей Gateway
• Фоновий процес
• Стан системи
• Doctor
• Автентифікація
• Віддалений доступ
• Керування секретами