Protocolo de Gateway

El protocolo WS del Gateway es el plano de control único + transporte de nodos para OpenClaw. Todos los clientes (CLI, interfaz web, app de macOS, nodos iOS/Android, nodos sin interfaz) se conectan por WebSocket y declaran su rol + alcance durante el handshake.

Transporte

• WebSocket, tramas de texto con cargas JSON.
• La primera trama debe ser una solicitud connect.
• Las tramas previas a la conexión tienen un límite de 64 KiB. Después de un handshake correcto, los clientes deben seguir los límites hello-ok.policy.maxPayload y hello-ok.policy.maxBufferedBytes. Con los diagnósticos activados, las tramas entrantes demasiado grandes y los búferes salientes lentos emiten eventos payload.large antes de que el Gateway cierre o descarte la trama afectada. Estos eventos conservan tamaños, límites, superficies y códigos de motivo seguros. No conservan el cuerpo del mensaje, el contenido de adjuntos, el cuerpo sin procesar de la trama, tokens, cookies ni valores secretos.

Handshake (connect)

Gateway → Cliente (desafío previo a la conexión):

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

Cliente → Gateway:

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

Gateway → Cliente:

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

Mientras el Gateway todavía termina de iniciar sidecars, la solicitud connect puede devolver un error UNAVAILABLE reintentable con details.reason establecido en "startup-sidecars" y retryAfterMs. Los clientes deben reintentar esa respuesta dentro de su presupuesto general de conexión en lugar de mostrarla como un fallo terminal del handshake.

server, features, snapshot y policy son obligatorios según el esquema (packages/gateway-protocol/src/schema/frames.ts). auth también es obligatorio e informa el rol y los alcances negociados. pluginSurfaceUrls es opcional y asigna nombres de superficies de Plugin, como canvas, a URL hospedadas con alcance.

Las URL de superficies de Plugin con alcance pueden caducar. Los nodos pueden llamar a node.pluginSurface.refresh con { "surface": "canvas" } para recibir una entrada nueva en pluginSurfaceUrls. La refactorización experimental del Plugin Canvas no admite la ruta de compatibilidad obsoleta canvasHostUrl, canvasCapability ni node.canvas.capability.refresh; los clientes nativos y gateways actuales deben usar superficies de Plugin.

Cuando no se emite un token de dispositivo, hello-ok.auth informa los permisos negociados sin campos de token:

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

Los clientes backend de confianza del mismo proceso (client.id: "gateway-client", client.mode: "backend") pueden omitir device en conexiones directas de loopback cuando se autentican con el token/contraseña compartidos del Gateway. Esta ruta está reservada para RPC internos del plano de control y evita que las líneas base obsoletas de emparejamiento CLI/dispositivo bloqueen trabajo backend local, como actualizaciones de sesiones de subagentes. Los clientes remotos, clientes de origen de navegador, clientes de nodo y clientes explícitos de token de dispositivo/identidad de dispositivo siguen usando las comprobaciones normales de emparejamiento y aumento de alcance.

Cuando se emite un token de dispositivo, hello-ok también incluye:

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

El bootstrap integrado por QR/código de configuración es una ruta nueva de traspaso móvil. Una conexión correcta con código de configuración de línea base devuelve un token de nodo principal más un token de operador limitado:

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

El traspaso de operador está limitado intencionalmente para que el onboarding por QR pueda iniciar el bucle de operador móvil sin conceder operator.admin ni operator.pairing. Sí incluye operator.talk.secrets para que el cliente nativo pueda leer la configuración de Talk que necesita después del bootstrap. Los alcances más amplios de administración y emparejamiento requieren un emparejamiento de operador aprobado por separado o un flujo de token. Los clientes deben conservar hello-ok.auth.deviceTokens solo cuando la conexión haya usado autenticación de bootstrap en un transporte de confianza, como wss:// o loopback/emparejamiento local.

Ejemplo de nodo

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

Encuadre

• Solicitud: {type:"req", id, method, params}
• Respuesta: {type:"res", id, ok, payload|error}
• Evento: {type:"event", event, payload, seq?, stateVersion?}

Los métodos con efectos secundarios requieren claves de idempotencia (consulta el esquema).

Roles + alcances

