Protocole du Gateway

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

Transport et tramage

• WebSocket, trames 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 initiale, 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 ferme la connexion ou 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 ou les secrets.

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

Négociation initiale

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 (format ci-dessus). pluginSurfaceUrls est facultatif et associe les noms de surfaces de Plugin (par exemple canvas) à des URL hébergées et limitées à leur portée ; ces URL pouvant expirer, les nœuds appellent node.pluginSurface.refresh avec { "surface": "canvas" } pour obtenir une nouvelle entrée. Le chemin obsolète canvasHostUrl / canvasCapability / node.canvas.capability.refresh n’est pas pris en charge ; utilisez les surfaces de Plugin.

Pendant que le Gateway termine encore le démarrage des processus auxiliaires, connect peut renvoyer une erreur UNAVAILABLE pouvant faire l’objet d’une nouvelle tentative, avec details.reason: "startup-sidecars" et retryAfterMs. Réessayez dans la limite de votre délai de connexion au lieu de considérer cela comme un échec définitif de la négociation initiale.

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 chemin de transfert mobile. Une connexion réussie avec un code de configuration de base renvoie un jeton de nœud principal ainsi qu’un jeton 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, notamment operator.talk.secrets pour les lectures de configuration de Talk, mais n’inclut aucune portée de modification de l’appairage ni operator.admin. Un accès plus étendu à l’appairage ou à l’administration nécessite un flux distinct d’appairage approuvé ou de jeton. Ne conservez hello-ok.auth.deviceTokens que lorsque l’authentification d’amorçage a été effectuée via un transport fiable (wss:// ou un appairage en boucle locale/local).

Les clients 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 ou le 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 de sous-agent) et évite que des références d’appairage CLI/appareil obsolètes bloquent les opérations locales du backend. Les clients distants, issus d’un navigateur, de type nœud, ou utilisant explicitement un jeton d’appareil ou une identité d’appareil passent toujours par les contrôles normaux d’appairage et d’élévation de portée.

Rôle de worker et protocole fermé

Les workers cloud utilisent un point d’entrée dédié en boucle locale via le tunnel SSH appartenant au Gateway, avec clé d’hôte épinglée. Il accepte uniquement l’identité du worker et ne distribue jamais l’authentification générale, les événements de nœuds, les RPC d’opérateur ou les méthodes de Plugin. Un connect strict vérifie un identifiant de connexion de courte durée, stocké sous forme de hachage et lié à l’environnement, au hachage du paquet, à 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 et l’ensemble de fonctionnalités actuels. En cas de réussite, il renvoie un worker-hello-ok minimal ; la négociation des fonctionnalités est indépendante de la version générale du protocole. Les trames restent inférieures à 64 KiB. La liste d’autorisation fermée contient worker.heartbeat, worker.transcript.commit et worker.live-event. Les validations de transcription utilisent une clôture par époque du propriétaire, une liaison de session appartenant au Gateway, une opération de comparaison-échange sur la feuille de base et une relecture durable des séquences ; le Gateway génère les identifiants d’entrée et de parent de transcription 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 sous forme de widgets intégrés hébergés.

Les capacités du client décrivent le client connecté, et non l’autorisation. Les outils d’agent peuvent déclarer des capacités requises ; le Gateway omet ces outils sauf si chaque exigence figure dans les caps du client d’origine. Les exécutions provenant d’un canal ne disposent d’aucune capacité de client 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 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": "…"    }  }}

Les nœuds déclarent leurs capacités revendiquées au moment de la connexion :

• caps : catégories générales telles que camera, canvas, screen, location, voice, talk.
• commands : liste d’autorisation des commandes pouvant être invoquées.
• permissions : paramètres granulaires (par exemple screen.record, camera.capture).

Le Gateway les considère comme des déclarations et applique les listes d’autorisation côté serveur.

Rôles et portées

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

Rôles :

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

Portées d’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 les secrets sont inclus, lisez l’identifiant de connexion du fournisseur Talk actif dans talk.resolved.config.apiKey ; talk.providers.<id>.apiKey conserve le format 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 ces préfixes principaux réservés correspondent toujours à operator.admin (src/shared/gateway-method-policy.ts) : config.*, exec.approvals.*, wizard.*, update.*.

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

node.pair.approve comporte un contrôle 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), fondé sur les commands déclarées dans la requête en attente (src/infra/node-pairing-authz.ts) :

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

Les nœuds déclarent leurs capacités revendiquées au moment de la connexion :

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

