Passer au contenu principal

​
Runbook du Gateway

Utilisez cette page pour le démarrage du premier jour et les opérations du deuxième jour du service Gateway.

Dépannage approfondi

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

Configuration

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

Gestion des secrets

Contrat SecretRef, comportement des instantanés d’exécution, et opérations de migration/rechargement.

Contrat du plan des secrets

Règles exactes des cibles/chemins de secrets apply et comportement des profils d’authentification en mode ref-only.

​
Démarrage local en 5 minutes

1

Démarrer le Gateway

openclaw gateway --port 18789
# débogage/trace recopiés vers stdio
openclaw gateway --port 18789 --verbose
# force l’arrêt de l’écouteur sur le port sélectionné, puis démarre
openclaw gateway --force
2

Vérifier l’état de santé du service

openclaw gateway status
openclaw status
openclaw logs --follow
Référence saine : Runtime: running, Connectivity probe: ok, et Capability: ... qui correspond à ce que vous attendez. Utilisez openclaw gateway status --require-rpc lorsque vous avez besoin d’une preuve RPC en portée lecture, et pas seulement d’une joignabilité.
3

Valider l’état de préparation des canaux

openclaw channels status --probe
Avec un gateway joignable, cela exécute des sondes de canaux en direct par compte ainsi que des audits facultatifs. Si le gateway est inaccessible, la CLI bascule vers des résumés de canaux basés uniquement sur la configuration au lieu de la sortie des sondes en direct.
Le rechargement de la configuration du Gateway surveille le chemin du fichier de configuration actif (résolu à partir des valeurs par défaut du profil/de l’état, ou de OPENCLAW_CONFIG_PATH lorsqu’il est défini). Le mode par défaut est gateway.reload.mode="hybrid". Après le premier chargement réussi, le processus en cours d’exécution sert l’instantané de configuration actif en mémoire ; un rechargement réussi remplace cet instantané de manière atomique.

