Utilisez cette page pour le démarrage du jour 1 et les opérations du jour 2 du service Gateway.Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
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 de configuration complète.
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 cible/chemin de
secrets apply et comportement des profils d’authentification par référence uniquement.Démarrage local en 5 minutes
Vérifier l’état du service
Runtime: running, Connectivity probe: ok et Capability: ... correspondant à ce que vous attendez. Utilisez openclaw gateway status --require-rpc lorsque vous avez besoin d’une preuve RPC avec périmètre de lecture, et pas seulement d’une joignabilité.Le rechargement de la configuration du Gateway surveille le chemin du fichier de configuration actif (résolu depuis les 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".
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é atomiquement.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, compatibles OpenAI (
/v1/models,/v1/embeddings,/v1/chat/completions,/v1/responses,/tools/invoke) - Interface de contrôle et 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(ouOPENCLAW_GATEWAY_TOKEN/OPENCLAW_GATEWAY_PASSWORD), et les configurations de proxy inverse non-loopback peuvent utilisergateway.auth.mode: "trusted-proxy".
Points de terminaison compatibles OpenAI
La surface de compatibilité la plus utile d’OpenClaw est désormais :GET /v1/modelsGET /v1/models/{id}POST /v1/embeddingsPOST /v1/chat/completionsPOST /v1/responses
- 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 préfèrent de plus en plus
/v1/responses.
/v1/modelsest pensé d’abord pour les agents : il renvoieopenclaw,openclaw/defaultetopenclaw/<agentId>.openclaw/defaultest l’alias stable qui correspond toujours à l’agent par défaut configuré.- Utilisez
x-openclaw-modellorsque vous voulez une substitution du fournisseur/modèle backend ; sinon, la configuration normale du modèle et des embeddings de l’agent sélectionné reste aux commandes.
Précédence du port et de la liaison
| Paramètre | Ordre de résolution |
|---|---|
| Port Gateway | --port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789 |
| Mode de liaison | CLI/override → gateway.bind → loopback |
--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.
Au démarrage, le Gateway utilise le même port effectif et la même liaison lorsqu’il initialise les origines locales
de l’interface de contrôle pour les liaisons non-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 d’exécution. Ajoutez explicitement toutes les origines de navigateurs distants, comme les URL de proxy HTTPS, à
gateway.controlUi.allowedOrigins.
Modes de rechargement à chaud
gateway.reload.mode | Comportement |
|---|---|
off | Aucun rechargement de configuration |
hot | Applique uniquement les changements sûrs à chaud |
restart | Redémarre pour les changements nécessitant un rechargement |
hybrid (par défaut) | Applique à chaud si sûr, redémarre si nécessaire |
Jeu de commandes opérateur
gateway status --deep sert à la découverte supplémentaire des services (LaunchDaemons/unités système 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 seul Gateway peut héberger plusieurs agents et canaux. Vous n’avez besoin de plusieurs Gateways que si vous voulez intentionnellement de l’isolation ou un bot de secours. Vérifications utiles :gateway status --deeppeut signalerOther gateway-like services detected (best effort)et afficher des conseils de nettoyage lorsque d’anciennes installations launchd/systemd/schtasks sont encore présentes.gateway probepeut avertir à propos demultiple reachable gatewayslorsque plusieurs cibles répondent.- Si c’est intentionnel, isolez les ports, la configuration/l’état et les racines d’espaces de travail par Gateway.
gateway.portuniqueOPENCLAW_CONFIG_PATHuniqueOPENCLAW_STATE_DIRuniqueagents.defaults.workspaceunique
Accès distant
Préféré : Tailscale/VPN. Solution de repli : tunnel SSH.ws://127.0.0.1:18789.
Voir : Gateway distant, Authentification, Tailscale.
Supervision et cycle de vie du service
Utilisez des exécutions supervisées pour une fiabilité proche de la production.- macOS (launchd)
- Linux (systemd utilisateur)
- Windows (natif)
- Linux (service système)
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, de sorte que la récupération automatique KeepAlive fonctionne toujours après des plantages inattendus et que gateway start le réactive proprement. Pour supprimer durablement la relance automatique entre les redémarrages, passez --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 répare la dérive de configuration du service.Chemin rapide du profil dev
19001.
Référence rapide du protocole (vue opérateur)
- La première trame client doit être
connect. - Le Gateway renvoie l’instantané
hello-ok(presence,health,stateVersion,uptimeMs, limites/politique). hello-ok.features.methods/eventssont une liste de découverte prudente, pas un dump généré de toutes les routes d’aide 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 de cycle de vie d’appairage/approbation etshutdown.
- Accusé d’acceptation immédiat (
status:"accepted") - Réponse finale de complétion (
status:"ok"|"error"), avec des événementsagentdiffusés entre les deux.
Contrôles opérationnels
Vivacité
- Ouvrir WS et envoyer
connect. - Attendre une réponse
hello-okavec instantané.
Disponibilité
Récupération des lacunes
Les événements ne sont pas rejoués. En cas de lacunes de séquence, actualisez l’état (health, system-presence) avant de continuer.
Signatures de défaillance courantes
| Signature | Problème probable |
|---|---|
refusing to bind gateway ... without auth | Liaison non-loopback sans chemin d’authentification de gateway valide |
another gateway instance is already listening / EADDRINUSE | Conflit de port |
Gateway start blocked: set gateway.mode=local | Configuration définie en mode distant, ou horodatage du mode local absent d’une configuration endommagée |
unauthorized pendant la connexion | Incompatibilité d’authentification entre le client et le gateway |
Garanties de sécurité
- Les clients du protocole Gateway échouent rapidement lorsque le Gateway est indisponible (pas de repli implicite vers un canal direct).
- Les premières trames invalides ou non connectées sont rejetées et fermées.
- L’arrêt gracieux émet l’événement
shutdownavant la fermeture du socket.
Associé :