Gateway

• Par défaut, le Gateway refuse de démarrer sauf si gateway.mode=local est défini dans ~/.openclaw/openclaw.json. Utilisez --allow-unconfigured pour les exécutions ponctuelles/de développement.
• openclaw onboard --mode local et openclaw setup sont censés écrire gateway.mode=local. Si le fichier existe mais que gateway.mode est absent, considérez cela comme une configuration cassée ou écrasée et réparez-la au lieu de supposer implicitement le mode local.
• Si le fichier existe et que gateway.mode est absent, le Gateway considère cela comme une altération suspecte de la configuration et refuse de « deviner local » pour vous.
• L’écoute au-delà du loopback sans authentification est bloquée (garde-fou de sécurité).
• SIGUSR1 déclenche un redémarrage dans le processus lorsqu’il est autorisé (commands.restart est activé par défaut ; définissez commands.restart: false pour bloquer le redémarrage manuel, tandis que les applications/mises à jour via l’outil/la configuration du gateway restent autorisées).
• Les gestionnaires SIGINT/SIGTERM arrêtent le processus gateway, mais ils ne restaurent aucun état de terminal personnalisé. Si vous encapsulez la CLI avec une TUI ou une entrée en mode brut, restaurez le terminal avant de quitter.

• Les enregistrements conservent les métadonnées opérationnelles : noms d’événements, nombres, tailles en octets, relevés mémoire, état des files/sessions, noms de canaux/plugins et résumés de sessions expurgés. Ils ne conservent pas le texte des discussions, les corps de webhook, les sorties d’outils, les corps bruts de requête ou de réponse, les jetons, les cookies, les valeurs secrètes, les noms d’hôte ni les ids de session bruts. Définissez diagnostics.enabled: false pour désactiver entièrement l’enregistreur.
• Lors des sorties fatales du Gateway, des délais d’arrêt dépassés et des échecs de démarrage après redémarrage, OpenClaw écrit le même instantané de diagnostic dans ~/.openclaw/logs/stability/openclaw-stability-*.json lorsque l’enregistreur contient des événements. Inspectez le bundle le plus récent avec openclaw gateway stability --bundle latest ; --limit, --type et --since-seq s’appliquent aussi à la sortie du bundle.

• gateway status reste disponible pour le diagnostic même lorsque la configuration CLI locale est manquante ou invalide.
• Par défaut, gateway status vérifie l’état du service, la connexion WebSocket et la capacité d’authentification visible au moment de la poignée de main. Il ne vérifie pas les opérations de lecture/écriture/administration.
• Les sondes de diagnostic ne modifient pas l’authentification d’un appareil lors de sa première utilisation : elles réutilisent un jeton d’appareil déjà mis en cache lorsqu’il existe, mais elles ne créent pas une nouvelle identité d’appareil CLI ni un enregistrement d’appairage d’appareil en lecture seule simplement pour vérifier l’état.
• gateway status résout les SecretRefs d’authentification configurés pour l’authentification de la sonde lorsque c’est possible.
• Si un SecretRef d’authentification requis n’est pas résolu dans ce chemin de commande, gateway status --json signale rpc.authWarning lorsque la connectivité/l’authentification de la sonde échoue ; passez explicitement --token/--password ou résolvez d’abord la source du secret.
• Si la sonde réussit, les avertissements d’auth-ref non résolue sont supprimés pour éviter les faux positifs.
• Utilisez --require-rpc dans les scripts et l’automatisation lorsqu’un service à l’écoute ne suffit pas et que les appels RPC à portée de lecture doivent aussi être sains.
• --deep ajoute une analyse au mieux des installations launchd/systemd/schtasks supplémentaires. Lorsque plusieurs services de type Gateway sont détectés, la sortie lisible par l’humain affiche des conseils de nettoyage et avertit que la plupart des configurations devraient exécuter un seul Gateway par machine.
• --deep signale aussi un transfert récent de redémarrage du superviseur du Gateway lorsque le processus du service s’est terminé proprement pour un redémarrage par un superviseur externe.
• --deep exécute la validation de configuration en mode compatible avec les plugins (pluginValidation: "full") et expose les avertissements de manifeste de plugin configuré (par exemple des métadonnées de configuration de canal manquantes) afin que les vérifications rapides d’installation et de mise à jour les détectent. Par défaut, gateway status conserve le chemin rapide en lecture seule qui ignore la validation des plugins.
• La sortie lisible par l’humain inclut le chemin résolu du fichier de journal ainsi qu’un instantané des chemins/validités de configuration CLI par rapport au service afin d’aider à diagnostiquer les dérives de profil ou de répertoire d’état.

• Sur les installations Linux systemd, les vérifications de dérive d’authentification du service lisent les valeurs Environment= et EnvironmentFile= de l’unité (y compris %h, les chemins entre guillemets, plusieurs fichiers et les fichiers optionnels -).
• Les vérifications de dérive résolvent les SecretRefs gateway.auth.token avec l’environnement d’exécution fusionné (d’abord l’environnement de commande du service, puis l’environnement du processus en solution de repli).
• Si l’authentification par jeton n’est pas effectivement active (gateway.auth.mode explicite à password/none/trusted-proxy, ou mode non défini lorsque le mot de passe peut l’emporter et qu’aucun candidat de jeton ne peut l’emporter), les vérifications de dérive de jeton ignorent la résolution du jeton de configuration.

