GatewayGateway runbook

Utilisez cette page pour le démarrage initial (day-1) et les opérations courantes (day-2) du service Gateway.

Deep troubleshooting

Diagnostics basés sur les symptômes avec des échelles de commande exactes et des signatures de journal.

Configuration

Guide de configuration orienté tâche + référence de configuration complète.

Secrets management

Contrat SecretRef, comportement de l’instantané d’exécution et opérations de migration/rechargement.

Secrets plan contract

Règles exactes secrets apply target/path et comportement ref-only auth-profile.

Démarrage local en 5 minutes

1. GatewayStart the Gateway

   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

2. Verify service health

   openclaw gateway status
   openclaw status
   openclaw logs --follow

   Ligne de base saine : Runtime: running, Connectivity probe: ok et Capability: ... correspondant à ce que vous attendez. Utilisez openclaw gateway status --require-rpcRPC lorsque vous avez besoin d’une preuve RPC de portée de lecture, et pas seulement d’accessibilité.

3. Validate channel readiness

   openclaw channels status --probe

   Avec une passerelle accessible, cela exécute des sondes de channel en direct par compte et des audits facultatifs. Si la passerelle est inaccessible, la CLI revient par défaut aux résumés de channel uniquement basés sur la configuration au lieu d’une sortie de sonde en direct.

Note

Le rechargement de la configuration de la Gateway surveille le chemin du fichier de configuration actif (résolu à partir des valeurs par défaut du profil/de l’état, ou GatewayOPENCLAW_CONFIG_PATH si défini). Le mode par défaut est gateway.reload.mode="hybrid". Après le premier chargement réussi, le processus en cours dessert l’instantané de configuration en mémoire actif ; un rechargement réussi échange cet instantané de manière atomique.

Modèle d’exécution

