Skip to main content
Utilisez cette page pour le démarrage initial et l’exploitation courante 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 axé sur les tâches et référence complète de la configuration.

Gestion des secrets

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

Contrat du plan de secrets

Règles exactes de cible/chemin de secrets apply et comportement des profils d’authentification reposant uniquement sur des références.

​
Démarrage local en 5 minutes

1

Démarrer le Gateway

2

Vérifier l’état du service

État sain de référence : Runtime: running, Connectivity probe: ok et une ligne Capability correspondant à vos attentes. Utilisez openclaw gateway status --require-rpc pour vérifier le RPC avec une portée de lecture, et pas seulement l’accessibilité.
3

Valider la disponibilité des canaux

Lorsque le Gateway est accessible, cette commande exécute des sondes de canal en direct pour chaque compte ainsi que des audits facultatifs. Si le Gateway est inaccessible, la CLI se rabat sur des récapitulatifs des canaux fondés uniquement sur la configuration.
Le rechargement de la configuration du Gateway surveille le chemin du fichier de configuration actif (déterminé à partir des valeurs par défaut du profil/de l’état, ou de OPENCLAW_CONFIG_PATH lorsque cette variable est définie). Le mode par défaut est gateway.reload.mode="hybrid". Après le premier chargement réussi, le processus en cours d’exécution utilise l’instantané actif de la configuration 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 aux canaux.
  • Un seul port multiplexé pour :
    • le contrôle/RPC WebSocket ;
    • les API HTTP (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke) ;
    • les routes HTTP des Plugins, comme la route facultative /api/v1/admin/rpc ;
    • l’interface de contrôle et les hooks.
  • Mode de liaison par défaut : loopback. Dans un environnement de conteneur détecté, la valeur par défaut effective est auto (résolue en 0.0.0.0 pour la redirection de ports), sauf si le service ou le funnel Tailscale est actif, auquel cas loopback est toujours imposé.
  • 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 hors loopback peuvent utiliser gateway.auth.mode: "trusted-proxy".

​
Points de terminaison compatibles avec OpenAI

La surface de compatibilité d’OpenClaw offrant le plus d’impact :
  • 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 privilégient de plus en plus /v1/responses.
/v1/models est centré sur les agents : il renvoie openclaw, openclaw/default et openclaw/<agentId> pour chaque agent configuré. openclaw/default est l’alias stable qui correspond toujours à l’agent par défaut configuré. Envoyez x-openclaw-model lorsque vous souhaitez remplacer le fournisseur/modèle du backend ; sinon, la configuration normale du modèle et des embeddings de l’agent sélectionné reste utilisée. Tous ces points de terminaison s’exécutent sur le port principal du Gateway et utilisent la même frontière 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 distincte, désactivée par défaut, destinée aux outils de l’hôte qui ne peuvent pas utiliser le RPC WebSocket. Consultez RPC HTTP d’administration.

​
Priorité du port et de la liaison

Les services Gateway installés enregistrent la valeur résolue de --port 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. Au démarrage, le Gateway utilise le même port et le même mode de liaison effectifs lorsqu’il initialise les origines locales de l’interface de contrôle pour les liaisons hors loopback. Par exemple, --bind lan --port 3000 initialise http://localhost:3000 et http://127.0.0.1:3000 avant l’exécution de la validation. Ajoutez explicitement toute origine de navigateur distant, comme les URL de proxy HTTPS, à gateway.controlUi.allowedOrigins.

​
Modes de rechargement à chaud

​
Ensemble de commandes pour l’opérateur

gateway status --deep sert à effectuer une détection supplémentaire des services (LaunchDaemons/unités système systemd/schtasks), et non une vérification plus approfondie de l’état du RPC.

​
Plusieurs Gateways (sur le même hôte)

La plupart des installations doivent exécuter un seul Gateway par machine. Un seul Gateway peut héberger plusieurs agents et canaux. Vous n’avez besoin de plusieurs Gateways que si vous souhaitez délibérément les isoler ou disposer d’un bot de secours. Vérifications utiles :
Résultats attendus :
  • 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 toujours présentes.
  • gateway probe peut avertir de la présence de multiple reachable gateway identities lorsque plusieurs Gateways distincts répondent, ou lorsqu’OpenClaw ne peut pas prouver que les cibles accessibles correspondent au même Gateway. Un tunnel SSH, une URL de proxy ou une URL distante configurée vers le même Gateway correspond à un seul Gateway utilisant plusieurs transports, même lorsque les ports de transport diffèrent.
  • Si cela est intentionnel, isolez les ports, la configuration/l’état et les racines des espaces de travail pour chaque Gateway.
