Runbook 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 (/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

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

Ensemble 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 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 --deepopenclaw 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 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é de type 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 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

Chemin rapide du profil de développement

openclaw --dev setupopenclaw --dev gateway --allow-unconfiguredopenclaw --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 statusopenclaw channels status --probeopenclaw 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

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

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

Associé

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