Guide d’exploitation du Gateway

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

# Démarrage local en 5 minutes

openclaw gateway --port 18789
# debug/trace mirrored to stdio
openclaw gateway --port 18789 --verbose
# force-kill listener on selected port, then start
openclaw gateway --force

openclaw gateway status
openclaw status
openclaw 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.
• 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é à plus fort levier 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 compte :

• 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 pensé d’abord pour les agents : il renvoie openclaw, openclaw/default et openclaw/<agentId>.
• openclaw/default est l’alias stable qui pointe toujours vers 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’embeddings de l’agent sélectionné restent aux commandes.

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.

# 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 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 toute origine de navigateur distante, comme les URL de proxy HTTPS, à gateway.controlUi.allowedOrigins.

# Modes de rechargement à chaud

# Ensemble de commandes opérateur

openclaw gateway status
openclaw gateway status --deep   # adds a system-level service scan
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor

gateway status --deep sert à une découverte supplémentaire de 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 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 intentionnellement une isolation ou un bot de secours.

Vérifications utiles :

openclaw gateway status --deep
openclaw gateway probe

À quoi vous attendre :

• gateway status --deep peut signaler Other gateway-like services detected (best effort) et afficher des conseils de nettoyage lorsque de vieilles installations launchd/systemd/schtasks sont encore présentes.
• gateway probe peut avertir au sujet de multiple reachable gateways lorsque plusieurs cibles répondent.
• Si c’est intentionnel, isolez les ports, la configuration/l’état et les racines d’espace de travail pour chaque 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 19001
OPENCLAW_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 install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

openclaw gateway install
systemctl --user enable --now openclaw-gateway[-<profile>].service
openclaw gateway status

sudo loginctl enable-linger <user>

[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
TimeoutStopSec=30
TimeoutStartSec=30
SuccessExitStatus=0 143
KillMode=control-group

[Install]
WantedBy=default.target

openclaw gateway install
openclaw gateway status --json
openclaw gateway restart
openclaw gateway stop

sudo systemctl daemon-reload
sudo systemctl enable --now openclaw-gateway[-<profile>].service

# Chemin rapide du profil de développement

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --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 l’instantané hello-ok (presence, health, stateVersion, uptimeMs, limites/politique).
• hello-ok.features.methods / events sont une liste de découverte conservatrice, pas un vidage généré de toutes les routes d’assistance 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 du cycle de vie d’appairage/approbation et shutdown.

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

1. Accusé de réception accepté 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

# Disponibilité

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

# Prêt à servir

openclaw gateway status
openclaw channels status --probe
openclaw 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 les enchaînements de diagnostic complets, utilisez Dépannage Gateway.

# Garanties de sécurité

• Les clients du protocole Gateway échouent rapidement lorsque Gateway est indisponible (aucun basculement implicite vers le canal direct).
• Les premières trames invalides/non-connect sont rejetées et fermées.
• L’arrêt gracieux émet l’événement shutdown avant la fermeture du socket.

Voir aussi :

• Dépannage
• Processus en arrière-plan
• Configuration
• État de santé
• Diagnostic
• Authentification

# Voir aussi

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