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 + ámbito durante el handshake.

Transporte

• WebSocket, tramas de texto con cargas útiles 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 diagnósticos activados, las tramas entrantes sobredimensionadas 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 bruto 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 está terminando sidecars de arranque, la solicitud connect puede devolver un error reintentable UNAVAILABLE 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 de handshake.

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

Las URL de superficies de plugins con ámbito pueden expirar. 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 plugins.

Cuando no se emite ningún 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 confiables del mismo proceso (client.id: "gateway-client", client.mode: "backend") pueden omitir device en conexiones directas local 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 con origen de navegador, clientes de nodo y clientes explícitos con token de dispositivo/identidad de dispositivo siguen usando las comprobaciones normales de emparejamiento y ampliación de ámbito.

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

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

El arranque integrado mediante 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 intencionadamente para que el onboarding QR pueda iniciar el bucle de operador móvil y completar la configuración nativa sin conceder ámbitos de mutación de emparejamiento ni operator.admin. Incluye operator.talk.secrets para que el cliente nativo pueda leer la configuración de Talk que necesita después del arranque. El acceso más amplio de emparejamiento y administración requiere un flujo separado aprobado de emparejamiento de operador o token. Los clientes deben persistir hello-ok.auth.deviceTokens solo cuando la conexión usó autenticación de arranque en un transporte confiable como wss:// o emparejamiento local/loopback.

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

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 + ámbitos

Para ver el modelo completo de ámbitos de operador, las comprobaciones en tiempo de aprobación y la semántica de secretos compartidos, consulta Ámbitos de operador.

Roles

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

Ámbitos (operador)

Ámbitos 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 conserva 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 ámbito de operador, pero los prefijos reservados de administración del núcleo (config.*, exec.approvals.*, wizard.*, update.*) siempre se resuelven como operator.admin.

El ámbito de método es solo la primera barrera. 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 ámbito en tiempo de aprobación encima del ámbito base del método:

• solicitudes sin comandos: operator.pairing
• solicitudes con comandos de nodo no exec: 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 reivindicaciones de capacidad en el momento de la conexión:

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

El Gateway trata estas como reivindicaciones 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 UI 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 confiable actualiza sus metadatos de emparejamiento.

Evento alive en segundo plano de Node

Los nodos pueden llamar a node.event con event: "node.presence.alive" para registrar que un nodo emparejado estaba activo durante una activación 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 una enumeración cerrada: background, silent_push, bg_app_refresh, significant_location, manual o connect. Las cadenas de activador desconocidas se normalizan a background en el gateway antes de persistir. El evento es duradero solo para sesiones de dispositivo de nodo autenticadas; las sesiones sin dispositivo o no emparejadas devuelven handled: false.

Los gateways correctos devuelven un resultado estructurado:

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

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

Delimitación de ámbito de eventos de difusión

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