Le Gateway les considère comme des déclarations et applique les listes d’autorisation côté serveur. Les nœuds connectés peuvent publier des descripteurs facultatifs d’outils Plugin ou 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 l’unique chemin de publication ; les descripteurs d’outils de Plugin ne sont pas acceptés dans les paramètres de connect. Chaque descripteur doit utiliser un name d’outil compatible avec le fournisseur et désigner une command figurant dans la liste d’autorisation actuelle des commandes du nœud. Le Gateway fait confiance aux métadonnées des descripteurs provenant du nœud appairé, filtre les descripteurs qui ne font pas partie de la surface de commandes approuvée, les supprime lorsque le nœud se déconnecte et rejette les tentatives d’un opérateur de 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 compétences avec node.skills.update. Cette méthode réservée au rôle de nœud constitue l’unique chemin de publication des compétences du nœud ; les compétences ne sont pas acceptées dans les paramètres de connect. Chaque descripteur contient un nom sûr, une description et un contenu SKILL.md de taille limitée. Le Gateway analyse ce contenu avec le chargeur de compétences normal, l’inclut dans les instantanés de compétences 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 compétences publiées par les nœuds.

Présence

• system-presence renvoie des entrées indexées par identité d’appareil, notamment deviceId, roles et scopes, afin que les interfaces utilisateur puissent afficher une 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 l’heure de connexion actuelle avec le motif connect ; les nœuds appairés peuvent également signaler une présence durable en arrière-plan via 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 détermine 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 active de l’ordinateur pour en savoir plus sur la sélection, la confidentialité, le contexte du modèle et le comportement de routage des notifications.

Événement de maintien en vie du nœud 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 nœuds ; les sessions sans appareil ou non appairé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 anciens Gateways peuvent uniquement renvoyer { "ok": true } pour node.event ; considérez cela comme un RPC acquitté, et non comme une persistance durable de la présence.

Portée des événements diffusés

Les événements de diffusion envoyés par le serveur sont filtrés selon la 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 chat, d’agent et de résultats d’outils (événements agent diffusés en continu, événements de résultats d’outils) 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 plutôt operator.approvals.
• Les événements d’état et 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 (fermeture en cas d’échec), sauf si un gestionnaire enregistré les assouplit explicitement.

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 et des exportations de méthodes des Plugins/canaux chargés — il ne s’agit pas d’une extraction 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 du chat de l’interface utilisateur, telles que chat.inject, et autres événements de chat limités à la transcription. Dans le protocole v4, les charges utiles différentielles transportent 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, session.tool : mises à jour de la transcription, de l’opération de session en cours et du flux d’événements pour une session abonnée.
• session.approval : état assaini, en attente et terminal, des approbations pour un abonné explicitement activé sur une session exacte. Les approbations enfants utilisent l’audience persistée de l’ancêtre ; les événements ne modifient jamais les transcriptions et ne réveillent pas les agents.
• sessions.changed : l’index ou les métadonnées des sessions ont changé.
• presence : mises à jour de l’instantané de présence du système.
• tick : événement périodique de maintien de connexion/vérification d’activité.
• health : mise à jour de l’instantané d’état 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 Nodes.
• node.invoke.request : diffusion d’une demande d’invocation d’un Node.
• device.pair.requested / device.pair.resolved : cycle de vie des appareils appairés.
• voicewake.changed : la configuration du déclencheur par mot de réveil a changé.
• 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 pour les Nodes

Les Nodes peuvent appeler skills.bins pour récupérer la liste actuelle des exécutables des Skills afin d’effectuer les vérifications d’autorisation automatique.

RPC du registre d’audit

audit.activity.list fournit aux clients opérateurs une vue stable, de la plus récente à la plus ancienne, des métadonnées du cycle de vie des exécutions d’agents, des actions d’outils et des messages explicitement activés. Il exige operator.read. Les requêtes excluent les enregistrements datant 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. Consultez l’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 du message facultative ("inbound" ou "outbound") et channel exact ; bornes inclusives after / before facultatives en millisecondes Unix ; limit facultatif de 1 à 500 ; et chaîne cursor facultative provenant de la page précédente.
• Résultat : { "events": AuditActivityEventV1[], "nextCursor"?: string }.

L’union de résultats V1 nommée comporte des schémas distincts pour les exécutions d’agent, les actions d’outil, les messages entrants et les messages sortants. Le discriminateur eventType vaut respectivement agent_run, tool_action, inbound_message ou outbound_message ; kind et la direction du message restent disponibles pour le filtrage et l’affichage. Chaque événement possède un entier schemaVersion: 1. 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 des 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 de bord 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, la séquence de l’événement source, un horodatage, un acteur, une action, un état, un entier schemaVersion: 1 et redaction: "metadata_only". Les enregistrements d’exécution et d’outil exigent la provenance de l’agent et de l’exécution et peuvent inclure la provenance de la session. Les enregistrements de message peuvent inclure les identifiants de l’agent et de l’exécution, mais n’incluent délibérément 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 de l’appel d’outil et le nom de l’outil.

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 de l’échec, la durée, le nombre de résultats, le code de motif et des pseudonymes avec clé, locaux à 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 prompts, 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 des exécutions et des outils restent des métadonnées de corrélation brutes et peuvent intégrer des identifiants de compte de plateforme ou de pair ; les enregistrements de message omettent les clés de session.

