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 manquant, 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 manquant, le Gateway considère cela comme une détérioration suspecte de la configuration et refuse de « deviner local » pour vous.
• La liaison au-delà de loopback sans authentification est bloquée (garde-fou de sécurité).
• lan, tailnet et custom se résolvent actuellement via des chemins BYOH IPv4 uniquement.
• Le BYOH IPv6 uniquement n’est pas pris en charge nativement sur ce chemin aujourd’hui. Utilisez un sidecar ou un proxy IPv4 si l’hôte lui-même est IPv6 uniquement.
• 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 des outils/configurations 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 enveloppez la CLI avec une TUI ou une saisie 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, identifiants d’approbation, noms de canaux/plugins et résumés de session 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, cookies, valeurs secrètes, noms d’hôte ni identifiants bruts de session. Définissez diagnostics.enabled: false pour désactiver entièrement l’enregistreur.
• Lors des sorties fatales du Gateway, des expirations de délai 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 prouve l’état du service, la connexion WebSocket et la capacité d’authentification visible au moment du handshake. Il ne prouve pas les opérations de lecture/écriture/administration.
• Les sondes de diagnostic ne modifient pas l’état pour l’authentification initiale d’un appareil : 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 juste 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.
• Lorsque le sondage est activé, la sortie JSON inclut gateway.version lorsque le Gateway en cours d’exécution la signale ; --require-rpc peut se rabattre sur la charge utile RPC status.runtimeVersion si la sonde de handshake de suivi ne peut pas fournir les métadonnées de version.
• Utilisez --require-rpc dans les scripts et automatisations lorsqu’un service à l’écoute ne suffit pas et que vous avez aussi besoin que les appels RPC de portée lecture soient 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 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 de service s’est terminé proprement pour un redémarrage par superviseur externe.
• --deep exécute la validation de configuration en mode compatible Plugin (pluginValidation: "full") et expose les avertissements de manifeste Plugin configurés (par exemple des métadonnées de configuration de canal manquantes) afin que les vérifications smoke 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 Plugin.
• La sortie lisible inclut le chemin de journal de fichier résolu ainsi que l’instantané des chemins/validité de configuration CLI-vs-service pour aider à diagnostiquer une dérive de profil ou de répertoire d’état.

• Sur les installations Linux systemd, les contrôles de dérive d’authentification de service lisent les valeurs Environment= et EnvironmentFile= depuis l’unité (y compris %h, les chemins entre guillemets, les fichiers multiples et les fichiers facultatifs -).
• Les contrôles 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 repli).
• Si l’authentification par jeton n’est pas effectivement active (gateway.auth.mode explicite défini sur password/none/trusted-proxy, ou mode non défini lorsque le mot de passe peut l’emporter et qu’aucun candidat jeton ne peut l’emporter), les contrôles 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 prouver concernant l’authentification. C’est distinct de la joignabilité.
• Read probe: ok signifie que les appels RPC de détail de portée 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 de portée lecture est limité. C’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 de suivi ont expiré ou échoué. C’est aussi une joignabilité dégradée, et non 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 initiale ni d’état d’appairage.
• 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é les diagnostics RPC détaillés complets.
• capability : meilleure capacité observée sur 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 facultatifs.
• network : indications d’URL local loopback/tailnet dérivées de la configuration actuelle et du réseau de l’hôte.
• discovery.timeoutMs et discovery.count : le budget de découverte réel et le nombre de résultats utilisés pour ce passage de sonde.

Par cible (targets[].connect) :

• ok : joignabilité après connexion + classification dégradée.
• rpcOk : réussite RPC détaillée complète.
• scopeLimited : échec du RPC détaillé 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 s’est rabattue sur des sondes directes.
• multiple_gateways : des identités Gateway distinctes étaient joignables, ou OpenClaw n’a pas pu prouver que les cibles joignables sont le même Gateway. Un tunnel SSH, une URL proxy ou une URL distante configurée vers le même Gateway ne déclenche pas cet avertissement.
• 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, --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 à un 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 conserver de désactivation — la récupération automatique KeepAlive reste active pour les futurs plantages, et gateway start la réactive proprement sans launchctl enable manuel. Passez --disable pour supprimer durablement KeepAlive et RunAtLoad afin que le Gateway ne redémarre pas automatiquement avant le prochain gateway start explicite ; utilisez cette option lorsqu’un arrêt manuel doit survivre aux redémarrages ou aux redémarrages système.
• gateway restart --safe demande au Gateway en cours d’exécution de précontrôler le travail actif et de planifier un seul redémarrage regroupé une fois ce travail terminé. Le redémarrage sûr par défaut attend le travail actif jusqu’au gateway.reload.deferralTimeoutMs configuré (5 minutes par défaut) ; lorsque ce délai est dépassé, le redémarrage est forcé. Définissez gateway.reload.deferralTimeoutMs sur 0 pour une attente sûre indéfinie qui ne force jamais. --safe ne peut pas être combiné avec --force ni --wait.
• gateway restart --wait 30s remplace le budget configuré d’attente de vidage avant redémarrage pour ce redémarrage. Les nombres seuls 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 avec OpenClaw, mais contourne la barrière de report afin que le Gateway émette le redémarrage immédiatement, même lorsque des blocages sont signalés. C’est une échappatoire opérateur pour les reports 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-le lorsqu’un opérateur a déjà inspecté les blocages de tâches listés et veut rétablir le Gateway immédiatement.
• 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 le SecretRef peut être résolu, mais ne conserve pas le jeton résolu dans les métadonnées d’environnement du service.
• Si l’authentification par jeton exige un jeton et que le SecretRef de jeton configuré n’est pas résolu, l’installation échoue fermée au lieu de conserver un texte brut de repli.
• Pour l’authentification par mot de passe sur gateway run, préférez OPENCLAW_GATEWAY_PASSWORD, --password-file ou un gateway.auth.password adossé à SecretRef plutôt qu’un --password en ligne.
• En mode d’authentification inféré, 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 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.