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

Dépannage approfondi

Diagnostics axés sur les 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 de plan des secrets

Règles exactes de cible/chemin secrets apply et comportement de profil d’authentification par référence uniquement.

​
Démarrage local en 5 minutes

1

Démarrer le Gateway

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
2

Vérifier la santé du service

openclaw gateway status
openclaw status
openclaw logs --follow
Référence saine : Runtime: running, Connectivity probe: ok et Capability: ... qui correspondent à 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 preuve d’accessibilité.
3

Valider l’état de préparation du canal

openclaw channels status --probe
Avec un Gateway accessible, cette commande exécute des sondes de canal en direct par compte et des audits facultatifs. Si le Gateway est inaccessible, la CLI revient à des résumés de canaux basés uniquement sur la configuration au lieu d’une sortie de sonde 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 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.
  • Port multiplexé unique pour :
    • contrôle/RPC WebSocket
    • API HTTP (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
    • routes HTTP de Plugin, comme la route facultative /api/v1/admin/rpc
    • UI de contrôle et hooks
  • Mode de liaison par défaut : loopback.
  • L’authentification est requise par défaut. Les configurations avec secret partagé utilisent gateway.auth.token / gateway.auth.password (ou OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD), et les configurations reverse-proxy non-loopback peuvent utiliser gateway.auth.mode: "trusted-proxy".

​
Points de terminaison compatibles OpenAI

La surface de compatibilité la plus efficace 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 sondent d’abord /v1/models.
  • De nombreux pipelines RAG et de mémoire attendent /v1/embeddings.
  • Les clients natifs pour agents privilégient de plus en plus /v1/responses.
Note de planification :
  • /v1/models est centré agent : il renvoie openclaw, openclaw/default et openclaw/<agentId>.
  • openclaw/default est l’alias stable qui correspond toujours à l’agent par défaut configuré.
  • Utilisez x-openclaw-model lorsque vous voulez remplacer le fournisseur/modèle backend ; sinon, le modèle normal et la configuration d’embedding de l’agent sélectionné restent maîtres.
Tous ces éléments 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. Le RPC HTTP d’administration (POST /api/v1/admin/rpc) est une route de Plugin séparée, désactivée par défaut, pour les outils hôtes qui ne peuvent pas utiliser le RPC WebSocket. Voir RPC HTTP d’administration.

​
Priorité du port et de la liaison

ParamètreOrdre de résolution
Port Gateway--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
Mode liaisonCLI/remplacement → gateway.bind → loopback
Les services Gateway installés enregistrent le --port résolu dans les métadonnées du superviseur. Après avoir modifié gateway.port, exécutez openclaw doctor --fix ou openclaw gateway install --force afin que launchd/systemd/schtasks démarre le processus sur le nouveau port. Le démarrage du Gateway utilise le même port et la même liaison effectifs lorsqu’il amorce les origines locales de l’UI de contrôle pour les liaisons non-loopback. Par exemple, --bind lan --port 3000 amorce http://localhost:3000 et http://127.0.0.1:3000 avant l’exécution de la validation d’exécution. Ajoutez explicitement toute origine de navigateur distant, comme les URL de proxy HTTPS, à gateway.controlUi.allowedOrigins.

​
Modes de rechargement à chaud

gateway.reload.modeComportement
offAucun rechargement de configuration
hotAppliquer uniquement les changements sûrs à chaud
restartRedémarrer lors des changements nécessitant un redémarrage
hybrid (par défaut)Appliquer à chaud si sûr, redémarrer lorsque c’est requis

​
Ensemble de commandes opérateur

openclaw gateway status
openclaw gateway status --deep   # adds a system-level service scan
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 à la découverte supplémentaire de services (unités système LaunchDaemons/systemd/schtasks), pas à une sonde de santé RPC plus approfondie.

​
Gateways multiples (même hôte)

La plupart des installations devraient exécuter un Gateway par machine. Un Gateway unique peut héberger plusieurs agents et canaux. Vous n’avez besoin de plusieurs Gateways que lorsque vous voulez intentionnellement une isolation ou un bot de secours. Vérifications utiles : 
openclaw gateway status --deep
openclaw gateway probe
À quoi s’attendre :
  • gateway status --deep peut signaler Other gateway-like services detected (best effort) et afficher des indications de nettoyage lorsque d’anciennes installations launchd/systemd/schtasks sont encore présentes.
  • gateway probe peut avertir de multiple reachable gateway identities lorsque des Gateways distincts répondent, ou lorsqu’OpenClaw ne peut pas prouver que les cibles accessibles sont le même Gateway. Un tunnel SSH, une URL de proxy ou une URL distante configurée vers le même Gateway constitue un seul Gateway avec plusieurs transports, même lorsque les ports de transport diffèrent.
  • Si c’est intentionnel, isolez les ports, la configuration/l’état et les racines d’espace de travail par Gateway.
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
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 l’authentification par 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 type production. 
openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop
Utilisez openclaw gateway restart pour les redémarrages. N’enchaînez pas openclaw gateway stop et openclaw gateway start comme substitut de redémarrage.Sur macOS, gateway stop utilise launchctl bootout par défaut — cela retire le LaunchAgent de la session de démarrage actuelle sans persister de désactivation, donc la récupération automatique KeepAlive fonctionne toujours après des plantages inattendus et gateway start le réactive proprement. Pour supprimer durablement le redémarrage automatique entre les redémarrages système, passez --disable : openclaw gateway stop --disable.Les labels 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.

​
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/une configuration isolés et le port Gateway de base 19001.

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

  • La première trame client doit être connect.
  • Le Gateway renvoie un instantané hello-ok (presence, health, stateVersion, uptimeMs, limites/politique).
  • hello-ok.features.methods / events sont une liste de découverte prudente, pas un dump généré de chaque route d’assistance appelable.
  • Requêtes : req(method, params) → res(ok/payload|error).
  • Les événements courants incluent connect.challenge, agent, chat, session.message, session.operation, session.tool, sessions.changed, presence, tick, health, heartbeat, les événements de cycle de vie d’appariement/approbation, et shutdown.
Les exécutions d’agent se déroulent en deux étapes :
  1. Accusé d’acceptation immédiat (status:"accepted")
  2. Réponse finale d’achèvement (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

​
Vivacité

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

​
État de préparation

openclaw gateway status
openclaw channels status --probe
openclaw health

​
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 de défaillance 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 marqueur du mode local manquant dans une configuration endommagée
unauthorized during connectIncompatibilité d’authentification entre le client et le Gateway
Pour des diagnostics complets étape par étape, utilisez Dépannage du Gateway.

​
Garanties de sécurité

  • Les clients du protocole Gateway échouent rapidement lorsque le Gateway est indisponible (aucun basculement implicite vers un canal direct).
  • Les premières trames invalides ou sans connexion sont rejetées et fermées.
  • L’arrêt progressif émet un événement shutdown avant la fermeture du socket.
Associé :

​
Associé