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 un dommage de configuration suspect et refuse de « deviner local » à votre place.
• La liaison 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 l’application/la mise à jour de l’outil et de 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, compteurs, tailles en octets, mesures de mémoire, état des files/sessions, noms de canaux/plugins et résumés de session expurgés. Ils ne conservent pas le texte de discussion, les corps de webhook, les sorties d’outils, les corps bruts de requête ou de réponse, les tokens, les cookies, les valeurs secrètes, les noms d’hôte ni les identifiants bruts de session. Définissez diagnostics.enabled: false pour désactiver entièrement l’enregistreur.
• Lors des arrêts fatals du Gateway, des délais d’arrêt 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 les diagnostics 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 pour la première fois : elles réutilisent un jeton d’appareil en cache existant 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 uniquement pour vérifier le statut.
• 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ésolus 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 vous devez aussi vérifier le bon état des appels RPC avec portée de lecture.
• --deep ajoute une recherche au mieux des installations launchd/systemd/schtasks supplémentaires. Lorsque plusieurs services de type Gateway sont détectés, la sortie lisible 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 Gateway lorsque le processus du service s’est terminé proprement pour un redémarrage par superviseur externe.
• La sortie lisible inclut le chemin résolu du fichier journal ainsi que l’instantané des chemins/validités de configuration CLI-versus-service pour aider à diagnostiquer les dérives de profil ou de répertoire d’état.

• Sur les installations systemd Linux, les vérifications de dérive d’authentification du service lisent à la fois les valeurs Environment= et EnvironmentFile= de l’unité (y compris %h, les chemins entre guillemets, les fichiers multiples et les fichiers optionnels -).
• Les vérifications de dérive résolvent les SecretRefs gateway.auth.token à l’aide de l’environnement d’exécution fusionné (environnement de commande du service d’abord, puis 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 où le mot de passe peut l’emporter et aucun candidat 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 concernant l’authentification. C’est distinct de la joignabilité.
• Read probe: ok signifie que les appels RPC de détail avec portée de lecture (health/status/system-presence/config.get) ont aussi réussi.
• Read probe: limited - missing scope: operator.read signifie que la connexion a réussi mais que le RPC avec portée de lecture est limité. Cela est signalé comme une joignabilité dégradée, pas 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, pas un Gateway injoignable.
• Comme gateway status, la sonde réutilise l’authentification d’appareil en cache existante mais ne crée pas d’identité d’appareil ni d’état d’appairage pour une première utilisation.
• Le code de sortie est non nul uniquement 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é l’ensemble des diagnostics RPC détaillés.
• 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 à considérer comme le gagnant actif dans cet ordre : URL explicite, tunnel SSH, distant configuré, puis loopback local.
• warnings[] : enregistrements d’avertissement au mieux avec code, message et targetIds optionnels.
• network : indications d’URL de loopback local/tailnet dérivées de la configuration actuelle et du réseau de l’hôte.
• discovery.timeoutMs et discovery.count : budget de découverte et nombre de résultats réels utilisés pour cette passe de sonde.

Par cible (targets[].connect) :

• ok : joignabilité après connexion + classification dégradée.
• rpcOk : réussite complète du RPC de détail.
• scopeLimited : échec du RPC de détail dû à une portée d’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 mise en place 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 volontairement 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 était 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, --force, --wait <duration>, --json
• gateway uninstall|start|stop : --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 désactive volontairement le LaunchAgent avant de l’arrêter.
• gateway restart --safe demande au Gateway en cours d’exécution de prévalider le travail OpenClaw actif et de différer le redémarrage jusqu’à ce que la livraison des réponses, les exécutions intégré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 de drainage de redémarrage configuré pour ce redémarrage. Les nombres seuls sont des millisecondes ; les unités comme s, m et h sont acceptées. --wait 0 attend indéfiniment.
• gateway restart --force ignore le drainage du travail actif et redémarre immédiatement. Utilisez-le lorsqu’un opérateur a déjà inspecté les bloqueurs 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 nécessite 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 conserve pas le jeton résolu dans les métadonnées d’environnement du service.
• Si l’authentification par jeton nécessite un jeton et que la SecretRef de jeton configurée n’est pas résolue, l’installation échoue de manière fermée au lieu de conserver du 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 déduit, OPENCLAW_GATEWAY_PASSWORD défini uniquement dans le shell n’assouplit pas les exigences de jeton à l’installation ; utilisez une configuration durable (gateway.auth.password ou env dans la 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.