Runbook du service Gateway

Utilisez cette page pour le démarrage jour 1 et les opérations jour 2 du service Gateway.

Deep troubleshooting

Diagnostics orientés symptômes avec séquences de commandes exactes et signatures de logs.

Configuration

Guide d’installation orienté tâches + référence complète de configuration.

Démarrage local en 5 minutes

Start the Gateway

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

Verify service health

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

Référence saine : Runtime: running et RPC probe: ok.

Validate channel readiness

openclaw channels status --probe

Le rechargement de la configuration Gateway surveille le chemin actif du fichier de configuration (résolu à partir des valeurs par défaut du profil/état, ou OPENCLAW_CONFIG_PATH lorsqu’il est défini). Mode par défaut : gateway.reload.mode="hybrid" (application à chaud des changements sûrs, redémarrage pour les changements critiques).

Modèle d’exécution

Un processus toujours actif pour le routage, le plan de contrôle et les connexions aux canaux.
Multiplexage sur un port unique.
- Contrôle/RPC WebSocket
- OpenResponses (HTTP) : /v1/responses.
- Interface de contrôle et hooks
Mode de liaison par défaut : loopback.
L’authentification Gateway est requise par défaut : définissez gateway.auth.token (ou OPENCLAW_GATEWAY_TOKEN) ou gateway.auth.password.

Priorité du port et du mode de liaison

Paramètre	Ordre de résolution
Port du Gateway	Priorité des ports : `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > valeur par défaut `18789`.
Mode de liaison	CLI/surcharge → `gateway.bind` → `loopback`

Modes de rechargement à chaud

Désactiver avec `gateway.reload.mode="off"`.	Comportement keepalive
`off`	Aucun rechargement de la configuration
`hot`	Appliquer uniquement les modifications sûres à chaud
`restart`	Redémarrer si des modifications nécessitent un rechargement
`hybrid` (par défaut)	Appliquer à chaud lorsque c’est sûr, redémarrer lorsque nécessaire

Ensemble de commandes opérateur

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

Accès distant

Tailscale/VPN recommandé ; sinon tunnel SSH : Solution de secours : tunnel SSH.

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.

Voir : Remote Gateway, Authentication, Tailscale.

Supervision et cycle de vie du service

Utilisez des exécutions supervisées pour une fiabilité proche de la production.

macOS (launchd)
Linux (systemd user)
Linux (system service)

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

Les labels LaunchAgent sont ai.openclaw.gateway (par défaut) ou ai.openclaw.<profile> lors de l’exécution d’un profil nommé. openclaw doctor audite et corrige les dérives de configuration du service.

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

Utilisez une unité système pour les hôtes multi-utilisateurs ou toujours actifs.

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

Les paramètres par défaut incluent un état/configuration isolé et le port de base du gateway 19001.

Protocole (vue opérateur)

La première trame client doit être connect.
Le Gateway renvoie un instantané hello-ok (presence, health, stateVersion, uptimeMs, limites/policy).
Requêtes : {type:"req", id, method, params} → {type:"res", id, ok, payload|error}
Événements courants : connect.challenge, agent, chat, presence, tick, health, heartbeat, shutdown.

Les exécutions d’agent se déroulent en deux étapes :

Accusé de réception immédiat accepté (status:"accepted")
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

Ouvrez la connexion WS et envoyez connect.
Attendez la réponse hello-ok avec l’instantané.

Disponibilité

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

Récupération des écarts

Les événements ne sont pas rejoués. En cas d’écarts de séquence, actualisez l’état (health, system-presence) avant de continuer.

Signatures d’échec courantes

Signature	Problème probable
`refusing to bind gateway ... without auth`	Liaison non-loopback sans token/mot de passe
`another gateway instance is already listening` / `EADDRINUSE`	Conflit de port
`Gateway start blocked: set gateway.mode=local`	Configuration définie en mode distant
Instantané de connexion	Incompatibilité d’authentification entre le client et le Gateway

Pour un diagnostic complet étape par étape, consultez Gateway Troubleshooting.

Garanties de sécurité

Les clients du protocole Gateway échouent immédiatement lorsque le Gateway est indisponible (aucun fallback implicite vers un canal direct).
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.

Liens connexes :

Gateway

Accès à distance

Interfaces Web

Runbook du Gateway

Runbook du service Gateway

Deep troubleshooting

Configuration

Démarrage local en 5 minutes

Modèle d’exécution

Priorité du port et du mode de liaison

Modes de rechargement à chaud

Ensemble de commandes opérateur

Accès distant

Supervision et cycle de vie du service

Gateways multiples (même hôte)

Profil dev (`--dev`)

Protocole (vue opérateur)

Vérifications opérationnelles

KeepAlive : true

Disponibilité

Récupération des écarts

Signatures d’échec courantes

Garanties de sécurité

​Runbook du service Gateway

Deep troubleshooting

Configuration

​Démarrage local en 5 minutes

​Modèle d’exécution

​Priorité du port et du mode de liaison

​Modes de rechargement à chaud

​Ensemble de commandes opérateur

​Accès distant

​Supervision et cycle de vie du service

​Gateways multiples (même hôte)

​Profil dev (--dev)

​Protocole (vue opérateur)

​Vérifications opérationnelles

​KeepAlive : true

​Disponibilité

​Récupération des écarts

​Signatures d’échec courantes

​Garanties de sécurité

Runbook du service Gateway

Démarrage local en 5 minutes

Modèle d’exécution

Priorité du port et du mode de liaison

Modes de rechargement à chaud

Ensemble de commandes opérateur

Accès distant

Supervision et cycle de vie du service

Gateways multiples (même hôte)

Profil dev (`--dev`)

Protocole (vue opérateur)

Vérifications opérationnelles

KeepAlive : true

Disponibilité

Récupération des écarts

Signatures d’échec courantes

Garanties de sécurité