Protocole du Gateway

Le protocole WS du Gateway constitue l’unique plan de contrôle et le transport des Nodes pour OpenClaw. Les clients opérateurs et Nodes (CLI, interface Web, application macOS, Nodes iOS/Android, Nodes sans interface) se connectent via WebSocket et déclarent un rôle et une portée au moment de la négociation de connexion.

Transport et encadrement

• WebSocket, trames de texte, charges utiles JSON.
• La première trame doit être une requête connect.
• Les trames précédant la connexion sont limitées à 64 KiB (MAX_PREAUTH_PAYLOAD_BYTES). Après la négociation de connexion, respectez 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 la connexion ou n’abandonne la trame. Ces événements contiennent surface, les tailles en octets, les limites et un code de motif sûr, mais jamais le corps des messages, le contenu des pièces jointes, les octets bruts des trames, les jetons, les cookies ni les secrets.

Formes des trames :

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

Négociation de connexion

Le Gateway envoie un défi avant la connexion :

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

Le client répond avec connect :

{  "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": "…"    }  }}

Le Gateway répond avec hello-ok :

{  "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    }  }}

server, features, snapshot, policy et auth sont tous requis par HelloOkSchema (packages/gateway-protocol/src/schema/frames.ts). auth indique le rôle et les portées négociés même lorsqu’aucun jeton d’appareil n’est émis (forme ci-dessus). pluginSurfaceUrls est facultatif et associe les noms des surfaces des Plugins (par exemple canvas) à des URL hébergées à portée limitée ; cette entrée peut expirer, les Nodes appellent donc node.pluginSurface.refresh avec { "surface": "canvas" } pour en obtenir une nouvelle. Le chemin obsolète canvasHostUrl / canvasCapability / node.canvas.capability.refresh n’est pas pris en charge ; utilisez les surfaces des Plugins. Le champ facultatif appliedConfigHash de l’instantané est la révision résolue de la configuration source acceptée par l’exécution active du Gateway. Les clients peuvent la comparer à config.get.configRevisionHash afin de déterminer si une configuration enregistrée plus récente nécessite encore un redémarrage. config.get.hash reste la révision brute du fichier racine utilisée par les protections contre les conflits d’écriture de configuration.

Pendant que le Gateway termine encore le démarrage des processus auxiliaires, connect peut renvoyer une erreur UNAVAILABLE réessayable avec details.reason: "startup-sidecars" et retryAfterMs. Réessayez dans les limites de votre budget de connexion au lieu de la traiter comme un échec définitif de la négociation de connexion.

Lorsqu’un jeton d’appareil est émis, hello-ok.auth l’ajoute :

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

L’amorçage intégré par code QR/code de configuration est un parcours de transfert mobile. Une connexion réussie avec le code de configuration de base renvoie un jeton de Node principal ainsi qu’un jeton d’opérateur limité :

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

Ce transfert à l’opérateur est volontairement limité : il suffit pour démarrer la boucle de l’opérateur mobile et la configuration native, y compris operator.talk.secrets pour les lectures de configuration de Talk, mais n’inclut ni les portées de modification de l’appairage ni operator.admin. Un accès plus étendu à l’appairage ou à l’administration nécessite un flux d’appairage ou de jeton distinct et approuvé. Ne conservez hello-ok.auth.deviceTokens que lorsque l’authentification d’amorçage a été effectuée via un transport fiable (wss:// ou appairage en boucle locale/local).

Les clients de backend fiables exécutés dans le même processus (client.id: "gateway-client", client.mode: "backend") peuvent omettre device sur les connexions directes en boucle locale 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 (par exemple, les mises à jour de session des sous-agents) et évite que des références obsolètes d’appairage de CLI/d’appareil ne bloquent le travail local du backend. Les clients distants, provenant d’un navigateur, Nodes, ainsi que les clients utilisant explicitement un jeton d’appareil ou une identité d’appareil, restent soumis aux vérifications normales d’appairage et d’élévation des portées.

Rôle de worker et protocole fermé

Les workers cloud utilisent une entrée en boucle locale dédiée via le tunnel SSH appartenant au Gateway, dont la clé d’hôte est épinglée. Elle accepte uniquement l’identité du worker et ne distribue jamais l’authentification générale, les événements de Node, les RPC d’opérateur ni les méthodes des Plugins. Un contrôle strict connect vérifie un identifiant de connexion à courte durée de vie, stocké sous forme de hachage et lié à l’environnement, au hachage du bundle, à l’époque du propriétaire, à la version de l’ensemble de RPC, à l’expiration et à une session nullable ; il vérifie séparément la version actuelle et l’ensemble de fonctionnalités. La réussite renvoie un résultat minimal worker-hello-ok ; la négociation des fonctionnalités est indépendante de la version générale du protocole. Les trames restent inférieures à 64 KiB, sauf une trame worker.inference.start négociée qui peut atteindre 25 MiB. La liste d’autorisation fermée contient worker.heartbeat, worker.transcript.commit, worker.live-event, worker.inference.start et worker.inference.cancel.

Les validations de transcription utilisent un cloisonnement par époque du propriétaire, une liaison de session appartenant au Gateway, une comparaison-échange de la feuille de base et une relecture durable des séquences ; le Gateway génère les identifiants des entrées de transcription et de leurs parents au moyen du mécanisme normal d’écriture de session. La propriété et l’expiration sont revérifiées à chaque RPC.

Capacités du client

Les clients opérateurs peuvent annoncer des capacités facultatives dans connect.params.caps :

• tool-events : accepte les événements structurés du cycle de vie des outils.
• inline-widgets : peut afficher les résultats d’outils de widgets intégrés hébergés.

Les capacités du client décrivent le client connecté, et non l’autorisation. Les outils de l’agent peuvent déclarer des capacités requises ; le Gateway omet ces outils sauf si chaque exigence figure dans le champ caps du client à l’origine de l’exécution. Les exécutions provenant d’un canal ne disposent d’aucune capacité de client du Gateway ; les outils soumis à des capacités sont donc indisponibles même lorsque la politique des outils les autorise explicitement.

Exemple de connexion d’un Node

{  "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": "…"    }  }}

