Guide d’exploitation du Gateway

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

Démarrage local en 5 minutes

openclaw gateway --port 18789# debug/trace mirrored to stdioopenclaw gateway --port 18789 --verbose# force-kill listener on selected port, then startopenclaw 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 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 (ou OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD), et les configurations de proxy inverse non-loopback peuvent utiliser gateway.auth.mode: "trusted-proxy".

Points de terminaison 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 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.

Note de planification :

• /v1/models est pensé d’abord pour les agents : 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 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.

Tout cela s’exécute sur le port principal du Gateway et utilise la même frontière d’authentification opérateur de confiance que le reste de l’API HTTP du Gateway.

Précédence du port et de la liaison

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.

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

Jeu de commandes opérateur

openclaw gateway statusopenclaw gateway status --deep   # adds a system-level service scanopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

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 :

openclaw gateway status --deepopenclaw gateway probe

À 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 à propos de multiple reachable gateways lorsque plusieurs cibles répondent.
• Si c’est intentionnel, isolez les ports, la configuration/l’état et les racines d’espaces de travail par Gateway.

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 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

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.

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.

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 <user>

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.target [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143KillMode=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

Chemin rapide du profil dev

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

Les valeurs par défaut incluent une configuration/un état 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 l’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 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 et shutdown.

Les exécutions d’agents se font en deux étapes :

1. Accusé d’acceptation immédiat (status:"accepted")
2. Réponse finale de complétion (status:"ok"|"error"), avec des événements agent diffusés entre les deux.

Voir la documentation complète du protocole : Protocole Gateway.

Contrôles opérationnels

Vivacité

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

Disponibilité

openclaw gateway statusopenclaw channels status --probeopenclaw health

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

Pour des procédures de diagnostic complètes, utilisez Dépannage du 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 shutdown avant la fermeture du socket.

Associé :

• Dépannage
• Processus en arrière-plan
• Configuration
• Santé
• Doctor
• Authentification

Associé

• Configuration
• Dépannage du Gateway
• Accès distant
• Gestion des secrets