Passerelle

Runbook de la Passerelle

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

Dépannage approfondi

Diagnostics par symptôme avec des échelles de commandes exactes et des signatures de logs.

Configuration

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

Gestion des secrets

Contrat SecretRef, comportement du snapshot d'exécution, et opérations de migration/rechargement.

Contrat du plan de secrets

Règles exactes d'application des secrets (cible/chemin) et comportement auth-profile ref-only.

Démarrage local en 5 minutes

Étape 1 : Démarrer la Passerelle

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

Étape 2 : Vérifier l'intégrité du service

openclaw gateway status
openclaw status
openclaw logs --follow

État sain de base : Runtime: running et RPC probe: ok.

Étape 3 : Valider la disponibilité des canaux

openclaw channels status --probe

ℹ️ Le rechargement de la configuration de la passerelle surveille le chemin du fichier de configuration actif (résolu à partir des valeurs par défaut du profil/état, ou OPENCLAW_CONFIG_PATH lorsqu'il est défini). Le mode par défaut est gateway.reload.mode="hybrid".

Modèle d'exécution

  • Un processus toujours actif pour le routage, le plan de contrôle et les connexions de canaux.
  • Port multiplexé unique pour :
    • WebSocket contrôle/RPC
    • APIs HTTP (compatible OpenAI, Réponses, invocation d'outils)
    • Interface de contrôle et hooks
  • Mode de liaison par défaut : loopback.
  • L'authentification est requise par défaut (gateway.auth.token / gateway.auth.password, ou OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).

Priorité du port et de la liaison

ParamètreOrdre de résolution
Port de la passerelle--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
Mode de liaisonCLI/override → gateway.bind → loopback

Modes de rechargement à chaud

gateway.reload.modeComportement
offPas de rechargement de configuration
hotApplique uniquement les changements sûrs à chaud
restartRedémarre sur les changements nécessitant un rechargement
hybrid (par défaut)Applique à chaud quand c'est sûr, redémarre quand c'est nécessaire

Ensemble de commandes opérateur

openclaw gateway status
openclaw gateway status --deep
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor

Accès à distance

Préféré : Tailscale/VPN. Solution de repli : tunnel SSH.

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

Ensuite, connectez les clients localement à ws://127.0.0.1:18789.

⚠️ Si l'authentification de la passerelle est configurée, les clients doivent toujours envoyer l'authentification (token/password) même via des tunnels SSH.

Voir : Passerelle distante, Authentification, Tailscale.

Supervision et cycle de vie du service

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

openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

Passerelles multiples sur un même hôte

La plupart des configurations doivent exécuter une seule Passerelle. Utilisez-en plusieurs uniquement pour une isolation/redondance stricte (par exemple un profil de secours). Liste de contrôle 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

Voir : Passerelles multiples.

Chemin rapide du profil de développement

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status

Les valeurs par défaut incluent un état/config isolé et un port de passerelle de base 19001.

Référence rapide du protocole (vue opérateur)

  • La première trame du client doit être connect.
  • La passerelle renvoie un snapshot hello-ok (presence, health, stateVersion, uptimeMs, limites/politique).
  • Requêtes : req(method, params) → res(ok/payload|error).
  • Événements courants : connect.challenge, agent, chat, presence, tick, health, heartbeat, shutdown.

Les exécutions d'agent sont en deux étapes :

  1. Accusé de réception immédiat (status:"accepted")
  2. Réponse de finalisation (status:"ok"|"error"), avec des événements agent diffusés entre les deux.

Voir la documentation complète du protocole : Protocole de la Passerelle.

Vérifications opérationnelles

Vivacité

  • Ouvrir WS et envoyer connect.
  • Attendre une réponse hello-ok avec un snapshot.

Disponibilité

openclaw gateway status
openclaw channels status --probe
openclaw health

Récupération d'écart

Les événements ne sont pas rejoués. En cas d'écart de séquence, rafraîchir l'état (health, system-presence) avant de continuer.

Signatures courantes de défaillance

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 en mode distant
unauthorized pendant la connexionIncompatibilité d'authentification entre le client et la passerelle

Pour des échelles de diagnostic complètes, utilisez Dépannage de la Passerelle.

Garanties de sécurité

  • Les clients du protocole de la passerelle échouent rapidement lorsque la Passerelle est indisponible (pas de repli implicite sur le canal direct).
  • Les premières trames invalides/non-connect sont rejetées et la connexion est fermée.
  • L'arrêt gracieux émet un événement shutdown avant la fermeture du socket.

Liens connexes :

Configuration