Les Nodes déclarent leurs capacités revendiquées au moment de la connexion :

• caps : catégories de haut niveau telles que camera, canvas, screen, location, voice, talk.
• commands : liste d’autorisation des commandes pouvant être invoquées.
• permissions : options granulaires (par exemple screen.record, camera.capture).

Le Gateway traite ces éléments comme des revendications et applique des listes d’autorisation côté serveur.

Rôles et portées

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

Rôles :

• operator : client du plan de contrôle (CLI/interface utilisateur/automatisation).
• node : hôte de capacités (caméra/écran/canevas/system.run).
• worker : hôte d’exécution cloud utilisant le protocole dédié et fermé des workers.

Portées de l’opérateur (src/gateway/operator-scopes.ts), ensemble fermé complet :

• 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 des secrets sont inclus, lisez l’identifiant de connexion actif du fournisseur Talk depuis talk.resolved.config.apiKey ; talk.providers.<id>.apiKey conserve la forme de la source et peut être un objet SecretRef ou une chaîne expurgée.

Les méthodes RPC du Gateway enregistrées par un Plugin peuvent demander leur propre portée d’opérateur, mais les préfixes principaux réservés suivants correspondent toujours à operator.admin (src/shared/gateway-method-policy.ts) : config.*, exec.approvals.*, wizard.*, update.*.

La portée de la méthode ne constitue que le premier contrôle. Certaines commandes avec barre oblique accessibles via chat.send appliquent des vérifications plus strictes au niveau de la commande : les écritures persistantes de /config set et /config unset nécessitent operator.admin, même pour les clients du Gateway qui disposent déjà d’une portée d’opérateur inférieure.

node.pair.approve applique une vérification supplémentaire de la portée au moment de l’approbation, en plus de la portée de base de la méthode (operator.pairing), selon le champ commands déclaré par la requête en attente (src/infra/node-pairing-authz.ts) :

Capacités/commandes/autorisations (Node)

Les Nodes déclarent leurs capacités revendiquées au moment de la connexion :

• caps : catégories de capacités de haut niveau telles que camera, canvas, screen, location, voice et talk.
• commands : liste d’autorisation des commandes pouvant être invoquées.
• permissions : options granulaires (par exemple screen.record, camera.capture).

Le Gateway traite ces éléments comme des déclarations et applique des listes d’autorisation côté serveur. Les nœuds connectés peuvent publier des descripteurs facultatifs de Plugin ou d’outil MCP visibles par l’agent avec node.pluginTools.update après une connexion ou une reconnexion réussie. Les hôtes de nœuds sans interface redémarrent pour appliquer les modifications déclaratives de l’inventaire MCP. Cette méthode de mise à jour est le seul chemin de publication ; les descripteurs d’outils de Plugin ne sont pas acceptés dans les paramètres connect. Chaque descripteur doit utiliser un name d’outil sûr pour le fournisseur et nommer un command figurant dans la liste d’autorisation actuelle des commandes du nœud. Le Gateway considère comme fiables les métadonnées des descripteurs provenant du nœud appairé, filtre les descripteurs hors de la surface de commandes approuvée, les supprime lorsque le nœud se déconnecte et rejette les tentatives des opérateurs visant à modifier le catalogue d’un autre nœud. Définissez gateway.nodes.pluginTools.enabled: false pour ignorer les descripteurs publiés par les nœuds.

Les hôtes de nœuds connectés publient leur catalogue complet de remplacement des Skills avec node.skills.update. Cette méthode réservée au rôle de nœud est le seul chemin de publication des Skills du nœud ; les Skills ne sont pas acceptées dans les paramètres connect. Chaque descripteur contient un nom sûr, une description et un contenu SKILL.md limité. Le Gateway analyse ce contenu avec le chargeur de Skills normal, l’inclut dans les instantanés des Skills de l’agent tant que le nœud est connecté et le supprime lors de la déconnexion. Définissez gateway.nodes.skills.enabled: false pour ignorer les Skills publiées par les nœuds.