Liste de contrôle par instance :
  • Valeur gateway.port unique
  • Valeur OPENCLAW_CONFIG_PATH unique
  • Valeur OPENCLAW_STATE_DIR unique
  • Valeur agents.defaults.workspace unique
Exemple :
Configuration détaillée : /gateway/multiple-gateways.

​
Accès distant

Option recommandée : Tailscale/VPN. Solution de repli : tunnel SSH.
Connectez ensuite localement les clients à ws://127.0.0.1:18789.
Les tunnels SSH ne contournent pas l’authentification du Gateway. Pour l’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 parcours d’authentification.
Consultez : Gateway distant, Authentification, Tailscale.

​
Supervision et cycle de vie du service

Utilisez des exécutions supervisées pour obtenir une fiabilité proche de celle d’un environnement de production.
Utilisez openclaw gateway restart pour les redémarrages. N’enchaînez pas openclaw gateway stop et openclaw gateway start pour remplacer un redémarrage.Sous macOS, gateway stop utilise launchctl bootout par défaut. Cela supprime le LaunchAgent de la session de démarrage actuelle sans conserver un état désactivé, de sorte que la récupération automatique KeepAlive continue de fonctionner après les arrêts inattendus et que gateway start le réactive correctement. Pour empêcher durablement le redémarrage automatique après les redémarrages du système, transmettez --disable : openclaw gateway stop --disable.Les libellés LaunchAgent sont ai.openclaw.gateway (par défaut) ou ai.openclaw.<profile> (profil nommé). openclaw doctor audite et corrige les dérives de la configuration du service.
Les erreurs de configuration non valide entraînent une sortie avec le code 78. Les unités systemd Linux utilisent RestartPreventExitStatus=78 pour interrompre les relancements jusqu’à ce que la configuration soit corrigée. launchd et le Planificateur de tâches Windows ne disposent pas d’une règle équivalente d’arrêt selon le code de sortie ; le Gateway conserve donc également l’historique des démarrages incorrects rapprochés et désactive le démarrage automatique des comptes de canaux/fournisseurs après des échecs de démarrage répétés. Dans ce mode sécurisé, le plan de contrôle démarre toujours afin de permettre l’inspection et la réparation, les rechargements à chaud de la configuration et secrets.reload refusent les redémarrages automatiques des canaux, et une requête explicite channels.start de l’opérateur peut remplacer cette désactivation.

​
Parcours rapide avec le profil de développement

Les valeurs par défaut comprennent une configuration et un état isolés, ainsi que le port Gateway de base 19001.

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

  • La première trame du client doit être connect.
  • Le Gateway renvoie une trame hello-ok avec un snapshot (presence, health, stateVersion, uptimeMs), ainsi que les limites de policy (maxPayload, maxBufferedBytes, tickIntervalMs).
  • hello-ok.features.methods / events constituent une liste de découverte prudente, et non une liste générée de toutes les routes auxiliaires pouvant être appelées.
  • Requêtes : req(method, params) → res(ok/payload|error).
  • Les événements courants comprennent connect.challenge, agent, chat, session.message, session.operation, session.tool, l’événement facultatif session.approval, sessions.changed, presence, tick, health, heartbeat, les événements du cycle de vie de l’appairage/de l’approbation et shutdown.
Les exécutions d’agent se déroulent en deux étapes :
  1. Accusé de réception immédiat (status:"accepted")
  2. Réponse finale d’achèvement (status:"ok"|"error"), avec des événements agent diffusés entre les deux.
Consultez la documentation complète du protocole : Protocole du Gateway.

​
Vérifications opérationnelles

​
Disponibilité

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

​
État de préparation

​
Récupération après une interruption

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

​
Signatures d’échec courantes

Pour consulter les procédures de diagnostic complètes, utilisez Dépannage du Gateway.

​
Garanties de sécurité

  • Les clients du protocole Gateway échouent immédiatement lorsque le Gateway est indisponible (aucun repli implicite vers un canal direct).
  • Les premières trames non valides ou autres que des trames de connexion sont rejetées, puis la connexion est fermée.
  • L’arrêt progressif émet l’événement shutdown avant la fermeture du socket.

​
Voir aussi