Pour les lignes entrantes, durationMs mesure la durée du traitement principal jusqu’à son état terminal et resultCount compte les charges utiles finalisées de type outil mis en file d’attente, bloc et réponse. 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 vers 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 ambiguës en raison d’un plantage l’omettent.

La couverture actuelle des messages inclut les messages entrants acceptés qui atteignent le traitement principal, y compris les résultats de doublon ou terminaux du cœur. La couverture sortante é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 pouvant être retentés 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 locaux 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 des workers fonctionne au mieux et peut perdre des enregistrements en cas de défaillance 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 et de résultat audit.list, ainsi que le schéma AuditEvent, restent inchangés et renvoient uniquement les enregistrements d’exécution d’agent et d’action d’outil. Les nouveaux clients opérateur doivent appeler audit.activity.list lorsque le Gateway l’annonce. Les anciens Gateways peuvent signaler soit unknown method: audit.activity.list, soit, parce que 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. Considérez ce dernier cas comme une absence de méthode uniquement lorsque la méthode n’a pas été annoncée. Un client peut alors réessayer audit.list uniquement lorsque 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érateur 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 assainis, 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 états, agentId facultatif, sessionKey facultatif, limit facultatif de 1 à 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 « introuvable » 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 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 auxiliaires pour les opérateurs

• commands.list (operator.read) récupère l’inventaire des commandes 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 la 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 influe uniquement sur la dénomination native ainsi que sur la disponibilité des commandes natives du Plugin.
  • includeArgs=false omet de la réponse les métadonnées sérialisées des arguments.
• tools.catalog (operator.read) récupère le catalogue des outils 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 des outils effectivement disponibles à l’exécution pour une session.
  • sessionKey est requis.
  • 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 propre à la session, dérivée par le serveur, 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 stratégie finale des outils, mais ne crée pas d’environnements d’exécution MCP, ne connecte pas de transports et n’émet pas 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 effectifs utilisent source="core", source="plugin", source="channel" ou source="mcp".
• tools.invoke (operator.write) appelle un outil disponible par le même chemin de stratégie du 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 la session résolue doit correspondre à agentId.
  • Les enveloppes du cœur réservées au propriétaire, telles que cron, gateway et nodes, nécessitent une identité de propriétaire/administrateur (operator.admin), même si tools.invoke lui-même relève de operator.write.
  • La réponse est une enveloppe destinée au SDK avec les champs ok, toolName, un champ output facultatif et des champs error typés. Les refus liés à l’approbation ou à la stratégie renvoient ok:false dans la charge utile au lieu de contourner le pipeline de stratégie des outils du Gateway.
• skills.status (operator.read) récupère 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 comprend l’éligibilité, les exigences manquantes, les vérifications de configuration et les options d’installation assainies 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 son installation. Il s’agit d’un chemin de téléversement administratif distinct destiné aux clients de confiance, et non du flux normal d’installation de 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 un fichier SKILL.md à la racine. Le nom du répertoire interne de l’archive ne sélectionne 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. Ce mode est refusé sauf si skills.install.allowUploadedArchives est activé ; ce paramètre n’influe pas sur les installations 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 clients plus anciens peuvent encore envoyer dangerouslyForceUnsafeInstall ; ce champ est obsolète, accepté uniquement pour assurer la compatibilité du protocole et ignoré. Utilisez security.installPolicy pour les décisions d’installation relevant de 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 modifie les valeurs de skills.entries.<skillKey>, telles que enabled, apiKey et env.

