Protocole Gateway

Le protocole WS du Gateway est le plan de contrôle unique + transport de nœud pour OpenClaw. Tous les clients (CLI, interface web, application macOS, nœuds iOS/Android, nœuds sans interface) se connectent via WebSocket et déclarent leur rôle + portée au moment de l’établissement de la connexion.

# Transport

• WebSocket, trames texte avec charges utiles JSON.
• La première trame doit être une requête connect.
• Les trames avant connexion sont limitées à 64 Kio. Après un établissement de connexion réussi, les clients doivent respecter les limites hello-ok.policy.maxPayload et hello-ok.policy.maxBufferedBytes. Lorsque les diagnostics sont activés, les trames entrantes surdimensionnées et les tampons sortants lents émettent des événements payload.large avant que le gateway ne ferme ou n’abandonne la trame concernée. Ces événements conservent les tailles, limites, surfaces et codes de raison sûrs. Ils ne conservent pas le corps du message, le contenu des pièces jointes, le corps brut de la trame, les jetons, les cookies ni les valeurs secrètes.

# Établissement de connexion (connect)

Gateway → Client (défi avant connexion) :

{
  "type": "event",
  "event": "connect.challenge",
  "payload": { "nonce": "…", "ts": 1737264000000 }
}

Client → Gateway :

{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 4,
    "maxProtocol": 4,
    "client": {
      "id": "cli",
      "version": "1.2.3",
      "platform": "macos",
      "mode": "operator"
    },
    "role": "operator",
    "scopes": ["operator.read", "operator.write"],
    "caps": [],
    "commands": [],
    "permissions": {},
    "auth": { "token": "…" },
    "locale": "en-US",
    "userAgent": "openclaw-cli/1.2.3",
    "device": {
      "id": "device_fingerprint",
      "publicKey": "…",
      "signature": "…",
      "signedAt": 1737264000000,
      "nonce": "…"
    }
  }
}

Gateway → Client :

{
  "type": "res",
  "id": "…",
  "ok": true,
  "payload": {
    "type": "hello-ok",
    "protocol": 4,
    "server": { "version": "…", "connId": "…" },
    "features": { "methods": ["…"], "events": ["…"] },
    "snapshot": { "…": "…" },
    "auth": {
      "role": "operator",
      "scopes": ["operator.read", "operator.write"]
    },
    "policy": {
      "maxPayload": 26214400,
      "maxBufferedBytes": 52428800,
      "tickIntervalMs": 15000
    }
  }
}

Pendant que le Gateway termine encore le démarrage des sidecars, la requête connect peut renvoyer une erreur UNAVAILABLE réessayable avec details.reason défini sur "startup-sidecars" et retryAfterMs. Les clients doivent réessayer cette réponse dans leur budget global de connexion au lieu de l’afficher comme un échec terminal d’établissement de connexion.

server, features, snapshot et policy sont tous requis par le schéma (src/gateway/protocol/schema/frames.ts). auth est également requis et indique le rôle/les portées négociés. pluginSurfaceUrls est facultatif et associe les noms de surfaces de plugin, comme canvas, à des URL hébergées à portée limitée.

Les URL de surfaces de plugin à portée limitée peuvent expirer. Les nœuds peuvent appeler node.pluginSurface.refresh avec { "surface": "canvas" } pour recevoir une nouvelle entrée dans pluginSurfaceUrls. La refonte expérimentale du plugin Canvas ne prend pas en charge l’ancien chemin de compatibilité canvasHostUrl, canvasCapability ou node.canvas.capability.refresh ; les clients natifs et gateways actuels doivent utiliser les surfaces de plugin.

Lorsqu’aucun jeton d’appareil n’est émis, hello-ok.auth indique les autorisations négociées sans champs de jeton :

{
  "auth": {
    "role": "operator",
    "scopes": ["operator.read", "operator.write"]
  }
}

Les clients backend de même processus de confiance (client.id: "gateway-client", client.mode: "backend") peuvent omettre device sur les connexions local loopback directes lorsqu’ils s’authentifient avec le jeton/mot de passe de gateway partagé. Ce chemin est réservé aux RPC internes du plan de contrôle et empêche les anciens référentiels CLI/appareil d’association de bloquer le travail backend local, comme les mises à jour de sessions de sous-agents. Les clients distants, les clients d’origine navigateur, les clients nœuds et les clients explicites avec jeton d’appareil/identité d’appareil utilisent toujours les vérifications normales d’association et de montée de portée.

