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

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

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

openclaw gateway --port 18789# debug/trace mirrored to stdioopenclaw gateway --port 18789 --verbose# force-kill listener on selected port, then startopenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

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

• Один постійно запущений процес для маршрутизації, control plane і підключень каналів.
• Один мультиплексований порт для:
  • WebSocket-керування/RPC
  • HTTP API (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • HTTP-маршрутів Plugin, як-от необов’язковий /api/v1/admin/rpc
  • Control UI і хуків
• Типовий режим прив’язки: loopback.
• Автентифікація потрібна за замовчуванням. Налаштування зі спільним секретом використовують gateway.auth.token / gateway.auth.password (або OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD), а налаштування reverse proxy не через loopback можуть використовувати gateway.auth.mode: "trusted-proxy".

OpenAI-сумісні endpoints

Найцінніша поверхня сумісності 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- і memory-конвеєрів очікують /v1/embeddings.
• Agent-native клієнти дедалі частіше віддають перевагу /v1/responses.

Примітка щодо планування:

• /v1/models орієнтований насамперед на agent: він повертає openclaw, openclaw/default і openclaw/<agentId>.
• openclaw/default — стабільний псевдонім, який завжди відповідає налаштованому типовому agent.
• Використовуйте x-openclaw-model, коли потрібне перевизначення backend-провайдера/моделі; інакше звичайні налаштування моделі та embeddings вибраного agent залишаються керівними.

Усе це працює на основному порту Gateway і використовує ту саму межу автентифікації довіреного оператора, що й решта HTTP API Gateway.

Admin HTTP RPC (POST /api/v1/admin/rpc) — це окремий, типово вимкнений маршрут Plugin для host tooling, який не може використовувати WebSocket RPC. Див. Admin HTTP RPC.

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

Встановлені служби gateway записують визначений --port у metadata супервізора. Після зміни gateway.port запустіть openclaw doctor --fix або openclaw gateway install --force, щоб launchd/systemd/schtasks запускали процес на новому порту.

Під час запуску Gateway використовує той самий фактичний порт і прив’язку, коли засіває локальні джерела Control UI для прив’язок не через loopback. Наприклад, --bind lan --port 3000 засіває http://localhost:3000 і http://127.0.0.1:3000 до запуску runtime- валідації. Додавайте будь-які джерела віддаленого браузера, як-от HTTPS proxy URLs, до gateway.controlUi.allowedOrigins явно.

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

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

openclaw gateway statusopenclaw gateway status --deep   # adds a system-level service scanopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

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

Кілька gateways (той самий host)

Більшість установок мають запускати один gateway на машину. Один gateway може розміщувати кілька agents і каналів.

Кілька gateways потрібні лише тоді, коли ви навмисно хочете ізоляцію або rescue bot.

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

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, коли відповідають різні gateways або коли OpenClaw не може довести, що доступні цілі є тим самим gateway. SSH tunnel, proxy URL або налаштований remote URL до того самого gateway — це один gateway із кількома transport, навіть якщо порти transport відрізняються.
• Якщо це навмисно, ізолюйте порти, config/state і корені workspace для кожного 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@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 <user>

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.target [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5TimeoutStopSec=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

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

openclaw --dev setupopenclaw --dev gateway --allow-unconfiguredopenclaw --dev status

Типові значення включають ізольовані стан/конфігурацію та базовий порт gateway 19001.

Короткий довідник протоколу (погляд оператора)

• Першим кадром клієнта має бути connect.
• Gateway повертає знімок hello-ok (presence, health, stateVersion, uptimeMs, обмеження/політика).
• hello-ok.features.methods / events — це консервативний список для виявлення, а не згенерований дамп кожного callable helper route.
• Запити: req(method, params) → res(ok/payload|error).
• Поширені події включають connect.challenge, agent, chat, session.message, session.operation, session.tool, sessions.changed, presence, tick, health, heartbeat, події життєвого циклу pairing/approval і shutdown.

Запуски агента мають два етапи:

1. Негайне підтвердження прийняття (status:"accepted")
2. Фінальна відповідь про завершення (status:"ok"|"error"), із потоковими подіями agent між ними.

Див. повну документацію протоколу: Протокол Gateway.

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

Liveness

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

Readiness

openclaw gateway statusopenclaw channels status --probeopenclaw health

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

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

Поширені ознаки збоїв

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

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

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

Пов’язане:

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

Пов’язане

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