Passer au contenu principal

​
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

1

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
2

Verify service health

openclaw --profile main gateway install
openclaw --profile rescue gateway install
Référence saine : Runtime: running et RPC probe: ok.
3

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ètreOrdre de résolution
Port du GatewayPriorité des ports : --port > OPENCLAW_GATEWAY_PORT > gateway.port > valeur par défaut 18789.
Mode de liaisonCLI/surcharge → gateway.bind → loopback

​
Modes de rechargement à chaud

Désactiver avec gateway.reload.mode="off".Comportement keepalive
offAucun rechargement de la configuration
hotAppliquer uniquement les modifications sûres à chaud
restartRedé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. 
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.

​
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 :
  1. Accusé de réception immédiat accepté (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

  • 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

SignatureProblème probable
refusing to bind gateway ... without authLiaison non-loopback sans token/mot de passe
another gateway instance is already listening / EADDRINUSEConflit de port
Gateway start blocked: set gateway.mode=localConfiguration définie en mode distant
Instantané de connexionIncompatibilité 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 :