Présence

• system-presence renvoie des entrées indexées par identité d’appareil, comprenant deviceId, roles et scopes, afin que les interfaces puissent afficher une ligne par appareil même lorsqu’il se connecte à la fois comme opérateur et comme nœud.
• node.list comprend les champs facultatifs lastSeenAtMs et lastSeenReason. Les nœuds connectés indiquent l’heure actuelle de connexion avec la raison connect ; les nœuds appairés peuvent également signaler une présence durable en arrière-plan au moyen d’un événement de nœud fiable.

Les nœuds macOS natifs peuvent également envoyer des événements node.presence.activity authentifiés avec une durée d’inactivité d’entrée limitée. Le Gateway calcule les horodatages d’activité selon sa propre horloge, expose le Mac connecté le plus récent via node.list et node.describe, et diffuse les mises à jour node.presence aux clients disposant d’une portée de lecture. Consultez Présence de l’ordinateur actif pour le comportement de sélection, de confidentialité, de contexte du modèle et de routage des notifications.

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

Les nœuds appellent node.event avec event: "node.presence.alive" pour enregistrer qu’un nœud appairé était actif lors d’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, connect. Les valeurs inconnues sont normalisées en background (src/shared/node-presence.ts). L’événement n’est conservé que pour les sessions authentifiées d’appareils de nœud ; les sessions sans appareil ou non appairées renvoient handled: false.

Les Gateways compatibles renvoient un résultat structuré :

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

Les anciens Gateways peuvent ne renvoyer que { "ok": true } pour node.event ; considérez cela comme un RPC accusé de réception, et non comme une persistance durable de la présence.

Portée des événements diffusés

Les événements diffusés par le serveur sont filtrés par portée afin que les sessions limitées à l’appairage ou aux nœuds ne reçoivent pas passivement le contenu des sessions (src/gateway/server-broadcast.ts) :

• Les trames de discussion, d’agent et de résultat d’outil (événements agent diffusés en continu, événements de résultat d’outil) nécessitent au minimum operator.read. Les sessions qui n’en disposent pas ignorent entièrement ces trames.
• Les diffusions plugin.* définies par les Plugins sont limitées par défaut à operator.write ou operator.admin ; les entrées explicites telles que plugin.approval.requested / plugin.approval.resolved utilisent operator.approvals à la place.
• Les événements d’état/de transport (heartbeat, presence, tick, cycle de vie de connexion/déconnexion) restent sans restriction afin que l’état du transport soit observable par chaque session authentifiée.
• Les familles inconnues d’événements diffusés sont filtrées par portée par défaut (échec fermé), sauf si un gestionnaire enregistré assouplit explicitement cette règle.

Chaque connexion cliente conserve son propre numéro de séquence par client, de sorte que les diffusions restent ordonnées de manière monotone sur ce socket, même lorsque différents clients voient des sous-ensembles distincts du flux d’événements, filtrés selon leur portée.

Familles de méthodes RPC

hello-ok.features.methods est une liste de découverte prudente construite à partir de src/gateway/server-methods-list.ts ainsi que des exports de méthodes des Plugins/canaux chargés ; il ne s’agit pas d’une liste générée de toutes les méthodes, et certaines méthodes (par exemple push.test, web.login.start, web.login.wait, sessions.usage) sont intentionnellement exclues de la découverte, bien qu’elles soient réelles et appelables. Considérez cette liste comme un mécanisme de découverte des 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 discussion de l’interface utilisateur telles que chat.inject et autres événements de discussion réservés à la transcription. Dans le protocole v4, les charges utiles différentielles transportent deltaText ; message reste l’instantané cumulatif de l’assistant. Les remplacements sans préfixe définissent replace=true et utilisent deltaText comme texte de remplacement.
• session.message, session.operation, session.tool : mises à jour de la transcription, des opérations de session en cours et du flux d’événements pour une session suivie.
• session.approval : état fiable et nettoyé des approbations en attente et terminales pour un abonné à une session exacte ayant explicitement accepté de les recevoir. Les approbations enfants utilisent l’audience persistante de l’ancêtre ; les événements ne modifient jamais les transcriptions et ne réveillent jamais les agents.
• sessions.changed : modification de l’index ou des métadonnées de session.
• presence : mises à jour de l’instantané de présence du système.
• tick : événement périodique de maintien de connexion/vitalité.
• health : mise à jour de l’instantané de santé du Gateway.
• heartbeat : mise à jour du flux d’événements Heartbeat.
• cron : événement de modification d’une exécution/tâche Cron.
• shutdown : notification d’arrêt du Gateway.
• node.pair.requested / node.pair.resolved : cycle de vie de l’appairage des Node.
• node.invoke.request : diffusion d’une requête d’invocation de Node.
• device.pair.requested / device.pair.resolved : cycle de vie des appareils appairés.
• voicewake.changed : modification de la configuration du déclencheur par mot de réveil.
• exec.approval.requested / exec.approval.resolved : cycle de vie des approbations d’exécution.
• plugin.approval.requested / plugin.approval.resolved : cycle de vie des approbations de Plugin.