Lorsqu’un jeton d’appareil est émis, hello-ok inclut également :

{
  "auth": {
    "deviceToken": "…",
    "role": "operator",
    "scopes": ["operator.read", "operator.write"]
  }
}

Lors du transfert de bootstrap de confiance, hello-ok.auth peut aussi inclure des entrées de rôle bornées supplémentaires dans deviceTokens :

{
  "auth": {
    "deviceToken": "…",
    "role": "node",
    "scopes": [],
    "deviceTokens": [
      {
        "deviceToken": "…",
        "role": "operator",
        "scopes": ["operator.approvals", "operator.read", "operator.talk.secrets", "operator.write"]
      }
    ]
  }
}

Pour le flux de bootstrap nœud/opérateur intégré, le jeton de nœud principal reste scopes: [] et tout jeton d’opérateur transféré reste limité à la liste d’autorisation de l’opérateur de bootstrap (operator.approvals, operator.read, operator.talk.secrets, operator.write). Les vérifications de portée de bootstrap restent préfixées par rôle : les entrées d’opérateur satisfont uniquement les requêtes d’opérateur, et les rôles non opérateurs ont toujours besoin de portées sous leur propre préfixe de rôle.

# Exemple de nœud

{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 4,
    "maxProtocol": 4,
    "client": {
      "id": "ios-node",
      "version": "1.2.3",
      "platform": "ios",
      "mode": "node"
    },
    "role": "node",
    "scopes": [],
    "caps": ["camera", "canvas", "screen", "location", "voice"],
    "commands": ["camera.snap", "canvas.navigate", "screen.record", "location.get"],
    "permissions": { "camera.capture": true, "screen.record": false },
    "auth": { "token": "…" },
    "locale": "en-US",
    "userAgent": "openclaw-ios/1.2.3",
    "device": {
      "id": "device_fingerprint",
      "publicKey": "…",
      "signature": "…",
      "signedAt": 1737264000000,
      "nonce": "…"
    }
  }
}

# Encadrement

• Requête : {type:"req", id, method, params}
• Réponse : {type:"res", id, ok, payload|error}
• Événement : {type:"event", event, payload, seq?, stateVersion?}

Les méthodes ayant des effets de bord requièrent des clés d’idempotence (voir le schéma).

# Rôles + portées

Pour le modèle complet des portées d’opérateur, les vérifications au moment de l’approbation et la sémantique des secrets partagés, consultez Portées d’opérateur.

# Rôles

• operator = client du plan de contrôle (CLI/interface utilisateur/automatisation).
• node = hôte de capacité (camera/screen/canvas/system.run).

# Portées (opérateur)

Portées courantes :

• operator.read
• operator.write
• operator.admin
• operator.approvals
• operator.pairing
• operator.talk.secrets

talk.config avec includeSecrets: true requiert operator.talk.secrets (ou operator.admin).

Les méthodes RPC du Gateway enregistrées par des plugins peuvent demander leur propre portée d’opérateur, mais les préfixes d’administration du cœur réservés (config.*, exec.approvals.*, wizard.*, update.*) se résolvent toujours en operator.admin.

La portée de méthode n’est que la première barrière. Certaines commandes slash atteintes via chat.send appliquent par-dessus des vérifications plus strictes au niveau de la commande. Par exemple, les écritures persistantes /config set et /config unset requièrent operator.admin.

node.pair.approve possède aussi une vérification de portée supplémentaire au moment de l’approbation, en plus de la portée de méthode de base :

• requêtes sans commande : operator.pairing
• requêtes avec des commandes de nœud non exec : operator.pairing + operator.write
• requêtes incluant system.run, system.run.prepare ou system.which : operator.pairing + operator.admin

# Capacités/commandes/autorisations (nœud)

Les nœuds déclarent des revendications de capacité au moment de la connexion :

• caps : catégories de capacités de haut niveau comme camera, canvas, screen, location, voice et talk.
• commands : liste d’autorisation de commandes pour l’invocation.
• permissions : bascules granulaires (par exemple screen.record, camera.capture).

