Protocole Gateway

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

Transport

• WebSocket, trames texte avec charges utiles JSON.
• La première trame doit être une requête connect.
• Les trames avant connexion sont plafonnées à 64 KiB. Après un établissement de liaison réussi, les clients doivent respecter les limites hello-ok.policy.maxPayload et hello-ok.policy.maxBufferedBytes. Avec les diagnostics activés, les trames entrantes surdimensionnées et les tampons sortants lents émettent des événements payload.large avant que le gateway ferme ou 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 liaison (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": 3,    "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 de ses 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 la présenter comme un échec terminal d’établissement de liaison.

server, features, snapshot et policy sont tous requis par le schéma (packages/gateway-protocol/src/schema/frames.ts). auth est également requis et indique le rôle et 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 refactorisation expérimentale du plugin Canvas ne prend pas en charge le chemin de compatibilité obsolète 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 confiance dans le même processus (client.id: "gateway-client", client.mode: "backend") peuvent omettre device sur les connexions directes en local loopback lorsqu’ils s’authentifient avec le jeton/mot de passe partagé du gateway. Ce chemin est réservé aux RPC internes du plan de contrôle et empêche les bases de référence CLI/appareil obsolètes 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 en portée.

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

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

L’amorçage intégré par QR/code de configuration est un nouveau chemin de transfert mobile. Une connexion réussie avec code de configuration de base renvoie un jeton de nœud principal plus un jeton opérateur borné :

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

Le transfert opérateur est volontairement borné afin que l’intégration par QR puisse démarrer la boucle opérateur mobile et terminer la configuration native sans accorder de portées de mutation d’association ni operator.admin. Il inclut operator.talk.secrets afin que le client natif puisse lire la configuration Talk dont il a besoin après l’amorçage. L’accès plus large à l’association et à l’administration nécessite un flux séparé d’association opérateur approuvée ou de jeton. Les clients ne doivent persister hello-ok.auth.deviceTokens que lorsque la connexion a utilisé une authentification d’amorçage sur un transport de confiance, comme wss:// ou une association loopback/locale.

Exemple de nœud

{  "type": "req",  "id": "…",  "method": "connect",  "params": {    "minProtocol": 3,    "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": "…"    }  }}

Tramage

• 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 avec effets de bord nécessitent des clés d’idempotence (voir le schéma).

Rôles + portées

Pour le modèle complet des portées opérateur, les vérifications au moment de l’approbation et la sémantique des secrets partagés, consultez Portées 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 nécessite operator.talk.secrets (ou operator.admin). Lorsque les secrets sont inclus, les clients doivent lire l’identifiant actif du fournisseur Talk depuis talk.resolved.config.apiKey ; talk.providers.<id>.apiKey conserve la forme source et peut être un objet SecretRef ou une chaîne caviardée.

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

La portée de méthode n’est que le premier garde-fou. Certaines commandes slash atteintes via chat.send appliquent en plus des vérifications plus strictes au niveau de la commande. Par exemple, les écritures persistantes /config set et /config unset nécessitent 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 commandes de nœud non-exec : operator.pairing + operator.write
• requêtes qui incluent system.run, system.run.prepare ou system.which : operator.pairing + operator.admin

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

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

• caps : catégories de capacité 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 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 également signaler une présence d’arrière-plan durable lorsqu’un événement de nœud de confiance met à jour leurs métadonnées d’association.

Événement de nœud vivant en arrière-plan

Les nœuds peuvent appeler node.event avec event: "node.presence.alive" pour enregistrer qu’un nœud associé était vivant 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 de nœud authentifiées ; les sessions sans appareil ou non associées renvoient handled: false.

Les gateways qui réussissent 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 un RPC accusé de réception, et non comme une persistance durable de présence.

Délimitation de 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 réservées aux nœuds ne reçoivent pas passivement le contenu de session.

• Trames de chat, d’agent et de résultats d’outils (y compris les événements agent diffusés en continu et les résultats d’appels d’outils) nécessitent au moins operator.read. Les sessions sans operator.read ignorent entièrement ces trames.
• 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.
• Événements d’état et de transport (heartbeat, presence, tick, cycle de vie connexion/déconnexion, etc.) restent sans restriction afin que la santé du transport reste observable par chaque session authentifiée.
• 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 du flux d’événements filtrés par portée.

Familles courantes de méthodes RPC

