Gateway‑Dienst‑Runbook¶

Use this page for day-1 startup and day-2 operations of the Gateway service.

Symptom-first diagnostics with exact command ladders and log signatures. Task-oriented setup guide + full configuration reference.

5-minute local startup¶

openclaw gateway --port 18789
# for full debug/trace logs in stdio:
openclaw gateway --port 18789 --verbose
# if the port is busy, terminate listeners then start:
openclaw gateway --force
# dev loop (auto-reload on TS changes):
pnpm gateway:watch

openclaw --profile main gateway install
openclaw --profile rescue gateway install

Healthy baseline: Runtime: running and RPC probe: ok.

openclaw channels status --probe

Gateway config reload watches the active config file path (resolved from profile/state defaults, or OPENCLAW_CONFIG_PATH when set). Standardmodus: gateway.reload.mode="hybrid" (sichere Änderungen hot anwenden, Neustart bei kritischen Änderungen).

Runtime model¶

One always-on process for routing, control plane, and channel connections.
Single‑Port‑Multiplex.
WebSocket control/RPC
OpenResponses (HTTP): /v1/responses.
Control UI and hooks
Default bind mode: loopback.
Gateway‑Authentifizierung ist standardmäßig erforderlich: setzen Sie gateway.auth.token (oder OPENCLAW_GATEWAY_TOKEN) oder gateway.auth.password.

Port and bind precedence¶

Setting	Resolution order
Abgeleitete Ports (Faustregeln):	Port‑Priorität: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > Standard `18789`.
Bind mode	CLI/override → `gateway.bind` → `loopback`

Hot reload modes¶

Deaktivieren mit `gateway.reload.mode="off"`.	Behavior
`off`	No config reload
`hot`	Apply only hot-safe changes
`restart`	Restart on reload-required changes
`hybrid` (default)	Hot-apply when safe, restart when required

Operator command set¶

openclaw gateway status
openclaw gateway install
openclaw gateway stop
openclaw gateway restart
openclaw logs --follow

Remote‑Zugriff¶

Tailscale/VPN bevorzugt; andernfalls SSH‑Tunnel: Fallback: SSH tunnel.

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

Clients verbinden sich anschließend über den Tunnel mit ws://127.0.0.1:18789.

Wenn ein Token konfiguriert ist, müssen Clients es auch über den Tunnel in connect.params.auth.token mitsenden.

See: Remote Gateway, Authentication, Tailscale.

Supervision and service lifecycle¶

Use supervised runs for production-like reliability.

Zum Neustart verwenden Sie `openclaw gateway restart` (oder `launchctl kickstart -k gui/$UID/bot.molt.gateway`).

OpenClaw.app kann ein Node‑basiertes Gateway‑Relay bündeln und einen benutzerbezogenen LaunchAgent mit der Bezeichnung bot.molt.gateway (oder bot.molt.<profile>; Legacy com.openclaw.*‑Labels werden weiterhin sauber entladen).(named profile).openclaw doctor` audits and repairs service config drift.

systemctl --user enable --now openclaw-gateway[-<profile>].service

Aktivieren Sie Lingering (erforderlich, damit der Benutzerdienst Logout/Idle überlebt):

sudo loginctl enable-linger youruser

Use a system unit for multi-user/always-on hosts.

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

Mehrere Gateways (gleicher Host)¶

Most setups should run one Gateway. Verwenden Sie mehrere Gateways nur für Redundanz oder strikte Isolation (z. B.

Checkliste pro Instanz:

eindeutiges gateway.port
eindeutiges OPENCLAW_CONFIG_PATH
eindeutiges OPENCLAW_STATE_DIR
eindeutiges agents.defaults.workspace

Beispiel:

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

Vollständige Anleitung: Multiple gateways.

Dev‑Profil (`--dev`)¶

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
# then target the dev instance:
openclaw --dev status
openclaw --dev health

Defaults include isolated state/config and base gateway port 19001.

Protokoll (Operator‑Sicht)¶

First client frame must be connect.
Gateway returns hello-ok snapshot (presence, health, stateVersion, uptimeMs, limits/policy).
Requests: {type:"req", id, method, params} → {type:"res", id, ok, payload|error}
Common events: connect.challenge, agent, chat, presence, tick, health, heartbeat, shutdown.

Agent runs are two-stage:

Immediate accepted ack (status:"accepted")
agent‑Antworten sind zweistufig: zuerst res‑Ack {runId,status:"accepted"}, dann ein finales res {runId,status:"ok"|"error",summary} nach Abschluss des Laufs; gestreamte Ausgabe trifft als event:"agent" ein.

Vollständige Doku: Gateway‑Protokoll und Bridge‑Protokoll (Legacy).

Betriebliche Prüfungen¶

Liveness¶

Open WS and send connect.
Expect hello-ok response with snapshot.

Readiness¶

`openclaw gateway health|status` — Health/Status über den Gateway‑WS anfordern.

Gap recovery¶

Events werden nicht wiederholt. On sequence gaps, refresh state (health, system-presence) before continuing.

Common failure signatures¶

Signature	Likely issue
`refusing to bind gateway ... without auth`	Non-loopback bind without token/password
`another gateway instance is already listening` / `EADDRINUSE`	Port conflict
`Gateway start blocked: set gateway.mode=local`	Config set to remote mode
`unauthorized` during connect	Auth mismatch between client and gateway

For full diagnosis ladders, use Gateway Troubleshooting.

Sicherheitsgarantien¶

Gateway protocol clients fail fast when Gateway is unavailable (no implicit direct-channel fallback).
Invalid/non-connect first frames are rejected and closed.
Geordneter Shutdown: Emit shutdown‑Event vor dem Schließen; Clients müssen Close + Reconnect handhaben.