Le Gateway traite celles-ci comme des revendications et applique des listes d’autorisation côté serveur.

# Présence

• system-presence renvoie des entrées indexées par identité d’appareil.
• Les entrées de présence incluent deviceId, roles et scopes afin que les interfaces utilisateur puissent afficher une seule ligne par appareil même lorsqu’il se connecte à la fois comme opérateur et comme nœud.
• node.list inclut les champs facultatifs lastSeenAtMs et lastSeenReason. Les nœuds connectés indiquent leur heure de connexion actuelle comme lastSeenAtMs avec la raison connect ; les nœuds associés peuvent aussi indiquer une présence durable en arrière-plan lorsqu’un événement de nœud de confiance met à jour leurs métadonnées d’association.

# Événement d’activité en arrière-plan du nœud

Les nœuds peuvent appeler node.event avec event: "node.presence.alive" pour enregistrer qu’un nœud associé était actif pendant un réveil en arrière-plan sans le marquer comme connecté.

{
  "event": "node.presence.alive",
  "payloadJSON": "{\"trigger\":\"silent_push\",\"sentAtMs\":1737264000000,\"displayName\":\"Peter's iPhone\",\"version\":\"2026.4.28\",\"platform\":\"iOS 18.4.0\",\"deviceFamily\":\"iPhone\",\"modelIdentifier\":\"iPhone17,1\",\"pushTransport\":\"relay\"}"
}

trigger est une énumération fermée : background, silent_push, bg_app_refresh, significant_location, manual ou connect. Les chaînes de déclencheur inconnues sont normalisées en background par le gateway avant la persistance. L’événement n’est durable que pour les sessions d’appareil nœud authentifiées ; les sessions sans appareil ou non associées renvoient handled: false.

Les gateways ayant réussi renvoient un résultat structuré :

{
  "ok": true,
  "event": "node.presence.alive",
  "handled": true,
  "reason": "persisted"
}

Les gateways plus anciens peuvent encore renvoyer { "ok": true } pour node.event ; les clients doivent traiter cela comme une RPC accusée réception, et non comme une persistance durable de présence.

# Portée des événements de diffusion

Les événements de diffusion WebSocket poussés par le serveur sont filtrés par portée afin que les sessions limitées à l’association ou propres aux nœuds ne reçoivent pas passivement le contenu des sessions.

• Les trames de chat, d’agent et de résultats d’outils (y compris les événements agent diffusés en flux et les résultats d’appels d’outils) requièrent au moins operator.read. Les sessions sans operator.read ignorent entièrement ces trames.
• Les diffusions plugin.* définies par les plugins sont limitées à operator.write ou operator.admin, selon la façon dont le plugin les a enregistrées.
• Les événements de statut et de transport (heartbeat, presence, tick, cycle de vie connexion/déconnexion, etc.) restent non restreints afin que la santé du transport reste observable pour chaque session authentifiée.
• Les familles d’événements de diffusion inconnues sont filtrées par portée par défaut (échec fermé), sauf si un gestionnaire enregistré les assouplit explicitement.

Chaque connexion client conserve son propre numéro de séquence par client afin que les diffusions préservent un ordre monotone sur ce socket, même lorsque différents clients voient différents sous-ensembles filtrés par portée du flux d’événements.

# Familles courantes de méthodes RPC