La surface WS publique est plus large que les exemples d’établissement de liaison/authentification ci-dessus. Il ne s’agit pas d’un export généré — hello-ok.features.methods est une liste de découverte prudente construite à partir de src/gateway/server-methods-list.ts plus les exports de méthodes de plugins/canaux chargés. Traitez-la comme de la 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 de chat UI telles que chat.inject et autres événements de chat limités à la transcription. Dans la version 4 du protocole, les charges utiles delta portent deltaText ; message reste l’instantané cumulatif de l’assistant. Les remplacements qui ne sont pas des préfixes définissent replace=true et utilisent deltaText comme texte de remplacement.
• session.message, session.operation et session.tool : mises à jour de transcription, d’opération de session en cours et de flux d’événements pour une session abonnée.
• sessions.changed : l’index ou les métadonnées de session ont changé.
• presence : mises à jour d’instantané de présence système.
• tick : événement périodique de keepalive / vivacité.
• health : mise à jour d’instantané de santé du gateway.
• heartbeat : mise à jour du flux d’événements Heartbeat.
• cron : événement de changement de run/tâche Cron.
• shutdown : notification d’arrêt du gateway.
• node.pair.requested / node.pair.resolved : cycle de vie de l’appairage de nœuds.
• node.invoke.request : diffusion d’une requête d’invocation de nœud.
• device.pair.requested / device.pair.resolved : cycle de vie d’appareil appairé.
• voicewake.changed : la configuration du déclencheur par mot d’activation 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 des nœuds

• Les nœuds peuvent appeler skills.bins pour récupérer la liste actuelle des exécutables de Skills pour les vérifications d’autorisation automatique.

RPC du registre des tâches

Les clients opérateur peuvent inspecter et annuler les enregistrements de tâches en arrière-plan du Gateway via les RPC du registre des tâches. Ces méthodes renvoient des résumés de tâches assainis, pas l’état brut de l’exécution.

• tasks.list requiert operator.read.
  • Paramètres : status facultatif ("queued", "running", "completed", "failed", "cancelled" ou "timed_out") ou un tableau de ces statuts, agentId facultatif, sessionKey facultatif, limit facultatif de 1 à 500, et chaîne cursor facultative.
  • Résultat : { "tasks": TaskSummary[], "nextCursor"?: string }.
• tasks.get requiert operator.read.
  • Paramètres : { "taskId": string }.
  • Résultat : { "task": TaskSummary }.
  • Les identifiants de tâche manquants renvoient la forme d’erreur introuvable du Gateway.
• tasks.cancel requiert operator.write.
  • Paramètres : { "taskId": string, "reason"?: string }.
  • Résultat : { "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }.
  • found indique si le registre contenait une tâche correspondante. cancelled indique si l’exécution a accepté ou enregistré l’annulation.

TaskSummary inclut id, status et des métadonnées facultatives telles que kind, runtime, title, agentId, sessionKey, childSessionKey, ownerKey, runId, taskId, flowId, parentTaskId, sourceId, les horodatages, la progression, le résumé terminal et le texte d’erreur assaini. agentId identifie l’agent qui exécute la tâche ; sessionKey et ownerKey préservent le contexte du demandeur et du contrôle.

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 principal de commande texte 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 tels que /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 Plugin natives.
  • includeArgs=false omet les métadonnées d’arguments sérialisées de la réponse.
• Les opérateurs peuvent appeler tools.catalog (operator.read) pour récupérer le catalogue des 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 : propriétaire du Plugin lorsque source="plugin"
  • optional : indique si un outil 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 requis.
  • 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 une projection dérivée côté serveur et limitée à la session de l’inventaire actif, incluant les outils du cœur, des Plugins, des canaux et des serveurs MCP déjà découverts.
  • tools.effective est en lecture seule pour MCP : il peut projeter un catalogue MCP de session déjà chaud via la politique d’outils finale, mais il ne crée pas d’environnements d’exécution MCP, ne connecte pas de transports et n’émet pas tools/list. Si aucun catalogue chaud correspondant n’existe, la réponse peut inclure une notification telle que mcp-not-yet-connected, mcp-not-yet-listed ou mcp-stale-catalog.
  • Les entrées d’outils effectifs utilisent source="core", source="plugin", source="channel" ou source="mcp".
• Les opérateurs peuvent appeler tools.invoke (operator.write) pour invoquer un outil disponible via le même chemin de politique Gateway que /tools/invoke.
  • name est requis. 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.
  • Les wrappers cœur réservés au propriétaire, tels que cron, gateway et nodes, exigent une identité propriétaire/administrateur (operator.admin), même si la méthode tools.invoke elle-même est operator.write.
  • 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 politique renvoient ok:false dans la charge utile au lieu de contourner le pipeline de politique d’outils du Gateway.
• Les opérateurs peuvent appeler skills.status (operator.read) pour récupérer l’inventaire visible des Skills pour 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 vérifications 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.upload.begin, skills.upload.chunk et skills.upload.commit (operator.admin) pour préparer une archive de Skills privée avant de l’installer. Il s’agit d’un chemin d’envoi administrateur séparé pour les clients de confiance, et non du flux normal d’installation de Skills ClawHub ; il est désactivé par défaut sauf si skills.install.allowUploadedArchives est activé.
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) crée un envoi lié à ce slug et à cette valeur force.
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) ajoute des octets au décalage décodé exact.
  • skills.upload.commit({ uploadId, sha256? }) vérifie la taille finale et le SHA-256. Le commit ne fait que finaliser l’envoi ; il n’installe pas le Skill.
  • Les archives de Skills téléversées sont des archives zip contenant une racine SKILL.md. Le nom du répertoire interne de l’archive ne sélectionne jamais la cible d’installation.