• Reachable: yes signifie qu’au moins une cible a accepté une connexion WebSocket.
• Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only indique ce que la sonde a pu vérifier au sujet de l’authentification. C’est distinct de la joignabilité.
• Read probe: ok signifie que les appels RPC de détail à portée de lecture (health/status/system-presence/config.get) ont également réussi.
• Read probe: limited - missing scope: operator.read signifie que la connexion a réussi, mais que le RPC à portée de lecture est limité. Cela est signalé comme une joignabilité dégradée, et non comme un échec complet.
• Read probe: failed après Connect: ok signifie que le Gateway a accepté la connexion WebSocket, mais que les diagnostics de lecture suivants ont expiré ou échoué. Cela est aussi une joignabilité dégradée, et non un Gateway injoignable.
• Comme gateway status, la sonde réutilise l’authentification d’appareil déjà mise en cache, mais ne crée pas d’identité d’appareil ni d’état d’appairage lors d’une première utilisation.
• Le code de sortie n’est non nul que lorsqu’aucune cible sondée n’est joignable.

Niveau supérieur :

• ok : au moins une cible est joignable.
• degraded : au moins une cible a accepté une connexion mais n’a pas terminé les diagnostics RPC détaillés complets.
• capability : meilleure capacité observée parmi les cibles joignables (read_only, write_capable, admin_capable, pairing_pending, connected_no_operator_scope ou unknown).
• primaryTargetId : meilleure cible à traiter comme gagnante active dans cet ordre : URL explicite, tunnel SSH, distant configuré, puis local loopback.
• warnings[] : enregistrements d’avertissement au mieux avec code, message et targetIds facultatif.
• network : indices d’URL local loopback/tailnet dérivés de la configuration actuelle et du réseau de l’hôte.
• discovery.timeoutMs et discovery.count : budget de découverte réel/nombre de résultats utilisé pour ce passage de sonde.

Par cible (targets[].connect) :

• ok : joignabilité après connexion + classification dégradée.
• rpcOk : réussite complète du RPC détaillé.
• scopeLimited : le RPC détaillé a échoué en raison d’une portée opérateur manquante.

Par cible (targets[].auth) :

• role : rôle d’authentification signalé dans hello-ok lorsqu’il est disponible.
• scopes : portées accordées signalées dans hello-ok lorsqu’elles sont disponibles.
• capability : classification de capacité d’authentification exposée pour cette cible.

• ssh_tunnel_failed : la configuration du tunnel SSH a échoué ; la commande est revenue aux sondes directes.
• multiple_gateways : plus d’une cible était joignable ; c’est inhabituel sauf si vous exécutez intentionnellement des profils isolés, comme un bot de secours.
• auth_secretref_unresolved : un SecretRef d’authentification configuré n’a pas pu être résolu pour une cible en échec.
• probe_scope_limited : la connexion WebSocket a réussi, mais la sonde de lecture a été limitée par l’absence de operator.read.

• gateway status : --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
• gateway install : --port, --runtime <node|bun>, --token, --wrapper <path>, --force, --json
• gateway restart : --safe, --skip-deferral, --force, --wait <duration>, --json
• gateway uninstall|start : --json
• gateway stop : --disable, --json

• Utilisez gateway restart pour redémarrer un service géré. N’enchaînez pas gateway stop et gateway start comme substitut de redémarrage.
• Sur macOS, gateway stop utilise launchctl bootout par défaut, ce qui retire le LaunchAgent de la session de démarrage actuelle sans rendre persistante une désactivation — la récupération automatique KeepAlive reste active pour les futurs plantages et gateway start se réactive proprement sans launchctl enable manuel. Passez --disable pour supprimer durablement KeepAlive et RunAtLoad afin que le Gateway ne redémarre pas jusqu’au prochain gateway start explicite ; utilisez cette option lorsqu’un arrêt manuel doit survivre aux redémarrages de la machine ou du système.
• gateway restart --safe demande au Gateway en cours d’exécution de vérifier en amont le travail OpenClaw actif et de différer le redémarrage jusqu’à ce que la livraison des réponses, les exécutions embarquées et les exécutions de tâches soient terminées. --safe ne peut pas être combiné avec --force ou --wait.
• gateway restart --wait 30s remplace le budget d’attente configuré pour ce redémarrage. Les nombres nus sont en millisecondes ; les unités comme s, m et h sont acceptées. --wait 0 attend indéfiniment.
• gateway restart --safe --skip-deferral exécute le redémarrage sûr compatible OpenClaw, mais contourne la barrière de différé afin que le Gateway émette le redémarrage immédiatement même lorsque des blocages sont signalés. Échappatoire opérateur pour les différés d’exécutions de tâches bloquées ; nécessite --safe.
• gateway restart --force ignore l’attente de vidage du travail actif et redémarre immédiatement. Utilisez cette option lorsqu’un opérateur a déjà inspecté les blocages de tâches listés et veut remettre le Gateway en service maintenant.
• Les commandes de cycle de vie acceptent --json pour les scripts.

• Lorsque l’authentification par jeton exige un jeton et que gateway.auth.token est géré par SecretRef, gateway install vérifie que la SecretRef peut être résolue, mais ne persiste pas le jeton résolu dans les métadonnées d’environnement du service.
• Si l’authentification par jeton exige un jeton et que la SecretRef de jeton configurée n’est pas résolue, l’installation échoue fermée au lieu de persister un texte en clair de secours.
• Pour l’authentification par mot de passe avec gateway run, préférez OPENCLAW_GATEWAY_PASSWORD, --password-file ou un gateway.auth.password adossé à une SecretRef plutôt que --password en ligne.
• En mode d’authentification inféré, OPENCLAW_GATEWAY_PASSWORD limité au shell n’assouplit pas les exigences de jeton à l’installation ; utilisez une configuration durable (gateway.auth.password ou env de configuration) lors de l’installation d’un service géré.
• Si gateway.auth.token et gateway.auth.password sont tous deux configurés et que gateway.auth.mode n’est pas défini, l’installation est bloquée jusqu’à ce que le mode soit défini explicitement.