Runbook du service Gateway¶

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). Mode par défaut : gateway.reload.mode="hybrid" (application à chaud des changements sûrs, redémarrage pour les changements critiques).

Runtime model¶

• One always-on process for routing, control plane, and channel connections.
• Multiplexage sur un port unique.
• WebSocket control/RPC
• OpenResponses (HTTP) : /v1/responses.
• Control UI and hooks
• Default bind mode: loopback.
• L’authentification Gateway est requise par défaut : définissez gateway.auth.token (ou OPENCLAW_GATEWAY_TOKEN) ou gateway.auth.password.

Port and bind precedence¶

Setting	Resolution order
Gateway port	Priorité des ports : --port > OPENCLAW_GATEWAY_PORT > gateway.port > valeur par défaut 18789.
Bind mode	CLI/override → gateway.bind → loopback

Hot reload modes¶

Désactiver avec gateway.reload.mode="off".	Comportement keepalive
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

Accès distant¶

Tailscale/VPN recommandé ; sinon tunnel SSH : Fallback: SSH tunnel.

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

Les clients se connectent ensuite à ws://127.0.0.1:18789 via le tunnel.

Si un jeton est configuré, les clients doivent l’inclure dans connect.params.auth.token même via le tunnel.

See: Remote Gateway, Authentication, Tailscale.

Supervision and service lifecycle¶

Use supervised runs for production-like reliability.

Pour redémarrer, utilisez `openclaw gateway restart` (ou `launchctl kickstart -k gui/$UID/bot.molt.gateway`).

LaunchAgent labels are ai.openclaw.gateway (default) or ai.openclaw.<profile> lors de l’exécution d’un profil nommé. openclaw doctor audits and repairs service config drift.

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

Activez le lingering (requis pour que le service utilisateur survive à la déconnexion/inactivité) :

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

Gateways multiples (même hôte)¶

Généralement inutile : un Gateway peut servir plusieurs canaux de messagerie et agents. Utilisez plusieurs Gateways uniquement pour la redondance ou une isolation stricte (ex. bot de secours).

Checklist par instance :

• gateway.port unique
• OPENCLAW_CONFIG_PATH unique
• OPENCLAW_STATE_DIR unique
• agents.defaults.workspace unique

Exemple :

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

Guide complet : Multiple gateways.

Profil dev (--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.

Protocole (vue opérateur)¶

• First client frame must be connect.
• Gateway returns hello-ok snapshot (presence, health, stateVersion, uptimeMs, limits/policy).
• Requêtes : {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:

1. Immediate accepted ack (status:"accepted")
2. Les réponses agent sont en deux étapes : d’abord un accusé res {runId,status:"accepted"}, puis un res final {runId,status:"ok"|"error",summary} après la fin de l’exécution ; la sortie streamée arrive sous forme de event:"agent".

Documentation complète : Gateway protocol et Bridge protocol (legacy).

Vérifications opérationnelles¶

KeepAlive : true¶

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

Readiness¶

`openclaw gateway health|status` — demander l’état/la santé via le WS du Gateway.

Gap recovery¶

Les événements ne sont pas rejoués. 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
Instantané de connexion	Auth mismatch between client and gateway

For full diagnosis ladders, use Gateway Troubleshooting.

Garanties de sécurité¶

• Gateway protocol clients fail fast when Gateway is unavailable (no implicit direct-channel fallback).
• Les premières trames non conformes ou le JSON malformé sont rejetés et la socket est fermée.
• Arrêt gracieux : émettre l’événement shutdown avant la fermeture ; les clients doivent gérer la fermeture + reconnexion.

---

Related:

• Troubleshooting
• Background Process
• Configuration
• Health
• Doctor
• Authentication