Para ver el modelo completo de alcances de operador, las comprobaciones en el momento de aprobación y la semántica de secretos compartidos, consulta Alcances de operador.

Roles

• operator = cliente del plano de control (CLI/interfaz/automatización).
• node = host de capacidades (cámara/pantalla/canvas/system.run).

Alcances (operador)

Alcances comunes:

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

talk.config con includeSecrets: true requiere operator.talk.secrets (o operator.admin). Cuando se incluyen secretos, los clientes deben leer la credencial activa del proveedor de Talk desde talk.resolved.config.apiKey; talk.providers.<id>.apiKey mantiene la forma de origen y puede ser un objeto SecretRef o una cadena redactada.

Los métodos RPC del Gateway registrados por Plugins pueden solicitar su propio alcance de operador, pero los prefijos reservados de administración del núcleo (config.*, exec.approvals.*, wizard.*, update.*) siempre se resuelven como operator.admin.

El alcance del método es solo la primera puerta. Algunos comandos slash alcanzados mediante chat.send aplican comprobaciones más estrictas a nivel de comando encima. Por ejemplo, las escrituras persistentes /config set y /config unset requieren operator.admin.

node.pair.approve también tiene una comprobación adicional de alcance en el momento de aprobación encima del alcance base del método:

• solicitudes sin comandos: operator.pairing
• solicitudes con comandos de nodo que no son de ejecución: operator.pairing + operator.write
• solicitudes que incluyen system.run, system.run.prepare o system.which: operator.pairing + operator.admin

Capacidades/comandos/permisos (nodo)

Los nodos declaran sus afirmaciones de capacidades durante la conexión:

• caps: categorías de capacidades de alto nivel como camera, canvas, screen, location, voice y talk.
• commands: lista de comandos permitidos para invocación.
• permissions: conmutadores granulares (por ejemplo, screen.record, camera.capture).

El Gateway trata esto como afirmaciones y aplica listas de permitidos del lado del servidor.

Presencia

• system-presence devuelve entradas indexadas por identidad de dispositivo.
• Las entradas de presencia incluyen deviceId, roles y scopes para que las interfaces puedan mostrar una sola fila por dispositivo incluso cuando se conecta como operator y node.
• node.list incluye campos opcionales lastSeenAtMs y lastSeenReason. Los nodos conectados informan su hora de conexión actual como lastSeenAtMs con el motivo connect; los nodos emparejados también pueden informar presencia duradera en segundo plano cuando un evento de nodo de confianza actualiza sus metadatos de emparejamiento.

Evento de nodo activo en segundo plano

Los nodos pueden llamar a node.event con event: "node.presence.alive" para registrar que un nodo emparejado estaba activo durante un despertar en segundo plano sin marcarlo como conectado.