• Tramas de chat, agente y resultados de herramientas (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 están restringidas a operator.write o 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 cada sesión autenticada.
• Familias de eventos de difusión desconocidas están protegidas por ámbito de forma predeterminada (fallo cerrado) salvo que un controlador registrado las relaje explícitamente.

Cada conexión de cliente conserva su propio número de secuencia por cliente para que las difusiones preserven el orden monótono en ese socket incluso cuando distintos clientes ven subconjuntos diferentes filtrados por ámbito del flujo de eventos.

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 conservadora de descubrimiento creada a partir de src/gateway/server-methods-list.ts más las exportaciones de métodos de plugins/canales cargadas. Trátala como descubrimiento de funcionalidades, 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 sin prefijo establecen replace=true y usan deltaText como texto de reemplazo.
• session.message, session.operation y session.tool: actualizaciones de transcripción, operación de sesión en curso y flujo de eventos para una sesión suscrita.
• sessions.changed: cambió el índice de sesiones 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 de 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 del emparejamiento de nodos.
• node.invoke.request: difusión de solicitud de invocación de nodo.
• 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 exec.
• plugin.approval.requested / plugin.approval.resolved: ciclo de vida de aprobación de plugin.

Métodos auxiliares de nodo

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

RPC del registro de tareas

Los clientes operador pueden inspeccionar y cancelar registros de tareas en segundo plano del Gateway mediante los RPC del registro de tareas. Estos métodos devuelven resúmenes saneados de tareas, 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 no encontrado 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 registro 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 conservan 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 para un agente.
  • agentId es opcional; omítelo para leer el espacio de trabajo del agente predeterminado.
  • scope controla a qué superficie apunta el name principal:
    • text devuelve el token de comando de texto principal sin la / inicial
    • native y la ruta predeterminada both devuelven nombres nativos conscientes del proveedor cuando están disponibles
  • textAliases contiene alias exactos con barra, como /model y /m.
  • nativeName contiene el nombre de comando nativo consciente del proveedor cuando existe.
  • provider es opcional y solo afecta la nomenclatura nativa y la disponibilidad de comandos nativos de Plugin.
  • includeArgs=false omite los metadatos de argumentos serializados de la respuesta.
• Los operadores pueden llamar a tools.catalog (operator.read) para obtener el catálogo de herramientas en tiempo de ejecución para 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 para una sesión.
  • sessionKey es obligatorio.
  • El Gateway deriva contexto de ejecución confiable desde la sesión en el servidor en lugar de aceptar contexto de autenticación o entrega proporcionado por el llamador.
  • La respuesta es una proyección derivada por el servidor y delimitada a la sesión del inventario activo, incluidos core, Plugin, canal y herramientas de servidores MCP ya descubiertas.
  • tools.effective es de solo lectura para MCP: puede proyectar un catálogo MCP de sesión ya inicializado 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 ya inicializado 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 a través de la misma ruta de política de Gateway que /tools/invoke.
  • name es obligatorio. args, sessionKey, agentId, confirm e idempotencyKey son opcionales.
  • Si sessionKey y agentId están presentes, el agente de sesión resuelto debe coincidir con agentId.
  • Los envoltorios 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 para un agente.
  • agentId es opcional; omítelo 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 de carga de administrador separada 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 el 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 de 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 instalador de Gateway: { name, installId, timeoutMs? } ejecuta una acción declarada metadata.openclaw.install en el host del Gateway. Los clientes más antiguos aún pueden enviar dangerouslyForceUnsafeInstall; este campo está obsoleto, se acepta solo por compatibilidad de protocolo y se ignora. Usa 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 rastreadas de ClawHub en el espacio de trabajo del agente predeterminado.
  • El modo de configuración parchea valores de 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 con tamaño de selector. Si agents.defaults.models está configurado, aún prevalece, incluido el descubrimiento con ámbito de proveedor para entradas provider/*. Sin una lista de permitidos, la respuesta usa entradas explícitas de models.providers.*.models, recurriendo al catálogo completo solo cuando no existen filas de modelos configuradas.
• "all": catálogo completo del Gateway, omitiendo agents.defaults.models. Úsalo para diagnósticos e interfaces de descubrimiento, no para selectores de modelos normales.

Aprobaciones de exec

• Cuando una solicitud exec necesita aprobación, el Gateway transmite exec.approval.requested.
• Los clientes operadores la resuelven llamando a exec.approval.resolve (requiere el alcance operator.approvals).
• Para host=node, exec.approval.request debe incluir systemRunPlan (argv/cwd/rawCommand canónicos/metadatos de sesión). 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 autoritativo 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.

Respaldo de entrega del agente

• Las solicitudes agent pueden incluir deliver=true para solicitar entrega saliente.
• bestEffortDeliver=false mantiene el comportamiento estricto: los destinos de entrega no resueltos o solo internos devuelven INVALID_REQUEST.
• bestEffortDeliver=true permite recurrir a la 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 incluyan su protocolo actual. Los clientes y servidores actuales requieren el protocolo v4.
• Los esquemas + 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 línea base esperada para clientes de terceros.

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

Auth

• La autenticación del 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" sin local loopback satisfacen la comprobación de autenticación de conexión desde los encabezados de solicitud en lugar de connect.params.auth.*.
• gateway.auth.mode: "none" con entrada privada omite por completo la autenticación de conexión con secreto compartido; no expongas ese modo en una entrada pública o no confiable.
• Después del emparejamiento, el Gateway emite un token de dispositivo limitado al rol de conexión + los ámbitos. Se devuelve en hello-ok.auth.deviceToken y el cliente debe persistirlo para conexiones futuras.
• Los clientes deben persistir el hello-ok.auth.deviceToken principal después de cualquier conexión correcta.
• Al reconectar con ese token de dispositivo almacenado, también se debe reutilizar el conjunto de ámbitos aprobado almacenado para ese token. Esto conserva el acceso de lectura/sondeo/estado que ya se concedió y evita reducir silenciosamente las reconexiones a un ámbito implícito más estrecho solo de 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á establecido.
  • auth.token se rellena por 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 nada de lo anterior 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: loopback, o wss:// con un tlsFingerprint fijado. wss:// público sin fijación no cumple los requisitos.
• El arranque integrado con código de configuración devuelve el hello-ok.auth.deviceToken del nodo principal más un token de operador acotado en hello-ok.auth.deviceTokens para transferencia móvil confiable. El token de operador incluye operator.talk.secrets para lecturas de configuración nativa de Talk, pero excluye ámbitos de mutación de emparejamiento y operator.admin.
• Mientras un arranque con código de configuración no base espera aprobación, los detalles de PAIRING_REQUIRED incluyen recommendedNextStep: "wait_then_retry", retryable: true y pauseReconnect: false. Los clientes deben seguir reconectando con el mismo token de arranque 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 arranque en un transporte confiable como wss:// o emparejamiento por loopback/local.
• 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 pueden rotarse/revocarse mediante device.token.rotate y device.token.revoke (requiere el ámbito operator.pairing). Rotar o revocar un nodo u otro rol que no sea de operador también requiere operator.admin.
• device.token.rotate devuelve metadatos de rotación. Solo refleja el token portador de reemplazo para llamadas del mismo dispositivo que ya están autenticadas con ese token de dispositivo, para que los clientes solo con 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 acotadas 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 de token de dispositivo emparejado, la administración de dispositivos tiene ámbito propio salvo que el llamador también tenga operator.admin: los llamadores que no son administradores solo pueden administrar el token de operador de la entrada de su propio dispositivo. La administración de tokens de nodo y otros que no sean de operador 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 contra los ámbitos de sesión actuales del llamador. Los llamadores que no son administradores no pueden rotar ni revocar un token de operador más amplio que el que ya poseen.
• 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 acotado con un token por dispositivo en caché.
  • Si ese reintento falla, los clientes deben detener los bucles de reconexión automática y mostrar orientación de acción para el operador.
• AUTH_SCOPE_MISMATCH significa que el token de dispositivo fue reconocido, pero no cubre el rol/los ámbitos solicitados. Los clientes no deben presentarlo como un token incorrecto; solicita al operador que vuelva a emparejar o que apruebe el contrato de ámbitos más estrecho/amplio.

Identidad de dispositivo + emparejamiento

• Los nodos deben incluir una identidad de dispositivo estable (device.id) derivada de una huella digital de par de claves.
• Los Gateways emiten tokens por dispositivo + rol.
• Las aprobaciones de emparejamiento son necesarias 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 de local loopback.
• OpenClaw también tiene una ruta estrecha de autoconexión local al backend/contenedor para flujos auxiliares confiables con secreto compartido.
• Las conexiones de tailnet o LAN del mismo host siguen tratándose como remotas para el emparejamiento y requieren aprobación.
• Los clientes WS normalmente incluyen identidad device durante connect (operador + nodo). 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 del operador de la Control UI con gateway.auth.mode: "trusted-proxy".
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (ruptura de emergencia, degradación grave de seguridad).
  • RPCs de backend gateway-client por loopback directo en la ruta auxiliar interna reservada.
• Omitir la identidad de dispositivo tiene consecuencias de ámbito. Cuando se permite una conexión de operador sin dispositivo mediante una ruta de confianza explícita, OpenClaw aun así 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 ruptura de emergencia para la Control UI. No concede ámbitos a clientes WebSocket personalizados arbitrarios con forma de backend o CLI.
• La ruta auxiliar de backend gateway-client reservada por loopback directo 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 aún usan el comportamiento de firma anterior 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 connect.challenge.
• Firma la carga útil v2 que incluye el nonce del servidor.
• Envía el mismo nonce en connect.params.device.nonce.
• La carga útil 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 aún controla la política de comandos al reconectar.

TLS + fijación

• TLS es compatible con conexiones WS.
• Los clientes pueden fijar opcionalmente la huella digital 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, nodos, aprobaciones, etc.). La superficie exacta la definen los esquemas TypeBox en packages/gateway-protocol/src/schema.ts.

Relacionado

• Protocolo de puente
• Runbook del Gateway