La surface WS publique est plus large que les exemples d’établissement de connexion/authentification ci-dessus. Ceci n’est pas un vidage généré : hello-ok.features.methods est une liste de découverte conservatrice construite à partir de src/gateway/server-methods-list.ts, plus les exports de méthodes de plugins/canaux chargés. Traitez-la comme une découverte de fonctionnalités, et non comme une énumération complète de src/gateway/server-methods/*.ts.

# Familles d’événements courantes

• chat : mises à jour du chat de l’interface utilisateur, comme chat.inject, et autres événements de chat limités au transcript.
• session.message et session.tool : mises à jour du transcript/flux d’événements pour une session abonnée.
• sessions.changed : l’index ou les métadonnées des sessions ont changé.
• presence : mises à jour des instantanés de présence système.
• tick : événement périodique de maintien de connexion / vivacité.
• health : mise à jour de l’instantané d’état du Gateway.
• heartbeat : mise à jour du flux d’événements Heartbeat.
• cron : événement de changement de tâche/exécution Cron.
• shutdown : notification d’arrêt du Gateway.
• node.pair.requested / node.pair.resolved : cycle de vie de l’appairage du Node.
• node.invoke.request : diffusion d’une demande d’invocation du Node.
• device.pair.requested / device.pair.resolved : cycle de vie d’un appareil appairé.
• voicewake.changed : la configuration du déclencheur par mot de réveil a changé.
• exec.approval.requested / exec.approval.resolved : cycle de vie de l’approbation exec.
• plugin.approval.requested / plugin.approval.resolved : cycle de vie de l’approbation de Plugin.

# Méthodes d’assistance du Node

• Les Nodes peuvent appeler skills.bins pour récupérer la liste actuelle des exécutables de Skills pour les contrôles d’autorisation automatique.

# Méthodes d’assistance opérateur

• Les opérateurs peuvent appeler commands.list (operator.read) pour récupérer l’inventaire des commandes d’exécution d’un agent.
  • agentId est facultatif ; omettez-le pour lire l’espace de travail de l’agent par défaut.
  • scope contrôle la surface ciblée par le name principal :
    • text renvoie le jeton de commande texte principal sans le / initial
    • native et le chemin par défaut both renvoient les noms natifs tenant compte du fournisseur lorsqu’ils sont disponibles
  • textAliases contient les alias slash exacts, comme /model et /m.
  • nativeName contient le nom de commande natif tenant compte du fournisseur lorsqu’il existe.
  • provider est facultatif et n’affecte que le nommage natif ainsi que la disponibilité des commandes de Plugin natives.
  • includeArgs=false omet les métadonnées d’arguments sérialisées dans la réponse.
• Les opérateurs peuvent appeler tools.catalog (operator.read) pour récupérer le catalogue d’outils d’exécution d’un agent. La réponse inclut les outils groupés et les métadonnées de provenance :
  • source : core ou plugin
  • pluginId : Plugin propriétaire lorsque source="plugin"
  • optional : indique si un outil de Plugin est facultatif
• Les opérateurs peuvent appeler tools.effective (operator.read) pour récupérer l’inventaire des outils effectifs à l’exécution pour une session.
  • sessionKey est obligatoire.
  • Le Gateway déduit le contexte d’exécution fiable côté serveur à partir de la session, au lieu d’accepter un contexte d’authentification ou de livraison fourni par l’appelant.
  • La réponse est limitée à la session et reflète ce que la conversation active peut utiliser maintenant, y compris les outils de core, de Plugin et de canal.
• Les opérateurs peuvent appeler tools.invoke (operator.write) pour invoquer un outil disponible via le même chemin de stratégie du Gateway que /tools/invoke.
  • name est obligatoire. args, sessionKey, agentId, confirm et idempotencyKey sont facultatifs.
  • Si sessionKey et agentId sont tous deux présents, l’agent de session résolu doit correspondre à agentId.
  • La réponse est une enveloppe destinée au SDK avec les champs ok, toolName, output facultatif et error typé. Les refus d’approbation ou de stratégie renvoient ok:false dans la charge utile au lieu de contourner le pipeline de stratégie d’outils du Gateway.
• Les opérateurs peuvent appeler skills.status (operator.read) pour récupérer l’inventaire visible des Skills d’un agent.
  • agentId est facultatif ; omettez-le pour lire l’espace de travail de l’agent par défaut.
  • La réponse inclut l’éligibilité, les exigences manquantes, les contrôles de configuration et les options d’installation assainies, sans exposer de valeurs secrètes brutes.
• Les opérateurs peuvent appeler skills.search et skills.detail (operator.read) pour les métadonnées de découverte ClawHub.
• Les opérateurs peuvent appeler skills.install (operator.admin) dans deux modes :
  • Mode ClawHub : { source: "clawhub", slug, version?, force? } installe un dossier de skill dans le répertoire skills/ de l’espace de travail de l’agent par défaut.
  • Mode installateur Gateway : { name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? } exécute une action metadata.openclaw.install déclarée sur l’hôte du Gateway.
• Les opérateurs peuvent appeler skills.update (operator.admin) dans deux modes :
  • Le mode ClawHub met à jour un slug suivi ou toutes les installations ClawHub suivies dans l’espace de travail de l’agent par défaut.
  • Le mode configuration corrige les valeurs skills.entries.<skillKey>, comme enabled, apiKey et env.

# Vues de models.list

models.list accepte un paramètre view facultatif :

• Omis ou "default" : comportement d’exécution actuel. Si agents.defaults.models est configuré, la réponse correspond au catalogue autorisé ; sinon, la réponse correspond au catalogue Gateway complet.
• "configured" : comportement dimensionné pour un sélecteur. Si agents.defaults.models est configuré, il reste prioritaire. Sinon, la réponse utilise les entrées explicites models.providers.*.models, avec repli vers le catalogue complet uniquement lorsqu’aucune ligne de modèle configurée n’existe.
• "all" : catalogue Gateway complet, en contournant agents.defaults.models. Utilisez ceci pour les diagnostics et les interfaces utilisateur de découverte, pas pour les sélecteurs de modèles normaux.

# Approbations exec

• Lorsqu’une demande exec nécessite une approbation, le Gateway diffuse exec.approval.requested.
• Les clients opérateurs résolvent la demande en appelant exec.approval.resolve (nécessite la portée operator.approvals).
• Pour host=node, exec.approval.request doit inclure systemRunPlan (argv/cwd/rawCommand/métadonnées de session canoniques). Les demandes sans systemRunPlan sont rejetées.
• Après approbation, les appels node.invoke system.run transférés réutilisent ce systemRunPlan canonique comme contexte de commande/cwd/session faisant autorité.
• Si un appelant modifie command, rawCommand, cwd, agentId ou sessionKey entre la préparation et le transfert final approuvé de system.run, le Gateway rejette l’exécution au lieu de faire confiance à la charge utile modifiée.

# Repli de livraison de l’agent

• Les demandes agent peuvent inclure deliver=true pour demander une livraison sortante.
• bestEffortDeliver=false conserve un comportement strict : les cibles de livraison non résolues ou uniquement internes renvoient INVALID_REQUEST.
• bestEffortDeliver=true autorise un repli vers une exécution limitée à la session lorsqu’aucune route livrable externe ne peut être résolue (par exemple des sessions internes/webchat ou des configurations multicanaux ambiguës).

# Versioning

• PROTOCOL_VERSION se trouve dans src/gateway/protocol/version.ts.
• Les clients envoient minProtocol + maxProtocol ; le serveur rejette les incompatibilités.
• Les schémas et modèles sont générés à partir des définitions TypeBox :
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

# Constantes client

Le client de référence dans src/gateway/client.ts utilise ces valeurs par défaut. Les valeurs sont stables dans le protocole v4 et constituent la base attendue pour les clients tiers.

Constante	Valeur par défaut	Source
PROTOCOL_VERSION	4	src/gateway/protocol/version.ts
Délai d’expiration des requêtes (par RPC)	30_000 ms	src/gateway/client.ts (requestTimeoutMs)
Délai preauth / connect-challenge	15_000 ms	src/gateway/handshake-timeouts.ts (config/env peut augmenter le budget serveur/client appairé)
Backoff de reconnexion initial	1_000 ms	src/gateway/client.ts (backoffMs)
Backoff de reconnexion maximal	30_000 ms	src/gateway/client.ts (scheduleReconnect)
Plafond de retry rapide après fermeture par jeton d’appareil	250 ms	src/gateway/client.ts
Délai de grâce force-stop avant terminate()	250 ms	FORCE_STOP_TERMINATE_GRACE_MS
Délai d’expiration par défaut de stopAndWait()	1_000 ms	STOP_AND_WAIT_TIMEOUT_MS
Intervalle de tick par défaut (avant hello-ok)	30_000 ms	src/gateway/client.ts
Fermeture sur délai d’expiration de tick	code 4000 lorsque le silence dépasse tickIntervalMs * 2	src/gateway/client.ts
MAX_PAYLOAD_BYTES	25 * 1024 * 1024 (25 MB)	src/gateway/server-constants.ts

Le serveur annonce les valeurs effectives policy.tickIntervalMs, policy.maxPayload et policy.maxBufferedBytes dans hello-ok ; les clients doivent respecter ces valeurs plutôt que les valeurs par défaut d’avant la poignée de main.

# Auth

• L’authentification du Gateway par secret partagé utilise connect.params.auth.token ou connect.params.auth.password, selon le mode d’authentification configuré.
• Les modes portant une identité, comme Tailscale Serve (gateway.auth.allowTailscale: true) ou gateway.auth.mode: "trusted-proxy" hors boucle locale, satisfont la vérification d’authentification de connexion à partir des en-têtes de requête plutôt que de connect.params.auth.*.
• L’entrée privée gateway.auth.mode: "none" ignore entièrement l’authentification de connexion par secret partagé ; n’exposez pas ce mode sur une entrée publique/non fiable.
• Après l’appairage, le Gateway émet un jeton d’appareil limité au rôle de connexion
  • aux scopes. Il est renvoyé dans hello-ok.auth.deviceToken et doit être conservé par le client pour les connexions futures.
• Les clients doivent conserver le hello-ok.auth.deviceToken principal après toute connexion réussie.
• La reconnexion avec ce jeton d’appareil stocké doit aussi réutiliser l’ensemble de scopes approuvé et stocké pour ce jeton. Cela préserve l’accès en lecture/sonde/état déjà accordé et évite de réduire silencieusement les reconnexions à un scope implicite plus étroit limité à l’administration.
• Assemblage de l’authentification de connexion côté client (selectConnectAuth dans src/gateway/client.ts) :
  • auth.password est orthogonal et est toujours transmis lorsqu’il est défini.
  • auth.token est renseigné par ordre de priorité : jeton partagé explicite d’abord, puis un deviceToken explicite, puis un jeton stocké par appareil (indexé par deviceId + role).
  • auth.bootstrapToken est envoyé uniquement lorsqu’aucun des éléments ci-dessus n’a résolu un auth.token. Un jeton partagé ou tout jeton d’appareil résolu le supprime.
  • La promotion automatique d’un jeton d’appareil stocké lors de la nouvelle tentative unique AUTH_TOKEN_MISMATCH est limitée aux points de terminaison fiables uniquement — boucle locale, ou wss:// avec un tlsFingerprint épinglé. Un wss:// public sans épinglage n’est pas admissible.
• Les entrées hello-ok.auth.deviceTokens supplémentaires sont des jetons de transfert d’amorçage. Conservez-les uniquement lorsque la connexion a utilisé l’authentification d’amorçage sur un transport fiable comme wss:// ou un appairage local/boucle locale.
• Si un client fournit un deviceToken explicite ou des scopes explicites, cet ensemble de scopes demandé par l’appelant reste l’autorité ; les scopes mis en cache ne sont réutilisés que lorsque le client réutilise le jeton stocké par appareil.
• Les jetons d’appareil peuvent être tournés/révoqués via device.token.rotate et device.token.revoke (requiert le scope operator.pairing).
• device.token.rotate renvoie des métadonnées de rotation. Il renvoie en miroir le jeton porteur de remplacement uniquement pour les appels du même appareil déjà authentifiés avec ce jeton d’appareil, afin que les clients utilisant seulement un jeton puissent conserver leur remplacement avant de se reconnecter. Les rotations partagées/admin ne renvoient pas le jeton porteur.
• L’émission, la rotation et la révocation des jetons restent limitées à l’ensemble de rôles approuvé enregistré dans l’entrée d’appairage de cet appareil ; la mutation de jeton ne peut pas étendre ni cibler un rôle d’appareil que l’approbation d’appairage n’a jamais accordé.
• Pour les sessions par jeton d’appareil appairé, la gestion des appareils est limitée à soi-même sauf si l’appelant dispose aussi de operator.admin : les appelants non administrateurs peuvent supprimer/révoquer/tourner uniquement l’entrée de leur propre appareil.
• device.token.rotate et device.token.revoke vérifient aussi l’ensemble de scopes du jeton opérateur cible par rapport aux scopes de session actuels de l’appelant. Les appelants non administrateurs ne peuvent pas tourner ni révoquer un jeton opérateur plus large que celui qu’ils détiennent déjà.
• Les échecs d’authentification incluent error.details.code ainsi que des indications de récupération :
  • error.details.canRetryWithDeviceToken (booléen)
  • error.details.recommendedNextStep (retry_with_device_token, update_auth_configuration, update_auth_credentials, wait_then_retry, review_auth_configuration)
• Comportement client pour AUTH_TOKEN_MISMATCH :
  • Les clients fiables peuvent tenter une seule nouvelle tentative bornée avec un jeton par appareil mis en cache.
  • Si cette nouvelle tentative échoue, les clients doivent arrêter les boucles de reconnexion automatiques et afficher des recommandations d’action opérateur.

# Identité d’appareil + appairage

• Les Nodes doivent inclure une identité d’appareil stable (device.id) dérivée d’une empreinte de paire de clés.
• Les Gateways émettent des jetons par appareil + rôle.
• Les approbations d’appairage sont requises pour les nouveaux ID d’appareil sauf si l’approbation automatique locale est activée.
• L’approbation automatique d’appairage est centrée sur les connexions directes via local loopback.
• OpenClaw dispose aussi d’un chemin étroit d’auto-connexion local au backend/conteneur pour les flux d’assistance fiables à secret partagé.
• Les connexions tailnet ou LAN du même hôte sont toujours traitées comme distantes pour l’appairage et requièrent une approbation.
• Les clients WS incluent normalement l’identité device pendant connect (opérateur + node). Les seules exceptions opérateur sans appareil sont des chemins de confiance explicites :
  • gateway.controlUi.allowInsecureAuth=true pour la compatibilité HTTP non sécurisée limitée à localhost.
  • authentification réussie de l’interface Control UI opérateur en gateway.auth.mode: "trusted-proxy".
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (mesure de dernier recours, forte dégradation de sécurité).
  • RPC backend gateway-client en boucle locale directe authentifiés avec le jeton/mot de passe Gateway partagé.
• Toutes les connexions doivent signer le nonce connect.challenge fourni par le serveur.

# Diagnostics de migration de l’authentification d’appareil

Pour les clients hérités qui utilisent encore le comportement de signature antérieur au challenge, connect renvoie maintenant des codes de détail DEVICE_AUTH_* sous error.details.code avec un error.details.reason stable.

Échecs de migration courants :

Message	details.code	details.reason	Signification
device nonce required	DEVICE_AUTH_NONCE_REQUIRED	device-nonce-missing	Le client a omis device.nonce (ou l’a envoyé vide).
device nonce mismatch	DEVICE_AUTH_NONCE_MISMATCH	device-nonce-mismatch	Le client a signé avec un nonce obsolète/incorrect.
device signature invalid	DEVICE_AUTH_SIGNATURE_INVALID	device-signature	La charge utile de signature ne correspond pas à la charge utile v2.
device signature expired	DEVICE_AUTH_SIGNATURE_EXPIRED	device-signature-stale	L’horodatage signé est hors de la dérive autorisée.
device identity mismatch	DEVICE_AUTH_DEVICE_ID_MISMATCH	device-id-mismatch	device.id ne correspond pas à l’empreinte de clé publique.
device public key invalid	DEVICE_AUTH_PUBLIC_KEY_INVALID	device-public-key	Le format/la canonisation de la clé publique a échoué.

Cible de migration :

• Attendez toujours connect.challenge.
• Signez la charge utile v2 qui inclut le nonce du serveur.
• Envoyez le même nonce dans connect.params.device.nonce.
• La charge utile de signature préférée est v3, qui lie platform et deviceFamily en plus des champs appareil/client/rôle/scopes/jeton/nonce.
• Les signatures héritées v2 restent acceptées pour compatibilité, mais l’épinglage des métadonnées d’appareil appairé contrôle toujours la politique de commande à la reconnexion.

# TLS + épinglage

• TLS est pris en charge pour les connexions WS.
• Les clients peuvent, en option, épingler l’empreinte du certificat du gateway (voir la configuration gateway.tls ainsi que gateway.remote.tlsFingerprint ou la CLI --tls-fingerprint).

# Portée

Ce protocole expose l’API complète du gateway (état, canaux, modèles, chat, agent, sessions, nodes, approbations, etc.). La surface exacte est définie par les schémas TypeBox dans src/gateway/protocol/schema.ts.

# Liens associés

• Protocole de pont
• Runbook Gateway