Protocole Gateway

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Transport

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

​

Négociation (connect)

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

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

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

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

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

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

​

Exemple Node

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

​

Encapsulation

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

​

Rôles + portées

​

Rôles

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

​

Portées (opérateur)

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

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

​

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

• caps : catégories de capacité de haut niveau telles que camera, canvas, screen, location, voice et talk.
• commands : liste d’autorisation des commandes pour invoke.
• permissions : bascules granulaires (par ex. screen.record, camera.capture).

​

Présence

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

​

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

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

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

​

Limitation de portée des événements de diffusion

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

​

Familles courantes de méthodes RPC

​

Familles d’événements courantes

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

​

Méthodes d’assistance de Node

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

​

RPC du registre des tâches

• 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 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 la forme d’erreur not-found 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.

​

Méthodes d’assistance pour les opérateurs

• Les opérateurs peuvent appeler commands.list (operator.read) pour récupérer l’inventaire des commandes d’exécution d’un agent.
  • agentId est facultatif ; omettez-le pour lire l’espace de travail de l’agent par défaut.
  • scope contrôle la surface ciblée par le name principal :
    • text renvoie le jeton de commande texte principal sans le / initial
    • native et le chemin par défaut both renvoient les noms natifs tenant compte du fournisseur lorsqu’ils sont disponibles
  • textAliases contient des alias slash exacts comme /model et /m.
  • nativeName contient le nom de commande natif tenant compte du fournisseur lorsqu’il existe.
  • provider est facultatif et affecte uniquement le nommage natif ainsi que la disponibilité des commandes natives de Plugin.
  • includeArgs=false omet les métadonnées d’arguments sérialisées de la réponse.
• Les opérateurs peuvent appeler tools.catalog (operator.read) pour récupérer le catalogue d’outils d’exécution d’un agent. La réponse inclut des outils groupés et des métadonnées de provenance :
  • source : core ou plugin
  • pluginId : propriétaire du Plugin lorsque source="plugin"
  • optional : indique si un outil de Plugin est facultatif
• Les opérateurs peuvent appeler tools.effective (operator.read) pour récupérer l’inventaire des outils effectif à l’exécution pour une session.
  • sessionKey est requis.
  • Le Gateway déduit le contexte d’exécution fiable depuis la session côté serveur au lieu d’accepter un contexte d’authentification ou de livraison fourni par l’appelant.
  • La réponse est limitée à la session et reflète ce que la conversation active peut utiliser immédiatement, y compris les outils du cœur, des Plugins et des canaux.
• Les opérateurs peuvent appeler tools.invoke (operator.write) pour invoquer un outil disponible via le même chemin de politique 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 session résolu doit correspondre à agentId.
  • La réponse est une enveloppe destinée au SDK avec ok, toolName, output facultatif et des champs error typés. Les refus d’approbation ou de politique renvoient ok:false dans la charge utile au lieu de contourner le pipeline de politique d’outils du Gateway.
• Les opérateurs peuvent appeler skills.status (operator.read) pour récupérer l’inventaire visible des skills d’un agent.
  • agentId est facultatif ; omettez-le pour lire l’espace de travail de l’agent par défaut.
  • La réponse inclut l’éligibilité, les exigences manquantes, les contrôles de configuration et les options d’installation assainies sans exposer les valeurs secrètes brutes.
• Les opérateurs peuvent appeler skills.search et skills.detail (operator.read) pour les métadonnées de découverte ClawHub.
• Les opérateurs peuvent appeler skills.upload.begin, skills.upload.chunk et skills.upload.commit (operator.admin) pour préparer une archive de skill privée avant de l’installer. Il s’agit d’un chemin de téléversement administrateur distinct pour les clients de confiance, et non du flux normal d’installation de skill 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 force.
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) ajoute des octets au décalage décodé exact.
  • skills.upload.commit({ uploadId, sha256? }) vérifie la taille finale et le SHA-256. La validation ne fait que finaliser le téléversement ; elle n’installe pas le skill.
  • Les archives de skill téléversées sont des archives zip contenant une racine SKILL.md. Le nom du répertoire interne de l’archive ne sélectionne jamais la cible d’installation.
• Les opérateurs peuvent appeler skills.install (operator.admin) dans 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 force doivent correspondre à la demande skills.upload.begin d’origine. Ce mode est rejeté sauf si skills.install.allowUploadedArchives est activé. Le paramètre n’affecte pas les installations ClawHub.
  • Mode installateur du Gateway : { name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? } exécute une action metadata.openclaw.install déclarée sur l’hôte du Gateway.
• Les opérateurs peuvent appeler skills.update (operator.admin) dans deux modes :
  • Le mode ClawHub met à jour un slug suivi ou toutes les installations ClawHub suivies dans l’espace de travail de l’agent par défaut.
  • Le mode configuration corrige les valeurs skills.entries.<skillKey> comme enabled, apiKey et env.

​

Vues de models.list

• Omis ou "default" : comportement d’exécution actuel. Si agents.defaults.models est configuré, la réponse est le catalogue autorisé, y compris les modèles découverts dynamiquement pour les entrées provider/*. Sinon, la réponse est le catalogue complet du Gateway.
• "configured" : comportement dimensionné pour le sélecteur. Si agents.defaults.models est configuré, il prévaut toujours, y compris la découverte limitée au fournisseur pour les entrées provider/*. Sans liste d’autorisation, la réponse utilise les entrées explicites models.providers.*.models, avec repli sur le catalogue complet uniquement lorsqu’aucune ligne de modèle configurée n’existe.
• "all" : catalogue complet du Gateway, contournant agents.defaults.models. Utilisez cette option pour les diagnostics et les interfaces de découverte, pas pour les sélecteurs de modèles normaux.

​

Approbations d’exécution

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

​

Repli de livraison de l’agent

• Les demandes agent peuvent inclure deliver=true pour demander une livraison sortante.
• bestEffortDeliver=false conserve le comportement strict : les cibles de livraison non résolues ou uniquement internes renvoient INVALID_REQUEST.
• bestEffortDeliver=true autorise le repli vers une exécution limitée à la session lorsqu’aucune route livrable externe ne peut être résolue (par exemple, sessions internes/webchat ou configurations multicanaux ambiguës).
• Les résultats finaux agent peuvent inclure result.deliveryStatus lorsqu’une livraison a été demandée, en utilisant les mêmes statuts sent, suppressed, partial_failed et failed documentés pour openclaw agent --json --deliver.

​

Versionnement

• PROTOCOL_VERSION réside dans src/gateway/protocol/version.ts.
• Les clients envoient minProtocol + maxProtocol ; le serveur rejette les plages qui n’incluent pas son protocole actuel. Les clients natifs utilisent une borne inférieure v3 afin que les clients v4 additifs puissent toujours atteindre les gateways v3.
• Les schémas + modèles sont générés à partir de définitions TypeBox :
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

​

Constantes client

​

Authentification

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

​

Identité de l’appareil + appairage

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

​

Diagnostics de migration de l’authentification d’appareil

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

​

TLS + épinglage

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

​

Portée

​

Voir aussi

• Protocole de pont
• Guide d’exploitation Gateway