• Un processus toujours actif pour le routage, le plan de contrôle et les connexions de canal.
• Port multiplexé unique pour :
  • Contrôle WebSocket / RPC
  • API HTTP (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • Routes HTTP de plugins, telles que /api/v1/admin/rpc en option
  • Interface utilisateur de contrôle et crochets (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 en boucle locale peuvent utiliser gateway.auth.mode: "trusted-proxy".

Points de terminaison compatibles OpenAI

La surface de compatibilité la plus à fort impact 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 s’attendent à /v1/embeddings.
• Les clients natifs pour agents préfèrent de plus en plus /v1/responses.

Note de planification :

• /v1/models est centré sur 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 souhaitez un remplacement de fournisseur/model backend ; sinon, la configuration normale de modèle et d’incorporation de l’agent sélectionné reste en vigueur.

Tous ceux-ci s’exécutent sur le port principal du Gateway et utilisent la même limite d’authentification de l’opérateur de confiance que le reste de l’HTTP Gateway du API.

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. Voir RPC HTTP d’administration.

Priorité du port et de la liaison

Paramètre	Ordre de résolution
Port du Gateway	--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
Mode de liaison	CLI/override → gateway.bind → loopback

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 pour 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 lors de l’initialisation des origines de l’interface utilisateur de contrôle locale pour les liaisons non bouclage (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 navigateur distant, telles que les URL de proxy HTTPS, à gateway.controlUi.allowedOrigins.

Modes de rechargement à chaud

gateway.reload.mode	Comportement
off	Aucun rechargement de la configuration
hot	Appliquer uniquement les modifications sans risque à chaud
restart	Redémarrer en cas de modifications nécessitant un rechargement
hybrid (par défaut)	Appliquer à chaud si sûr, redémarrer si nécessaire

Jeu de commandes de l’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 est destiné à la découverte de services supplémentaire (LaunchDaemons/unités système systemd/schtasks), et non à une sonde de santé RPC plus approfondie.

Plusieurs Gateways (même hôte)

La plupart des installations doivent exécuter une seule Gateway par machine. Une seule Gateway peut héberger plusieurs agents et canaux.

Vous n’avez besoin de plusieurs Gateways que si vous souhaitez intentionnellement une isolation ou un robot de secours.

Vérifications utiles :

openclaw gateway status --deep
openclaw gateway probe

À quoi s’attendre :

• gateway status --deep peut signaler Other gateway-like services detected (best effort) et imprimer des conseils de nettoyage lorsque des installations launchd/systemd/schtasks périmées sont encore présentes.
• gateway probe peut avertir concernant multiple reachable gateways lorsque plus d’une cible répond.
• Si c’est intentionnel, isolez les ports, la configuration/l’état et les racines de l’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 à distance

Préféré : Tailscale/VPN. Alternative : Tunnel SSH.

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

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

Warning

Les tunnels SSH ne contournent pas l’authentification de la passerelle. Pour l’authentification par secret partagé, les clients doivent toujours envoyer

token

/

password

même via le tunnel. Pour les modes basés sur l’identité, la requête doit toujours satisfaire ce chemin d’authentification.

Voir : Remote Gateway, Authentication, Tailscale.

Supervision et cycle de vie du service

Utilisez des exécutions supervisées pour une fiabilité de type production.

macOS (launchd)Linux (systemd user)WindowsWindows (natif)LinuxLinux (service système)

openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

Utilisez openclaw gateway restart pour les redémarrages. Ne chaî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 supprime le LaunchAgent de la session de démarrage actuelle sans rendre la désactivation persistante, donc la récupération automatique KeepAlive fonctionne toujours après des plantages inattendus et gateway start réactive proprement. Pour supprimer de manière persistante la relance automatique après les redémarrages, passez --disable : openclaw gateway stop --disable.

Les étiquettes LaunchAgent sont ai.openclaw.gateway (par défaut) ou `ai.openclaw.

(profil nommé).openclaw doctor` audit et répare la dérive de configuration du service.

openclaw gateway install
systemctl --user enable --now openclaw-gateway[-

].service openclaw gateway status

Pour la persistance après la déconnexion, activez le mode persistant (lingering) :

```bash
sudo loginctl enable-linger

Exemple manuel d'unité utilisateur lorsque vous avez besoin d'un chemin d'installation personnalisé :

```ini
[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
```Windows

Le démarrage géré natif sur Windows utilise une tâche planifiée nommée `OpenClaw Gateway`
(ou `OpenClaw Gateway (

)OpenClaw pour les profils nommés). Si la création de la tâche planifiée est refusée, OpenClaw revient à un lanceur de dossier de Démarrage par utilisateur qui pointe vers gateway.cmd` à l’intérieur du répertoire d’état.

Utilisez une unité système pour les hôtes multi-utilisateur/toujours actifs.

sudo systemctl daemon-reload
sudo systemctl enable --now openclaw-gateway[-

].service

Utilisez le même corps de service que l'unité utilisateur, mais installez-le sous
`/etc/systemd/system/openclaw-gateway[-

].serviceet ajustezExecStart=si votre binaireopenclaw` se trouve ailleurs.

Ne laissez pas non plus openclaw doctor --fixOpenClaw installer un service de passerelle au niveau utilisateur pour le même profil/port. Doctor refuse cette installation automatique lorsqu’il détecte un service de passerelle OpenClaw au niveau système ; utilisez OPENCLAW_SERVICE_REPAIR_POLICY=external lorsque l’unité système possède le cycle de vie.

Chemin rapide du profil Dev

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status

Les valeurs par défaut incluent un état/configuration isolé et le port de passerelle de base 19001.

Référence rapide du protocole (vue opérateur)

• La première trame client doit être connect.
• La passerelle renvoie un instantané Gatewayhello-ok (presence, health, stateVersion, uptimeMs, limites/stratégie).
• hello-ok.features.methods / events sont une liste de découverte conservatrice, et non un vidage 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 du cycle de vie d’appariement/approbation, et shutdown.

Les exécutions de l’agent se déroulent en deux étapes :

1. Accusé de réception immédiat accepté (status:"accepted")
2. Réponse d’achèvement finale (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

Liveness

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

Readiness

openclaw gateway status
openclaw channels status --probe
openclaw health

Récupération de lacune

Les événements ne sont pas rejoués. En cas d’écarts dans la séquence, actualisez l’état (health, system-presence) avant de continuer.

Signatures d’échec courantes

Signature	Problème probable
refusing to bind gateway ... without auth	Liaison non-boucle sans un chemin d’authentification de passerelle valide
another gateway instance is already listening / EADDRINUSE	Conflit de port
Gateway start blocked: set gateway.mode=local	Configuration définie sur le mode distant, ou l’horodatage du mode local est manquant dans une configuration endommagée
unauthorized lors de la connexion	Non-concordance d’authentification entre le client et la passerelle

Pour les échelles de diagnostic complètes, utilisez Gateway Troubleshooting.

Garanties de sécurité

• Les clients du protocole Gateway échouent rapidement lorsque Gateway n’est pas disponible (pas de repli implicite sur le channel direct).
• Les premières trames non valides ou non connectées sont rejetées et fermées.
• L’arrêt progressif émet l’événement shutdown avant la fermeture du socket.

---

Connexes :

• Troubleshooting
• Processus d’arrière-plan
• Configuration
• Santé
• Doctor
• Authentification

Connexes

• Configuration
• Gateway troubleshooting
• Accès à distance
• Gestion des secrets