Vues de 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 dimensionné pour un 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 explicites models.providers.<provider>.models et se rabat sur le catalogue complet uniquement lorsqu’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 comprennent 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 de diagnostic ou de découverte, et non pour les sélecteurs de modèles habituels.

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 (argv/cwd/rawCommand canoniques et métadonnées de session). Les requêtes sans systemRunPlan sont rejetées.
• Après approbation, les appels node.invoke system.run transférés réutilisent ce systemRunPlan canonique comme contexte faisant autorité pour la commande, le répertoire de travail et la session.
• 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 (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 de livraison externe ne peut être résolue (par exemple, les sessions internes/webchat ou les configurations multicanaux ambiguës).
• Les résultats finaux d’agent peuvent inclure result.deliveryStatus lorsqu’une livraison a été demandée, avec 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 ayant à la fois role: "node" et client.mode: "node" peuvent utiliser le protocole de 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 stratégie des commandes et les approbations d’exécution restent inchangées par cette fenêtre de compatibilité. Les capacités et commandes de Node appartenant aux 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 des clients

L’implémentation cliente de référence se trouve dans packages/gateway-client/src/ (OpenClaw l’enveloppe au moyen de la façade légère src/gateway/client.ts). Ces valeurs par défaut sont stables dans l’ensemble du protocole v4 et constituent la base 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 laisse les requêtes finies gérer leur délai configuré lorsque chaque requête en attente en possède un. 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 mécanisme de surveillance des ticks. Si les événements entrants et les réponses restent silencieux au-delà du seuil d’expiration des ticks, 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 le mode gateway.auth.mode configuré ("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 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’association, 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.
• Lors d’une reconnexion avec ce jeton d’appareil enregistré, l’ensemble des portées approuvé et enregistré pour ce jeton doit également être réutilisé. Cela préserve l’accès en lecture/sondage/état déjà accordé et évite que les reconnexions ne soient silencieusement réduites à une portée implicite 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é par appareil (indexé par deviceId + role).
  • auth.bootstrapToken est envoyé uniquement lorsqu’aucune des valeurs précédentes 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 la tentative unique après AUTH_TOKEN_MISMATCH est limitée aux points de terminaison fiables : 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 Node principal ainsi qu’un jeton d’opérateur à durée limitée dans hello-ok.auth.deviceTokens pour un transfert fiable vers un appareil mobile. Le jeton d’opérateur inclut operator.talk.secrets pour les lectures de configuration Talk natives, mais exclut les portées de modification d’association et operator.admin.
• Tant qu’un amorçage par code de configuration non standard 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 requête ou jusqu’à ce que le jeton devienne invalide.
• Ne conservez hello-ok.auth.deviceTokens que lorsque la connexion a utilisé une authentification d’amorçage sur un transport fiable tel que wss:// ou une association loopback/locale.
• Si un client fournit un deviceToken explicite ou des scopes explicites, cet ensemble de portées demandé par l’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é par appareil.
• Les jetons d’appareil peuvent être renouvelés/révoqués via device.token.rotate et device.token.revoke (nécessite operator.pairing). Le renouvellement ou la révocation du jeton 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 nouveau jeton porteur uniquement pour les appels provenant du même appareil et 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 effectués avec un secret partagé ou par un administrateur 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’association de cet appareil ; la modification d’un jeton ne peut pas étendre les droits ni cibler un rôle d’appareil que l’approbation de l’association n’a jamais accordé.
• Pour les sessions avec jeton d’appareil associé, 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 rôles non-opérateur est réservée aux administrateurs, même pour le propre appareil de l’appelant.
• device.token.rotate et device.token.revoke vérifient également l’ensemble des 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 les portées sont plus larges que celles 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 seule nouvelle tentative limitée avec un jeton par appareil mis en cache.
  • Si cette tentative échoue, arrêtez les boucles de reconnexion automatique et affichez des instructions d’intervention à 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 une nouvelle association ou à approuver le contrat de portée plus restreint/plus large.

Identité et association 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 approbations d’association sont requises pour les nouveaux identifiants d’appareil, sauf si l’approbation automatique locale est activée.
• L’approbation automatique des associations est centrée sur les connexions loopback locales directes.
• 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 tailnet ou LAN sur le même hôte sont toujours traitées comme distantes pour l’association et nécessitent une approbation.
• Les clients WS incluent normalement l’identité device pendant connect (opérateur + Node). Les seules exceptions permettant un 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.
  • une authentification réussie de l’opérateur dans l’interface de contrôle avec gateway.auth.mode: "trusted-proxy".
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (mesure d’urgence, dégradation sévère de la sécurité).
  • les RPC backend gateway-client en loopback direct sur le chemin interne réservé aux assistants.
• L’omission de l’identité de l’appareil a des conséquences sur les portées. Lorsqu’une connexion d’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 en les remplaçant par 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 conservation des portées d’urgence de l’interface de contrôle. Il n’accorde pas de portées à des clients WebSocket backend personnalisés ou structurés comme la CLI.
• Le chemin réservé de l’assistant backend gateway-client en loopback direct 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 de détail DEVICE_AUTH_* dans 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 privilégiée est v3 (buildDeviceAuthPayloadV3 dans packages/gateway-client/src/device-auth.ts), qui lie platform et deviceFamily en plus des champs d’appareil/client/rôle/portées/jeton/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 stratégie des commandes lors de la reconnexion.

TLS et épinglage

• TLS est pris en charge pour les connexions WS (configuration gateway.tls).
• Les clients peuvent éventuellement é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, chat, agent, sessions, nœuds, approbations, etc. La surface exacte est définie par les schémas TypeBox réexportés depuis packages/gateway-protocol/src/schema.ts.

Voir aussi

• Protocole de pont
• Guide d’exploitation du Gateway