Méthodes d’assistance des Node

Les Node peuvent appeler skills.bins pour récupérer la liste actuelle des exécutables de Skills à utiliser dans les vérifications d’autorisation automatique.

RPC du registre d’audit

audit.activity.list fournit aux clients opérateurs une vue stable, du plus récent au plus ancien, des métadonnées du cycle de vie des exécutions d’agent, des actions d’outil et des messages ayant fait l’objet d’une acceptation explicite. Il exige operator.read. Les requêtes excluent les enregistrements de plus de 30 jours et le registre SQLite partagé est limité à 100,000 enregistrements. Les lignes expirées sont supprimées au démarrage du Gateway, lors de la maintenance horaire et des écritures ultérieures. Voir Historique d’audit pour le modèle de données et la sémantique de confidentialité.

• Paramètres : agentId, sessionKey ou runId exact facultatif ; kind facultatif ("agent_run", "tool_action" ou "message") ; status facultatif ("started", "succeeded", "failed", "cancelled", "timed_out", "blocked" ou "unknown") ; direction de message facultatif ("inbound" ou "outbound") et channel exact ; limites inclusives facultatives after / before en millisecondes Unix ; limit facultatif de 1 à 500 ; et chaîne facultative cursor provenant de la page précédente.
• Résultat : { "events": AuditActivityEventV1[], "nextCursor"?: string }.

L’union de résultats V1 nommée possède des schémas distincts pour les exécutions d’agent, les actions d’outil, les messages entrants et les messages sortants. Le discriminateur eventType est respectivement agent_run, tool_action, inbound_message ou outbound_message ; kind et le direction de message restent disponibles pour le filtrage et l’affichage. Chaque événement possède un schemaVersion: 1 entier. Les références d’identité de message utilisent le format exact hmac-sha256:v1:<32 hex key id>:<64 hex digest> ; l’identifiant d’un acteur expéditeur de canal utilise le même format.

Toutes les variantes exigent eventType, schemaVersion, eventId, sequence, sourceSequence, occurredAt, kind, action, status, actor et redaction. Les champs des variantes sont les suivants :

Les énumérations fermées de messages sont les suivantes :

• conversationKind : direct, group, channel ou unknown.
• outcome entrant : completed, skipped ou failed ; reasonCode facultatif : duplicate, reply_operation_active, reply_operation_aborted, fast_abort, plugin_bound_handled, plugin_bound_unavailable, plugin_bound_declined, plugin_bound_error, before_dispatch_handled, acp_dispatch_completed, acp_dispatch_failed, acp_dispatch_empty ou acp_dispatch_aborted.
• outcome sortant : sent, suppressed, failed ou unknown ; reasonCode facultatif : cancelled_by_message_sending_hook, cancelled_by_reply_payload_sending_hook, empty_after_message_sending_hook, empty_after_reply_payload_sending_hook ou no_visible_payload. Un adaptateur qui ne renvoie aucune identité de plateforme est unknown, car l’effet secondaire externe ne peut pas être réfuté.
• deliveryKind : text, media ou other ; failureStage : platform_send, queue ou unknown.

Les champs terminaux sont corrélés et non facultatifs indépendamment :

Chaque événement d’activité comprend un identifiant d’événement stable, une séquence de registre monotone, une séquence d’événement source, un horodatage, un acteur, une action, un statut, un entier schemaVersion: 1 et redaction: "metadata_only". Les enregistrements d’exécution et d’outil nécessitent la provenance de l’agent et de l’exécution et peuvent inclure la provenance de la session. Les enregistrements de message peuvent inclure des identifiants d’agent et d’exécution, mais n’incluent intentionnellement jamais sessionKey ni sessionId ; le filtre de requête sessionKey ne s’applique donc qu’aux lignes d’exécution et d’outil. Les événements d’outil peuvent inclure l’identifiant d’appel de l’outil et son nom.

Les enregistrements de message utilisent message.inbound.processed ou message.outbound.finished et ajoutent la direction, le canal, le type de conversation, le résultat normalisé ainsi que, facultativement, le type de livraison, l’étape d’échec, la durée, le nombre de résultats, le code de motif et des pseudonymes avec clé, propres à l’installation, pour le compte, la conversation, le message et la cible. Ces pseudonymes facilitent la corrélation, mais ne constituent pas une anonymisation : la base de données d’état contient leur clé, contrairement aux exportations RPC et CLI. Le registre ne stocke ni les invites, ni le contenu des messages, ni les arguments ou résultats des outils, ni la sortie des commandes, ni le texte brut des erreurs. Les valeurs sessionKey d’exécution et d’outil restent des métadonnées de corrélation brutes et peuvent intégrer des identifiants de compte ou de pair de la plateforme ; les enregistrements de message omettent les clés de session.