​
Modèle d’exécution

  • Un processus toujours actif pour le routage, le plan de contrôle et les connexions de canaux.
  • Un port multiplexé unique pour :
    • le contrôle/RPC WebSocket
    • les API HTTP, compatibles OpenAI (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
    • l’interface utilisateur de contrôle et les hooks
  • Mode de liaison par défaut : loopback.
  • L’authentification est requise par défaut. Les configurations à secret partagé utilisent gateway.auth.token / gateway.auth.password (ou OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD), et les configurations de proxy inverse non-loopback peuvent utiliser gateway.auth.mode: "trusted-proxy".

​
Endpoints compatibles OpenAI

La surface de compatibilité la plus utile d’OpenClaw est désormais :
  • GET /v1/models
  • GET /v1/models/{id}
  • POST /v1/embeddings
  • POST /v1/chat/completions
  • POST /v1/responses
Pourquoi cet ensemble est important :
  • La plupart des intégrations Open WebUI, LobeChat et LibreChat interrogent d’abord /v1/models.
  • De nombreux pipelines RAG et de mémoire attendent /v1/embeddings.
  • Les clients natifs pour agents préfèrent de plus en plus /v1/responses.
Note de planification :
  • /v1/models est orienté agent : il renvoie openclaw, openclaw/default et openclaw/<agentId>.
  • openclaw/default est l’alias stable qui pointe toujours vers l’agent par défaut configuré.
  • Utilisez x-openclaw-model lorsque vous souhaitez un remplacement du fournisseur/modèle backend ; sinon, la configuration normale du modèle et des embeddings de l’agent sélectionné reste maîtresse.
Tous ceux-ci s’exécutent sur le port principal du Gateway et utilisent la même limite d’authentification d’opérateur de confiance que le reste de l’API HTTP du Gateway.

​
Priorité du port et du mode de liaison

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

​
Modes de rechargement à chaud

gateway.reload.modeComportement
offAucun 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

​
Jeu de commandes opérateur

openclaw gateway status
openclaw gateway status --deep   # ajoute une analyse du service au niveau système
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor
gateway status --deep sert à une découverte de services supplémentaire (LaunchDaemons/unités systemd système /schtasks), pas à une sonde d’état de santé RPC plus approfondie.

​
Plusieurs gateways (même hôte)

La plupart des installations doivent exécuter un gateway par machine. Un seul gateway peut héberger plusieurs agents et canaux. Vous n’avez besoin de plusieurs gateways que si vous voulez délibérément de l’isolation ou un bot de secours. Vérifications utiles : 
openclaw gateway status --deep
openclaw gateway probe
Ce à quoi s’attendre :
  • gateway status --deep peut signaler Other gateway-like services detected (best effort) et afficher des conseils de nettoyage lorsque d’anciennes installations launchd/systemd/schtasks sont encore présentes.
  • gateway probe peut avertir de multiple reachable gateways lorsque plus d’une cible répond.
  • Si cela est intentionnel, isolez les ports, la configuration/l’état et les racines d’espace de travail pour chaque gateway.
Configuration détaillée : /gateway/multiple-gateways.

​
Accès distant

Préféré : Tailscale/VPN. Solution de repli : tunnel SSH. 
ssh -N -L 18789:127.0.0.1:18789 user@host
Connectez ensuite les clients localement à ws://127.0.0.1:18789.
Les tunnels SSH ne contournent pas l’authentification du gateway. Pour une authentification à secret partagé, les clients doivent toujours envoyer token/password même via le tunnel. Pour les modes porteurs d’identité, la requête doit toujours satisfaire ce chemin d’authentification.
Voir : Gateway distant, Authentification, Tailscale.

​
Supervision et cycle de vie du service

Utilisez des exécutions supervisées pour une fiabilité de niveau production. 
openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop
Les libellés LaunchAgent sont ai.openclaw.gateway (par défaut) ou ai.openclaw.<profile> (profil nommé). openclaw doctor audite et répare les dérives de configuration du service.

​
Plusieurs gateways sur un même hôte

La plupart des configurations doivent exécuter un Gateway. N’utilisez plusieurs gateways que 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 : Plusieurs gateways.

​
Chemin rapide du profil dev

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status
Les valeurs par défaut incluent un état/une configuration isolés et un port Gateway de base 19001.

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

  • La première trame cliente doit être connect.
  • Le Gateway renvoie un instantané hello-ok (presence, health, stateVersion, uptimeMs, limits/policy).
  • hello-ok.features.methods / events sont une liste de découverte prudente, et non un dump généré de toutes les routes d’assistance appelables.
  • Requêtes : req(method, params) → res(ok/payload|error).
  • Les événements courants incluent connect.challenge, agent, chat, session.message, session.tool, sessions.changed, presence, tick, health, heartbeat, les événements du cycle de vie d’appairage/approbation, et shutdown.
Les exécutions d’agent se déroulent en deux étapes :
  1. Accusé de réception immédiat accepté (status:"accepted")
  2. Réponse finale de fin (status:"ok"|"error"), avec des événements agent diffusés entre les deux.
Voir la documentation complète du protocole : Protocole Gateway.

​
Vérifications opérationnelles

​
Disponibilité

  • Ouvrez un WS et envoyez connect.
  • Attendez une réponse hello-ok avec instantané.

​
État de préparation

openclaw gateway status
openclaw channels status --probe
openclaw health

​
Récupération après rupture

Les événements ne sont pas rejoués. En cas de trou 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 chemin d’authentification gateway valide
another gateway instance is already listening / EADDRINUSEConflit de port
Gateway start blocked: set gateway.mode=localConfiguration définie en mode distant, ou tampon de mode local manquant dans une configuration endommagée
unauthorized during connectIncompatibilité d’authentification entre le client et le gateway
Pour des séquences complètes de diagnostic, utilisez Dépannage Gateway.

​
Garanties de sécurité

  • Les clients du protocole Gateway échouent rapidement lorsque le Gateway n’est pas disponible (pas de bascule implicite directe vers le canal).
  • Les premières trames invalides/non-connect sont rejetées et la connexion est fermée.
  • L’arrêt propre émet un événement shutdown avant la fermeture du socket.
Associé :