{  "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 es un enum cerrado: background, silent_push, bg_app_refresh, significant_location, manual o connect. Las cadenas de trigger desconocidas se normalizan a background en el Gateway antes de persistirse. El evento solo es duradero para sesiones autenticadas de dispositivo de nodo; las sesiones sin dispositivo o sin emparejar devuelven handled: false.

Los gateways correctos devuelven un resultado estructurado:

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

Los gateways más antiguos aún pueden devolver { "ok": true } para node.event; los clientes deben tratarlo como una RPC reconocida, no como persistencia duradera de presencia.

Alcance de eventos de difusión

Los eventos de difusión WebSocket enviados por el servidor están limitados por alcance para que las sesiones con alcance de emparejamiento o solo de nodo no reciban pasivamente contenido de sesión.

• Tramas de chat, agente y resultado de herramienta (incluidos eventos agent transmitidos y resultados de llamadas a herramientas) requieren al menos operator.read. Las sesiones sin operator.read omiten estas tramas por completo.
• Difusiones plugin.* definidas por Plugins se limitan a operator.write u operator.admin, según cómo las haya registrado el Plugin.
• Eventos de estado y transporte (heartbeat, presence, tick, ciclo de vida de conexión/desconexión, etc.) permanecen sin restricciones para que la salud del transporte siga siendo observable para toda sesión autenticada.
• Familias de eventos de difusión desconocidas se limitan por alcance de forma predeterminada (fallo cerrado) salvo que un manejador registrado las relaje explícitamente.

Cada conexión de cliente mantiene su propio número de secuencia por cliente para que las difusiones conserven el orden monotónico en ese socket incluso cuando distintos clientes vean subconjuntos diferentes del flujo de eventos filtrados por alcance.

Familias comunes de métodos RPC

La superficie WS pública es más amplia que los ejemplos de handshake/autenticación anteriores. Esto no es un volcado generado: hello-ok.features.methods es una lista de descubrimiento conservadora creada a partir de src/gateway/server-methods-list.ts más las exportaciones de métodos de Plugins/canales cargados. Trátala como descubrimiento de funciones, no como una enumeración completa de src/gateway/server-methods/*.ts.

Familias de eventos comunes

• chat: actualizaciones de chat de UI como chat.inject y otros eventos de chat solo de transcripción. En el protocolo v4, las cargas delta llevan deltaText; message sigue siendo la instantánea acumulativa del asistente. Los reemplazos que no son de prefijo establecen replace=true y usan deltaText como texto de reemplazo.
• session.message, session.operation y session.tool: transcripción, operación de sesión en curso y actualizaciones de flujo de eventos para una sesión suscrita.
• sessions.changed: cambió el índice de sesión o los metadatos.
• presence: actualizaciones de instantánea de presencia del sistema.
• tick: evento periódico de keepalive / vivacidad.
• health: actualización de instantánea de salud del gateway.
• heartbeat: actualización del flujo de eventos de Heartbeat.
• cron: evento de cambio de ejecución/trabajo de Cron.
• shutdown: notificación de apagado del gateway.
• node.pair.requested / node.pair.resolved: ciclo de vida de emparejamiento de Node.
• node.invoke.request: difusión de solicitud de invocación de Node.
• device.pair.requested / device.pair.resolved: ciclo de vida de dispositivo emparejado.
• voicewake.changed: cambió la configuración del disparador de palabra de activación.
• exec.approval.requested / exec.approval.resolved: ciclo de vida de aprobación de ejecución.
• plugin.approval.requested / plugin.approval.resolved: ciclo de vida de aprobación de plugin.

Métodos auxiliares de Node

• Los Nodes pueden llamar a skills.bins para obtener la lista actual de ejecutables de Skills para comprobaciones de permiso automático.

RPC del libro mayor de tareas

Los clientes operadores pueden inspeccionar y cancelar registros de tareas en segundo plano del Gateway mediante los RPC del libro mayor de tareas. Estos métodos devuelven resúmenes de tareas saneados, no el estado bruto del runtime.

• tasks.list requiere operator.read.
  • Parámetros: status opcional ("queued", "running", "completed", "failed", "cancelled" o "timed_out") o un arreglo de esos estados, agentId opcional, sessionKey opcional, limit opcional de 1 a 500 y cadena cursor opcional.
  • Resultado: { "tasks": TaskSummary[], "nextCursor"?: string }.
• tasks.get requiere operator.read.
  • Parámetros: { "taskId": string }.
  • Resultado: { "task": TaskSummary }.
  • Los ids de tarea faltantes devuelven la forma de error not-found del Gateway.
• tasks.cancel requiere operator.write.
  • Parámetros: { "taskId": string, "reason"?: string }.
  • Resultado: { "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }.
  • found informa si el libro mayor tenía una tarea coincidente. cancelled informa si el runtime aceptó o registró la cancelación.

TaskSummary incluye id, status y metadatos opcionales como kind, runtime, title, agentId, sessionKey, childSessionKey, ownerKey, runId, taskId, flowId, parentTaskId, sourceId, marcas de tiempo, progreso, resumen terminal y texto de error saneado. agentId identifica al agente que ejecuta la tarea; sessionKey y ownerKey preservan el contexto del solicitante y de control.

Métodos auxiliares de operador

• Los operadores pueden llamar a commands.list (operator.read) para obtener el inventario de comandos en tiempo de ejecución de un agente.
  • agentId es opcional; omítalo para leer el espacio de trabajo del agente predeterminado.
  • scope controla a qué superficie apunta el name principal:
    • text devuelve el token principal del comando de texto sin la / inicial
    • native y la ruta predeterminada both devuelven nombres nativos conscientes del proveedor cuando están disponibles
  • textAliases lleva alias de barra exactos, como /model y /m.
  • nativeName lleva el nombre del comando nativo consciente del proveedor cuando existe uno.
  • provider es opcional y solo afecta la nomenclatura nativa y la disponibilidad de comandos nativos de plugins.
  • includeArgs=false omite de la respuesta los metadatos de argumentos serializados.
• Los operadores pueden llamar a tools.catalog (operator.read) para obtener el catálogo de herramientas en tiempo de ejecución de un agente. La respuesta incluye herramientas agrupadas y metadatos de procedencia:
  • source: core o plugin
  • pluginId: propietario del plugin cuando source="plugin"
  • optional: si una herramienta de plugin es opcional
• Los operadores pueden llamar a tools.effective (operator.read) para obtener el inventario de herramientas efectivo en tiempo de ejecución de una sesión.
  • sessionKey es obligatorio.
  • El Gateway deriva el contexto de tiempo de ejecución confiable desde la sesión en el servidor, en lugar de aceptar autenticación o contexto de entrega suministrados por el llamador.
  • La respuesta es una proyección derivada por el servidor y limitada a la sesión del inventario activo, incluidos core, plugin, canal y herramientas de servidor MCP ya descubiertas.
  • tools.effective es de solo lectura para MCP: puede proyectar un catálogo MCP de sesión activa a través de la política final de herramientas, pero no crea runtimes MCP, no conecta transportes ni emite tools/list. Si no existe un catálogo activo coincidente, la respuesta puede incluir un aviso como mcp-not-yet-connected, mcp-not-yet-listed o mcp-stale-catalog.
  • Las entradas de herramientas efectivas usan source="core", source="plugin", source="channel" o source="mcp".
• Los operadores pueden llamar a tools.invoke (operator.write) para invocar una herramienta disponible mediante la misma ruta de política del Gateway que /tools/invoke.
  • name es obligatorio. args, sessionKey, agentId, confirm e idempotencyKey son opcionales.
  • Si sessionKey y agentId están presentes, el agente resuelto de la sesión debe coincidir con agentId.
  • Los wrappers core solo para propietarios, como cron, gateway y nodes, requieren identidad de propietario/administrador (operator.admin), aunque el método tools.invoke en sí sea operator.write.
  • La respuesta es un sobre orientado al SDK con ok, toolName, output opcional y campos error tipados. Las aprobaciones o rechazos de política devuelven ok:false en la carga útil, en lugar de omitir la canalización de política de herramientas del Gateway.
• Los operadores pueden llamar a skills.status (operator.read) para obtener el inventario visible de skills de un agente.
  • agentId es opcional; omítalo para leer el espacio de trabajo del agente predeterminado.
  • La respuesta incluye elegibilidad, requisitos faltantes, comprobaciones de configuración y opciones de instalación saneadas sin exponer valores secretos sin procesar.
• Los operadores pueden llamar a skills.search y skills.detail (operator.read) para metadatos de descubrimiento de ClawHub.
• Los operadores pueden llamar a skills.upload.begin, skills.upload.chunk y skills.upload.commit (operator.admin) para preparar un archivo privado de skill antes de instalarlo. Esta es una ruta separada de carga administrativa para clientes confiables, no el flujo normal de instalación de skills de ClawHub, y está deshabilitada de forma predeterminada a menos que skills.install.allowUploadedArchives esté habilitado.
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) crea una carga vinculada a ese slug y valor de force.
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) agrega bytes en el desplazamiento decodificado exacto.
  • skills.upload.commit({ uploadId, sha256? }) verifica el tamaño final y SHA-256. Commit solo finaliza la carga; no instala la skill.
  • Los archivos de skills cargados son archivos zip que contienen una raíz SKILL.md. El nombre del directorio interno del archivo nunca selecciona el destino de instalación.
• Los operadores pueden llamar a skills.install (operator.admin) en tres modos:
  • Modo ClawHub: { source: "clawhub", slug, version?, force? } instala una carpeta de skill en el directorio skills/ del espacio de trabajo del agente predeterminado.
  • Modo de carga: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } instala una carga confirmada en el directorio skills/<slug> del espacio de trabajo del agente predeterminado. El slug y el valor de force deben coincidir con la solicitud original skills.upload.begin. Este modo se rechaza a menos que skills.install.allowUploadedArchives esté habilitado. La configuración no afecta las instalaciones de ClawHub.
  • Modo de instalador de Gateway: { name, installId, timeoutMs? } ejecuta una acción declarada metadata.openclaw.install en el host del gateway. Los clientes antiguos aún pueden enviar dangerouslyForceUnsafeInstall; este campo está obsoleto, se acepta solo por compatibilidad de protocolo y se ignora. Use security.installPolicy para decisiones de instalación propiedad del operador.
• Los operadores pueden llamar a skills.update (operator.admin) en dos modos:
  • El modo ClawHub actualiza un slug rastreado o todas las instalaciones ClawHub rastreadas en el espacio de trabajo del agente predeterminado.
  • El modo de configuración aplica parches a valores skills.entries.<skillKey>, como enabled, apiKey y env.

Vistas de models.list

models.list acepta un parámetro opcional view:

• Omitido o "default": comportamiento actual en tiempo de ejecución. Si agents.defaults.models está configurado, la respuesta es el catálogo permitido, incluidos modelos descubiertos dinámicamente para entradas provider/*. De lo contrario, la respuesta es el catálogo completo del Gateway.
• "configured": comportamiento del tamaño de un selector. Si agents.defaults.models está configurado, sigue teniendo prioridad, incluido el descubrimiento con alcance de proveedor para entradas provider/*. Sin una lista de permitidos, la respuesta usa entradas explícitas models.providers.*.models, y recurre al catálogo completo solo cuando no existen filas de modelos configuradas.
• "all": catálogo completo del Gateway, omitiendo agents.defaults.models. Use esto para diagnósticos e interfaces de descubrimiento, no para selectores de modelos normales.

Aprobaciones de exec

• Cuando una solicitud de exec necesita aprobación, el gateway transmite exec.approval.requested.
• Los clientes operadores resuelven llamando a exec.approval.resolve (requiere el alcance operator.approvals).
• Para host=node, exec.approval.request debe incluir systemRunPlan (argv/cwd/rawCommand/metadatos de sesión canónicos). Las solicitudes sin systemRunPlan se rechazan.
• Después de la aprobación, las llamadas reenviadas node.invoke system.run reutilizan ese systemRunPlan canónico como el contexto autorizado de comando/cwd/sesión.
• Si un llamador muta command, rawCommand, cwd, agentId o sessionKey entre la preparación y el reenvío final aprobado de system.run, el gateway rechaza la ejecución en lugar de confiar en la carga útil mutada.

Fallback de entrega del agente

• Las solicitudes agent pueden incluir deliver=true para solicitar entrega saliente.
• bestEffortDeliver=false conserva el comportamiento estricto: los destinos de entrega no resueltos o solo internos devuelven INVALID_REQUEST.
• bestEffortDeliver=true permite recurrir a ejecución solo de sesión cuando no se puede resolver una ruta entregable externa (por ejemplo, sesiones internas/webchat o configuraciones multicanal ambiguas).
• Los resultados finales de agent pueden incluir result.deliveryStatus cuando se solicitó entrega, usando los mismos estados sent, suppressed, partial_failed y failed documentados para openclaw agent --json --deliver.

Versionado

• PROTOCOL_VERSION vive en packages/gateway-protocol/src/version.ts.
• Los clientes envían minProtocol + maxProtocol; el servidor rechaza rangos que no incluyen su protocolo actual. Los clientes y servidores actuales requieren el protocolo v4.
• Los esquemas y modelos se generan a partir de definiciones TypeBox:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

Constantes del cliente

El cliente de referencia en src/gateway/client.ts usa estos valores predeterminados. Los valores son estables en el protocolo v4 y son la base esperada para clientes de terceros.

El servidor anuncia policy.tickIntervalMs, policy.maxPayload y policy.maxBufferedBytes efectivos en hello-ok; los clientes deben respetar esos valores en lugar de los valores predeterminados previos al handshake.

Autenticación

• La autenticación de Gateway con secreto compartido usa connect.params.auth.token o connect.params.auth.password, según el modo de autenticación configurado.
• Los modos que llevan identidad, como Tailscale Serve (gateway.auth.allowTailscale: true) o gateway.auth.mode: "trusted-proxy" no local loopback satisfacen la comprobación de autenticación de conexión desde los encabezados de la solicitud en lugar de connect.params.auth.*.
• La entrada privada gateway.auth.mode: "none" omite por completo la autenticación de conexión con secreto compartido; no expongas ese modo en entradas públicas o no confiables.
• Después del emparejamiento, el Gateway emite un token de dispositivo limitado al rol + ámbitos de la conexión. Se devuelve en hello-ok.auth.deviceToken y el cliente debería persistirlo para conexiones futuras.
• Los clientes deberían persistir el hello-ok.auth.deviceToken principal después de cualquier conexión correcta.
• Reconectar con ese token de dispositivo almacenado también debería reutilizar el conjunto de ámbitos aprobados almacenado para ese token. Esto conserva el acceso de lectura/sondeo/estado ya concedido y evita reducir silenciosamente las reconexiones a un ámbito implícito más estrecho de solo administrador.
• Ensamblado de autenticación de conexión del lado del cliente (selectConnectAuth en src/gateway/client.ts):
  • auth.password es ortogonal y siempre se reenvía cuando está definido.
  • auth.token se completa en orden de prioridad: primero el token compartido explícito, luego un deviceToken explícito y después un token por dispositivo almacenado (indexado por deviceId + role).
  • auth.bootstrapToken se envía solo cuando ninguno de los anteriores resolvió un auth.token. Un token compartido o cualquier token de dispositivo resuelto lo suprime.
  • La promoción automática de un token de dispositivo almacenado en el reintento único AUTH_TOKEN_MISMATCH está limitada a endpoints confiables únicamente: local loopback, o wss:// con un tlsFingerprint fijado. wss:// público sin fijación no cumple los requisitos.
• El bootstrap con código de configuración integrado devuelve el hello-ok.auth.deviceToken del Node principal más un token de operador limitado en hello-ok.auth.deviceTokens para una transferencia móvil confiable. El token de operador incluye operator.talk.secrets para lecturas de configuración nativa de Talk y excluye operator.admin y operator.pairing.
• Mientras un bootstrap con código de configuración no basal espera aprobación, los detalles de PAIRING_REQUIRED incluyen recommendedNextStep: "wait_then_retry", retryable: true y pauseReconnect: false. Los clientes deberían seguir reconectando con el mismo token de bootstrap hasta que se apruebe la solicitud o el token deje de ser válido.
• Persiste hello-ok.auth.deviceTokens solo cuando la conexión usó autenticación de bootstrap en un transporte confiable como wss:// o emparejamiento local/local loopback.
• Si un cliente proporciona un deviceToken explícito o scopes explícitos, ese conjunto de ámbitos solicitado por el llamador sigue siendo autoritativo; los ámbitos en caché solo se reutilizan cuando el cliente reutiliza el token por dispositivo almacenado.
• Los tokens de dispositivo se pueden rotar/revocar mediante device.token.rotate y device.token.revoke (requiere el ámbito operator.pairing). Rotar o revocar un Node u otro rol no operador también requiere operator.admin.
• device.token.rotate devuelve metadatos de rotación. Refleja el token portador de reemplazo solo para llamadas del mismo dispositivo que ya están autenticadas con ese token de dispositivo, para que los clientes de solo token puedan persistir su reemplazo antes de reconectar. Las rotaciones compartidas/de administrador no reflejan el token portador.
• La emisión, rotación y revocación de tokens permanecen limitadas al conjunto de roles aprobado registrado en la entrada de emparejamiento de ese dispositivo; la mutación de tokens no puede ampliar ni apuntar a un rol de dispositivo que la aprobación de emparejamiento nunca concedió.
• Para sesiones con token de dispositivo emparejado, la gestión de dispositivos queda autoacotada salvo que el llamador también tenga operator.admin: los llamadores no administradores solo pueden gestionar el token de operador de la entrada de su propio dispositivo. La gestión de tokens de Node y otros tokens no operadores es solo para administradores, incluso para el propio dispositivo del llamador.
• device.token.rotate y device.token.revoke también comprueban el conjunto de ámbitos del token de operador objetivo frente a los ámbitos de la sesión actual del llamador. Los llamadores no administradores no pueden rotar ni revocar un token de operador más amplio que el que ya tienen.
• Los fallos de autenticación incluyen error.details.code más sugerencias de recuperación:
  • error.details.canRetryWithDeviceToken (booleano)
  • error.details.recommendedNextStep (retry_with_device_token, update_auth_configuration, update_auth_credentials, wait_then_retry, review_auth_configuration)
• Comportamiento del cliente para AUTH_TOKEN_MISMATCH:
  • Los clientes confiables pueden intentar un reintento limitado con un token por dispositivo en caché.
  • Si ese reintento falla, los clientes deberían detener los bucles de reconexión automática y mostrar orientación de acción para el operador.
• AUTH_SCOPE_MISMATCH significa que se reconoció el token de dispositivo, pero no cubre el rol/los ámbitos solicitados. Los clientes no deberían presentarlo como un token incorrecto; pide al operador que vuelva a emparejar o apruebe el contrato de ámbitos más estrecho/amplio.

Identidad de dispositivo + emparejamiento

• Los Nodes deberían incluir una identidad de dispositivo estable (device.id) derivada de una huella de par de claves.
• Los Gateways emiten tokens por dispositivo + rol.
• Se requieren aprobaciones de emparejamiento para nuevos ID de dispositivo salvo que la aprobación automática local esté habilitada.
• La aprobación automática de emparejamiento se centra en conexiones directas por local loopback.
• OpenClaw también tiene una ruta estrecha de autoconexión local al backend/contenedor para flujos de ayudantes confiables con secreto compartido.
• Las conexiones del mismo host por tailnet o LAN siguen tratándose como remotas para el emparejamiento y requieren aprobación.
• Los clientes WS normalmente incluyen identidad de device durante connect (operador + Node). Las únicas excepciones de operador sin dispositivo son rutas de confianza explícitas:
  • gateway.controlUi.allowInsecureAuth=true para compatibilidad HTTP insegura solo en localhost.
  • autenticación correcta de operador en Control UI con gateway.auth.mode: "trusted-proxy".
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (recurso de emergencia, degradación severa de seguridad).
  • RPCs de backend gateway-client por direct-loopback en la ruta reservada de ayudante interno.
• Omitir la identidad de dispositivo tiene consecuencias de ámbito. Cuando una conexión de operador sin dispositivo se permite mediante una ruta de confianza explícita, OpenClaw todavía borra los ámbitos autodeclarados a un conjunto vacío salvo que esa ruta tenga una excepción nombrada de preservación de ámbitos. Los métodos protegidos por ámbito entonces fallan con missing scope.
• gateway.controlUi.dangerouslyDisableDeviceAuth=true es una ruta de preservación de ámbitos de emergencia de Control UI. No concede ámbitos a clientes WebSocket personalizados arbitrarios con forma de backend o CLI.
• La ruta reservada de ayudante de backend gateway-client por direct-loopback preserva ámbitos solo para RPCs internas del plano de control local; los ID de backend personalizados no reciben esta excepción.
• Todas las conexiones deben firmar el nonce connect.challenge proporcionado por el servidor.

Diagnósticos de migración de autenticación de dispositivo

Para clientes heredados que todavía usan el comportamiento de firma previo al desafío, connect ahora devuelve códigos de detalle DEVICE_AUTH_* bajo error.details.code con un error.details.reason estable.

Fallos comunes de migración:

Objetivo de migración:

• Espera siempre a connect.challenge.
• Firma la carga v2 que incluye el nonce del servidor.
• Envía el mismo nonce en connect.params.device.nonce.
• La carga de firma preferida es v3, que vincula platform y deviceFamily además de los campos de dispositivo/cliente/rol/ámbitos/token/nonce.
• Las firmas heredadas v2 siguen aceptándose por compatibilidad, pero la fijación de metadatos de dispositivo emparejado sigue controlando la política de comandos al reconectar.

TLS + fijación

• TLS es compatible con conexiones WS.
• Los clientes pueden fijar opcionalmente la huella del certificado del gateway (consulta la configuración gateway.tls más gateway.remote.tlsFingerprint o la CLI --tls-fingerprint).

Ámbito

Este protocolo expone la API completa del gateway (estado, canales, modelos, chat, agente, sesiones, Nodes, aprobaciones, etc.). La superficie exacta está definida por los esquemas TypeBox en packages/gateway-protocol/src/schema.ts.

Relacionado

• Protocolo de puente
• Runbook de Gateway