Pour les lignes entrantes, durationMs mesure le traitement par le cœur jusqu’à son état terminal et resultCount compte les charges utiles finalisées d’outil, de bloc et de réponse mises en file d’attente. Pour les lignes sortantes, durationMs couvre la prise en charge de la livraison jusqu’à l’accusé de réception, la lettre morte ou la réconciliation (temps d’attente en file compris), et resultCount compte les envois physiques identifiés sur la plateforme. deliveryKind, lorsqu’il est présent, décrit la charge utile effective après les hooks et le rendu ; les lignes supprimées ou rendues ambiguës par un plantage l’omettent.

La couverture actuelle des messages comprend les messages entrants acceptés qui atteignent le traitement par le cœur, y compris les résultats de doublon ou terminaux du cœur. Pour les messages sortants, elle écrit une ligne terminale par charge utile de réponse logique d’origine qui atteint la livraison durable partagée ; le découpage et la distribution par les adaptateurs sont agrégés dans resultCount. Les envois réessayables ou ambigus mis en file d’attente ne sont enregistrés qu’après un accusé de réception, une lettre morte ou une réconciliation. Les chemins propres aux Plugins et les chemins d’envoi direct qui contournent ces limites partagées ne sont pas encore couverts. La file d’attente bornée du worker fonctionne au mieux et peut perdre des enregistrements en cas d’échec ou de saturation ; cette surface ne constitue donc pas une archive de conformité sans perte.

L’enregistrement est activé par défaut et contrôlé par audit.enabled. L’enregistrement des messages est contrôlé séparément par audit.messages et sa valeur par défaut est "off". Lorsque l’enregistrement est désactivé, audit.activity.list continue de fournir les enregistrements écrits précédemment jusqu’à leur expiration.

Les schémas livrés de requête audit.list, de résultat et de AuditEvent restent inchangés et renvoient uniquement les enregistrements d’exécution d’agent et d’action d’outil. Les nouveaux clients opérateurs doivent appeler audit.activity.list lorsque le Gateway l’annonce. Les anciens Gateways peuvent signaler soit unknown method: audit.activity.list, soit, puisque l’autorisation précédait la recherche de méthode dans les versions livrées, missing scope: operator.admin pour une requête limitée à la lecture. Ne considérez ce dernier comme une absence de méthode que si la méthode n’était pas annoncée. Un client peut alors réessayer audit.list uniquement si ses filtres ne nécessitent pas la prise en charge du type de message, de la direction ou du canal.

Utilisez openclaw audit pour les requêtes textuelles et les exportations JSON bornées.

RPC du registre des tâches

Les clients opérateurs inspectent et annulent les enregistrements de tâches en arrière-plan du Gateway au moyen des RPC du registre des tâches (packages/gateway-protocol/src/schema/tasks.ts). Ceux-ci renvoient des résumés de tâches nettoyés, et non l’état brut de l’environnement d’exécution.

• tasks.list nécessite 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 compris entre 1 et 500, et chaîne cursor facultative.
  • Résultat : { "tasks": TaskSummary[], "nextCursor"?: string }.
• tasks.get nécessite operator.read.
  • Paramètres : { "taskId": string }.
  • Résultat : { "task": TaskSummary }.
  • Les identifiants de tâche manquants renvoient le format d’erreur d’absence de résultat du Gateway.
• tasks.cancel nécessite 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’environnement d’exécution a accepté ou enregistré l’annulation.

TaskSummary comprend id, status et des métadonnées facultatives : 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 nettoyé. 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 pour les opérateurs

• commands.list (operator.read) récupère l’inventaire des commandes de l’environnement d’exécution pour un agent.
  • agentId est facultatif ; omettez-le pour lire l’espace de travail de l’agent par défaut.
  • scope détermine la surface ciblée par le name principal : text renvoie le jeton principal de commande textuelle sans le / initial ; native et le chemin both par défaut renvoient les noms natifs adaptés au fournisseur lorsqu’ils sont disponibles.
  • textAliases contient les alias exacts avec barre oblique, tels que /model et /m.
  • nativeName contient le nom de commande natif adapté au fournisseur lorsqu’il existe.
  • provider est facultatif et n’affecte que la dénomination native ainsi que la disponibilité des commandes natives des Plugins.
  • includeArgs=false omet de la réponse les métadonnées d’arguments sérialisées.
• tools.catalog (operator.read) récupère le catalogue des outils de l’environnement d’exécution pour un agent. La réponse comprend les outils regroupé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
• tools.effective (operator.read) récupère l’inventaire effectif des outils de l’environnement d’exécution pour une session.
  • sessionKey est obligatoire.
  • Le Gateway déduit le contexte d’exécution fiable de la session côté serveur au lieu d’accepter un contexte d’authentification ou de livraison fourni par l’appelant.
  • La réponse est une projection dérivée par le serveur et limitée à la session de l’inventaire actif, comprenant 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 le catalogue MCP d’une session active au travers de la politique finale des outils, mais ne crée pas d’environnements d’exécution MCP, ne connecte pas de transports et n’émet pas de tools/list. Si aucun catalogue actif correspondant n’existe, la réponse peut inclure un avis tel que mcp-not-yet-connected, mcp-not-yet-listed ou mcp-stale-catalog.
  • Les entrées d’outils effectives utilisent source="core", source="plugin", source="channel" ou source="mcp".