• Les opérateurs peuvent appeler skills.install (operator.admin) selon trois modes :
  • Mode ClawHub : { source: "clawhub", slug, version?, force? } installe un dossier de Skills dans le répertoire skills/ de l’espace de travail de l’agent par défaut.
  • Mode envoi : { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } installe un envoi validé dans le répertoire skills/<slug> de l’espace de travail de l’agent par défaut. Le slug et la valeur force doivent correspondre à la requête skills.upload.begin d’origine. Ce mode est rejeté sauf si skills.install.allowUploadedArchives est activé. Le paramètre n’affecte pas les installations ClawHub.
  • Mode installateur Gateway : { name, installId, timeoutMs? } exécute une action metadata.openclaw.install déclarée sur l’hôte Gateway. Les anciens clients peuvent encore envoyer dangerouslyForceUnsafeInstall ; ce champ est obsolète, accepté uniquement pour la compatibilité du protocole et ignoré. Utilisez security.installPolicy pour les décisions d’installation appartenant à l’opérateur.
• Les opérateurs peuvent appeler skills.update (operator.admin) selon 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> telles que 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 est le catalogue autorisé, incluant les modèles découverts dynamiquement pour les entrées provider/*. Sinon, la réponse est le catalogue Gateway complet.
• "configured" : comportement dimensionné pour les sélecteurs. Si agents.defaults.models est configuré, il reste prioritaire, incluant la découverte limitée au fournisseur pour les entrées provider/*. Sans liste d’autorisation, 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 cette option pour les diagnostics et les interfaces de découverte, pas pour les sélecteurs de modèles normaux.

Approbations exec

• Lorsqu’une requête 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 requêtes sans systemRunPlan sont rejetées.
• Après approbation, les appels transférés node.invoke system.run 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 requêtes 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 le repli vers une exécution limitée à la session lorsqu’aucune route livrable externe ne peut être résolue (par exemple les sessions internes/webchat ou les configurations multicanales ambiguës).
• Les résultats finaux agent peuvent inclure result.deliveryStatus lorsqu’une livraison a été demandée, avec les mêmes statuts sent, suppressed, partial_failed et failed que ceux documentés pour openclaw agent --json --deliver.

Versionnement

• PROTOCOL_VERSION se trouve dans packages/gateway-protocol/src/version.ts.
• Les clients envoient minProtocol + maxProtocol ; le serveur rejette les plages qui n’incluent pas son protocole actuel. Les clients et serveurs actuels exigent le protocole v4.
• Les schémas + modèles sont générés à partir de 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 sur l’ensemble du protocole v4 et constituent la base attendue pour les clients tiers.

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 handshake.

Auth

• L’authentification 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 local loopback satisfont le contrôle d’authentification de connexion à partir des en-têtes de requête plutôt que de connect.params.auth.*.
• Le mode d’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 portées. Il est renvoyé dans hello-ok.auth.deviceToken et doit être conservé par le client pour les futures connexions.
• Les clients doivent conserver le hello-ok.auth.deviceToken principal après toute connexion réussie.
• Une reconnexion avec ce jeton d’appareil stocké doit aussi réutiliser l’ensemble de portées approuvé stocké pour ce jeton. Cela préserve l’accès lecture/sonde/statut déjà accordé et évite de réduire silencieusement les reconnexions à une portée implicite plus étroite réservée à 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 par appareil stocké (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 ponctuelle AUTH_TOKEN_MISMATCH est limitée aux points de terminaison fiables uniquement : loopback, ou wss:// avec un tlsFingerprint épinglé. Un wss:// public sans épinglage n’est pas admissible.
• L’amorçage intégré par code de configuration renvoie le hello-ok.auth.deviceToken du nœud principal ainsi qu’un jeton opérateur borné dans hello-ok.auth.deviceTokens pour un transfert mobile fiable. Le jeton opérateur inclut operator.talk.secrets pour les lectures de configuration Talk natives, mais exclut les portées de mutation d’appairage et operator.admin.
• Pendant qu’un amorçage par code de configuration hors référence attend une approbation, les détails PAIRING_REQUIRED incluent recommendedNextStep: "wait_then_retry", retryable: true et pauseReconnect: false. Les clients doivent continuer à se reconnecter avec le même jeton d’amorçage jusqu’à ce que la demande soit approuvée ou que le jeton devienne invalide.
• Conservez hello-ok.auth.deviceTokens uniquement lorsque la connexion a utilisé l’authentification d’amorçage sur un transport fiable comme wss:// ou un appairage loopback/local.
• Si un client fournit un deviceToken explicite ou des scopes explicites, l’ensemble de portées demandé par cet appelant reste l’autorité ; les portées mises en cache ne sont réutilisées que lorsque le client réutilise le jeton par appareil stocké.
• Les jetons d’appareil peuvent être alternés/révoqués via device.token.rotate et device.token.revoke (nécessite la portée operator.pairing). L’alternance ou la révocation d’un nœud ou d’un autre rôle non opérateur nécessite aussi operator.admin.
• device.token.rotate renvoie des métadonnées d’alternance. Il renvoie en écho 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 à jeton seul puissent conserver leur remplacement avant de se reconnecter. Les alternances partagées/admin ne renvoient pas le jeton porteur en écho.
• L’émission, l’alternance et la révocation des jetons restent borné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 possède aussi operator.admin : les appelants non administrateurs ne peuvent gérer que le jeton opérateur pour leur propre entrée d’appareil. La gestion des jetons de nœud et autres jetons non opérateur est réservée à l’administration, même pour le propre appareil de l’appelant.
• device.token.rotate et device.token.revoke vérifient aussi l’ensemble de portées du jeton opérateur cible par rapport aux portées de session actuelles de l’appelant. Les appelants non administrateurs ne peuvent pas alterner 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 du client pour AUTH_TOKEN_MISMATCH :
  • Les clients fiables peuvent tenter une 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 indications d’action pour l’opérateur.
• AUTH_SCOPE_MISMATCH signifie que le jeton d’appareil a été reconnu mais ne couvre pas le rôle/les portées demandés. Les clients ne doivent pas présenter cela comme un mauvais jeton ; invitez l’opérateur à réappairer ou à approuver le contrat de portée plus étroit/plus large.

Identité d’appareil + appairage

• Les nœuds doivent inclure une identité d’appareil stable (device.id) dérivée de l’empreinte d’une 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 de l’appairage est centrée sur les connexions directes local loopback.
• OpenClaw possède aussi un chemin étroit d’auto-connexion backend/local au conteneur pour les flux d’assistance fiables par secret partagé.
• Les connexions tailnet ou LAN sur le même hôte sont toujours traitées comme distantes pour l’appairage et nécessitent une approbation.
• Les clients WS incluent normalement l’identité device pendant connect (opérateur + nœud). Les seules exceptions opérateur sans appareil sont les chemins de confiance explicites :
  • gateway.controlUi.allowInsecureAuth=true pour la compatibilité HTTP non sécurisée limitée à localhost.
  • authentification Control UI opérateur réussie avec gateway.auth.mode: "trusted-proxy".
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (procédure d’urgence, dégradation de sécurité sévère).
  • RPC backend gateway-client en direct-loopback sur le chemin d’assistance interne réservé.
• Omettre l’identité d’appareil a des conséquences sur les portées. Lorsqu’une connexion opérateur sans appareil est autorisée via un chemin de confiance explicite, OpenClaw efface quand même les portées autodéclarées vers un ensemble vide, sauf si ce chemin possède une exception nommée de préservation des portées. Les méthodes protégées par portée échouent alors avec missing scope.
• gateway.controlUi.dangerouslyDisableDeviceAuth=true est un chemin de préservation des portées d’urgence pour Control UI. Il n’accorde pas de portées à des clients WebSocket backend personnalisés ou de forme CLI arbitraires.
• Le chemin d’assistance backend réservé en direct-loopback gateway-client préserve les portées uniquement pour les RPC internes du plan de contrôle local ; les ID backend personnalisés ne bénéficient pas de cette exception.
• Toutes les connexions doivent signer le nonce connect.challenge fourni par le serveur.

Diagnostics de migration de l’authentification d’appareil

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

Échecs de migration courants :

Cible de migration :

• Attendez toujours connect.challenge.
• Signez la charge utile v2 qui inclut le nonce 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 device/client/role/scopes/token/nonce.
• Les signatures héritées v2 restent acceptées pour la compatibilité, mais l’épinglage des métadonnées d’appareil appairé contrôle toujours la politique de commande lors de la reconnexion.

TLS + épinglage

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

Portée

Ce protocole expose l’API Gateway complète (statut, canaux, modèles, chat, agent, sessions, nœuds, approbations, etc.). La surface exacte est définie par les schémas TypeBox dans packages/gateway-protocol/src/schema.ts.

Connexe

• Protocole de pont
• Runbook Gateway