Guide d’exploitation du Gateway

Utilisez cette page pour le démarrage initial et l’exploitation courante du service Gateway.

Démarrage local en 5 minutes

openclaw gateway --port 18789# débogage/traçage répliqué vers les flux d’E/S standardopenclaw gateway --port 18789 --verbose# arrêter de force le processus à l’écoute sur le port sélectionné, puis démarreropenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

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

openclaw gateway statusopenclaw gateway status --deep   # ajoute une analyse du service au niveau systèmeopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

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 :

openclaw gateway status --deepopenclaw gateway probe

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 :

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002

Configuration détaillée : /gateway/multiple-gateways.

Accès distant

Option recommandée : Tailscale/VPN. Solution de repli : tunnel SSH.

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

Connectez ensuite localement les clients à ws://127.0.0.1:18789.

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.

openclaw gateway installopenclaw gateway statusopenclaw gateway restartopenclaw gateway stop

openclaw gateway installsystemctl --user enable --now openclaw-gateway[-<profile>].serviceopenclaw gateway status

sudo loginctl enable-linger $(whoami)

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.targetStartLimitBurst=5StartLimitIntervalSec=60 [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5RestartPreventExitStatus=78TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143OOMPolicy=continueKillMode=control-group [Install]WantedBy=default.target

openclaw gateway installopenclaw gateway status --jsonopenclaw gateway restartopenclaw gateway stop

sudo systemctl daemon-reloadsudo systemctl enable --now openclaw-gateway[-<profile>].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

openclaw --dev setupopenclaw --dev gateway --allow-unconfiguredopenclaw --dev status

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

openclaw gateway statusopenclaw channels status --probeopenclaw health

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

• Configuration
• Dépannage du Gateway
• Processus en arrière-plan
• État de santé
• Doctor
• Authentification
• Accès distant
• Gestion des secrets