• tools.invoke (operator.write) appelle un outil disponible au moyen du même chemin de politique 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.
  • Les wrappers du cœur réservés au propriétaire, tels que cron, gateway et nodes, nécessitent une identité de propriétaire ou d’administrateur (operator.admin), même si tools.invoke est lui-même operator.write.
  • La réponse est une enveloppe destinée au SDK avec ok, toolName, un champ output facultatif et des champs error typés. Les refus liés à l’approbation ou à la politique renvoient ok:false dans la charge utile au lieu de contourner le pipeline de politique des outils du Gateway.
• skills.status (operator.read) récupère l’inventaire des Skills visibles pour un agent.
  • agentId est facultatif ; omettez-le pour lire l’espace de travail de l’agent par défaut.
  • La réponse comprend l’éligibilité, les exigences manquantes, les vérifications de configuration et les options d’installation nettoyées sans exposer les valeurs brutes des secrets.
• skills.search et skills.detail (operator.read) renvoient les métadonnées de découverte de ClawHub.
• skills.upload.begin, skills.upload.chunk et skills.upload.commit (operator.admin) préparent une archive privée de Skill avant de l’installer. Il s’agit d’un chemin distinct de téléversement administratif destiné aux clients de confiance, et non du flux normal d’installation des Skills de 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 téléversement lié à ce slug et à cette valeur de forçage.
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) ajoute des octets à l’offset décodé exact.
  • skills.upload.commit({ uploadId, sha256? }) vérifie la taille finale et le SHA-256. La validation ne fait que finaliser le téléversement ; elle 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 détermine jamais la cible d’installation.
• skills.install (operator.admin) comporte trois 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 téléversement : { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } installe un téléversement validé dans le répertoire skills/<slug> de l’espace de travail de l’agent par défaut. Le slug et la valeur de forçage doivent correspondre à la requête skills.upload.begin d’origine. Rejeté sauf si skills.install.allowUploadedArchives est activé ; ce paramètre n’affecte pas les installations de ClawHub.
  • Mode programme d’installation du Gateway : { name, installId, timeoutMs? } exécute une action metadata.openclaw.install déclarée sur l’hôte du 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.
• skills.update (operator.admin) comporte 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 models.list

models.list accepte un paramètre view facultatif (src/agents/model-catalog-visibility.ts) :

• Omis ou "default" : si agents.defaults.models est configuré, la réponse correspond au catalogue autorisé, y compris les modèles découverts dynamiquement pour les entrées provider/*. Sinon, la réponse correspond au catalogue complet du Gateway.
• "configured" : comportement adapté au sélecteur. Si agents.defaults.models est configuré, il reste prioritaire, y compris pour la découverte limitée au fournisseur des entrées provider/*. Sans liste d’autorisation, la réponse utilise les entrées models.providers.<provider>.models explicites et ne se rabat sur le catalogue complet que si aucune ligne de modèle configurée n’existe.
• "provider-config" : inventaire models.providers.*.models défini par la source, indépendant des listes d’autorisation du sélecteur. Les lignes incluent les capacités publiques des modèles et la disponibilité tenant compte des routes, mais omettent les points de terminaison des fournisseurs, les données d’authentification et la configuration des requêtes d’exécution.
• "all" : catalogue complet du Gateway, sans tenir compte de agents.defaults.models. À utiliser pour les interfaces utilisateur de diagnostic et de découverte, et non pour les sélecteurs de modèles ordinaires.

Approbations d’exécution

• Lorsqu’une requête d’exécution nécessite une approbation, le Gateway diffuse exec.approval.requested.
• Les clients opérateurs la traitent en appelant exec.approval.resolve (nécessite operator.approvals).
• Pour host=node, exec.approval.request doit inclure systemRunPlan (métadonnées canoniques argv/cwd/rawCommand/de session). Les requêtes dépourvues de 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, de répertoire de travail et de session faisant autorité.
• Si un appelant modifie command, rawCommand, cwd, agentId ou sessionKey entre la préparation et le transfert system.run final approuvé, le Gateway rejette l’exécution au lieu de faire confiance à la charge utile modifiée.

Solution de repli pour la livraison de l’agent

• Les requêtes agent peuvent inclure deliver=true pour demander une livraison sortante.
• bestEffortDeliver=false (la valeur par défaut) 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 externe permettant la livraison ne peut être résolue (par exemple, pour les sessions internes/de chat web ou les configurations multicanaux ambiguës).
• Les résultats agent finaux peuvent inclure result.deliveryStatus lorsqu’une livraison a été demandée, en utilisant les mêmes états sent, suppressed, partial_failed et failed que ceux documentés pour openclaw agent --json --deliver.

Gestion des versions

• PROTOCOL_VERSION, MIN_CLIENT_PROTOCOL_VERSION, MIN_NODE_PROTOCOL_VERSION et MIN_PROBE_PROTOCOL_VERSION se trouvent dans packages/gateway-protocol/src/version.ts.
• Les clients envoient minProtocol + maxProtocol. Les clients opérateurs et d’interface utilisateur doivent inclure le protocole actuel dans cette plage ; les clients et serveurs actuels utilisent le protocole v4.
• Les clients authentifiés disposant à la fois de role: "node" et de client.mode: "node" peuvent utiliser le protocole Node N-1 (actuellement v3). Les sondes légères de redémarrage utilisent la même fenêtre N-1. L’authentification des appareils, l’association, les portées, la politique de commande et les approbations d’exécution ne sont pas modifiées par cette fenêtre de compatibilité. Les capacités et commandes Node détenues par des Plugins sont masquées jusqu’à ce que le Node soit mis à niveau vers le protocole actuel, car leurs surfaces hébergées ne font pas partie du contrat N-1.
• Les schémas et les modèles sont générés à partir des définitions TypeBox :
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

Constantes du client

L’implémentation du client de référence se trouve dans packages/gateway-client/src/ (OpenClaw l’encapsule au moyen de la façade légère src/gateway/client.ts). Ces valeurs par défaut sont stables pour le protocole v4 et constituent la référence attendue pour les clients tiers.

Le serveur annonce les valeurs effectives de policy.tickIntervalMs, policy.maxPayload et policy.maxBufferedBytes dans hello-ok ; les clients doivent respecter ces valeurs plutôt que les valeurs par défaut antérieures à la négociation.

Le client de référence permet aux requêtes finies de gérer leur propre échéance configurée lorsque chaque requête en attente en possède une. Une requête expectFinal sans timeoutMs fini, toute requête avec timeoutMs: null, ou un mélange de requêtes finies et sans limite maintient actif le chien de garde de pulsation. Si les événements entrants et les réponses restent silencieux au-delà du seuil d’expiration de la pulsation, le client ferme le socket avec le code 4000, rejette toutes les requêtes en attente et se reconnecte. Il ne réexécute pas les requêtes rejetées après la reconnexion.

Authentification

• L’authentification du Gateway par secret partagé utilise connect.params.auth.token ou connect.params.auth.password, selon la valeur configurée de gateway.auth.mode ("none" | "token" | "password" | "trusted-proxy").
• Les modes porteurs d’identité tels que Tailscale Serve (gateway.auth.allowTailscale: true) ou gateway.auth.mode: "trusted-proxy" hors boucle locale satisfont le contrôle d’authentification de la connexion à partir des en-têtes de requête plutôt que de connect.params.auth.*.
• Le gateway.auth.mode: "none" à entrée privée ignore entièrement l’authentification de connexion par secret partagé ; n’exposez pas ce mode sur une entrée publique ou non fiable.
• Après l’appairage, le Gateway émet un jeton d’appareil limité au rôle et aux portées de la connexion, renvoyé dans hello-ok.auth.deviceToken. Les clients doivent le conserver après toute connexion réussie.
• La reconnexion avec ce jeton d’appareil enregistré doit également réutiliser l’ensemble de portées approuvé et enregistré pour ce jeton. Cela préserve les accès de lecture, de sondage et d’état déjà accordés 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 packages/gateway-client/src/client.ts) :
  • auth.password est indépendant et toujours transmis lorsqu’il est défini.
  • auth.token est renseigné selon l’ordre de priorité suivant : d’abord le jeton partagé explicite, puis un deviceToken explicite, puis un jeton enregistré propre à l’appareil (indexé par deviceId + role).
  • auth.bootstrapToken n’est envoyé que si aucun des éléments ci-dessus n’a permis de déterminer auth.token. Un jeton partagé ou tout jeton d’appareil déterminé le désactive.
  • La promotion automatique d’un jeton d’appareil enregistré lors de l’unique nouvelle tentative AUTH_TOKEN_MISMATCH est limitée aux points de terminaison fiables : boucle locale, ou wss:// avec une valeur tlsFingerprint épinglée. 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 Node principal ainsi qu’un jeton d’opérateur à portée limitée dans hello-ok.auth.deviceTokens pour un transfert mobile fiable. Le jeton d’opérateur inclut operator.talk.secrets pour les lectures de configuration Talk natives, mais exclut les portées de modification de l’appairage et operator.admin.
• Pendant qu’un amorçage par code de configuration hors référence attend une approbation, les détails de PAIRING_REQUIRED incluent recommendedNextStep: "wait_then_retry", retryable: true et pauseReconnect: false. Continuez à vous reconnecter avec le même jeton d’amorçage jusqu’à l’approbation de la demande ou l’invalidation du jeton.
• Ne conservez hello-ok.auth.deviceTokens que lorsque la connexion a utilisé l’authentification d’amorçage sur un transport fiable tel que wss:// ou un appairage local/par boucle locale.
• Si un client fournit un deviceToken explicite ou un scopes explicite, l’ensemble de portées demandé par cet appelant reste la référence ; les portées mises en cache ne sont réutilisées que lorsque le client réutilise le jeton enregistré propre à l’appareil.
• Les jetons d’appareil peuvent être renouvelés ou révoqués via device.token.rotate et device.token.revoke (nécessite operator.pairing). Le renouvellement ou la révocation d’un Node ou d’un autre rôle non-opérateur nécessite également operator.admin.
• device.token.rotate renvoie les métadonnées de renouvellement. Il renvoie 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 uniquement un jeton puissent conserver son remplacement avant de se reconnecter. Les renouvellements partagés ou administratifs ne renvoient pas le jeton porteur.
• L’émission, le renouvellement et la révocation de jetons restent limités à l’ensemble de rôles approuvé et enregistré dans l’entrée d’appairage de cet appareil ; la modification d’un jeton ne peut ni étendre ni cibler un rôle d’appareil que l’approbation d’appairage n’a jamais accordé.
• Pour les sessions utilisant un jeton d’appareil appairé, la gestion des appareils est limitée à l’appareil lui-même, sauf si l’appelant possède également operator.admin : les appelants non administrateurs peuvent gérer uniquement le jeton d’opérateur de leur propre entrée d’appareil. La gestion des jetons de Node et des autres jetons non-opérateurs est réservée aux administrateurs, même pour l’appareil de l’appelant.
• device.token.rotate et device.token.revoke vérifient également l’ensemble de portées du jeton d’opérateur ciblé par rapport aux portées de la session actuelle de l’appelant. Les appelants non administrateurs ne peuvent ni renouveler ni révoquer un jeton d’opérateur dont la portée est plus large que celle qu’ils possèdent 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 : l’une des valeurs retry_with_device_token, update_auth_configuration, update_auth_credentials, wait_then_retry, review_auth_configuration (packages/gateway-protocol/src/connect-error-details.ts).
• Comportement du client pour AUTH_TOKEN_MISMATCH :
  • Les clients fiables peuvent effectuer une unique nouvelle tentative limitée avec un jeton propre à l’appareil mis en cache.
  • Si cette nouvelle tentative échoue, arrêtez les boucles de reconnexion automatique et affichez des instructions sur l’intervention requise de l’opérateur.
• AUTH_SCOPE_MISMATCH signifie que le jeton d’appareil a été reconnu, mais qu’il ne couvre pas le rôle ou les portées demandés. Ne le présentez pas comme un jeton incorrect ; invitez l’opérateur à effectuer un nouvel appairage ou à approuver le contrat de portée plus étroit ou plus large.

Identité et appairage des appareils

• Les Nodes 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 et par rôle.
• Les nouveaux identifiants d’appareil nécessitent une approbation d’appairage, sauf si l’approbation automatique locale est activée.
• L’approbation automatique de l’appairage est centrée sur les connexions locales directes par boucle locale.
• OpenClaw dispose également d’un chemin étroit d’auto-connexion locale au backend/conteneur pour les flux d’assistance fiables utilisant un secret partagé.
• Les connexions au tailnet ou au réseau local depuis le même hôte restent considérées comme distantes pour l’appairage et nécessitent une approbation.
• Les clients WS incluent normalement une identité device pendant connect (opérateur + Node). Les seules exceptions sans appareil pour les opérateurs sont les 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 de contrôle opérateur gateway.auth.mode: "trusted-proxy".
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (solution de dernier recours, dégradation sévère de la sécurité).
  • RPC backend gateway-client en boucle locale directe sur le chemin d’assistance interne réservé.
• L’absence d’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 tout de même les portées autodéclarées pour obtenir un ensemble vide, sauf si ce chemin possède une exception nommée de conservation des portées. Les méthodes soumises à des portées échouent alors avec missing scope.
• gateway.controlUi.dangerouslyDisableDeviceAuth=true est un chemin de dernier recours de conservation des portées pour l’interface de contrôle. Il n’accorde pas de portées à des clients WebSocket arbitraires de backend personnalisé ou présentant la forme de la CLI.
• Le chemin d’assistance backend réservé gateway-client en boucle locale directe conserve les portées uniquement pour les RPC internes du plan de contrôle local ; les identifiants de 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 des appareils

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

Échecs de migration courants :

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 recommandée est v3 (buildDeviceAuthPayloadV3 dans packages/gateway-client/src/device-auth.ts), qui lie platform et deviceFamily en plus des champs d’appareil, de client, de rôle, de portées, de jeton et de nonce.
• Les signatures v2 héritées restent acceptées à des fins de compatibilité, mais l’épinglage des métadonnées des appareils appairés continue de contrôler la politique des commandes lors de la reconnexion.

TLS et épinglage

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

Portée

Ce protocole expose l’intégralité de l’API du Gateway : état, canaux, modèles, discussion, agent, sessions, Nodes, approbations et plus encore. La surface exacte est définie par les schémas TypeBox réexportés depuis packages/gateway-protocol/src/schema.ts.

Rubriques connexes

• Protocole de pont
• Guide d’exploitation du Gateway