Protocolo de Gateway

​

Transporte y enmarcado

• WebSocket, tramas de texto, cargas JSON.
• La primera trama debe ser una solicitud connect.
• Las tramas previas a la conexión tienen un límite de 64 KiB (MAX_PREAUTH_PAYLOAD_BYTES). Después del handshake, siguen hello-ok.policy.maxPayload y hello-ok.policy.maxBufferedBytes. Con los 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. Estos eventos incluyen surface, tamaños en bytes, límites y un código de motivo seguro, nunca cuerpos de mensajes, contenido de adjuntos, bytes de tramas sin procesar, tokens, cookies ni secretos.

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

​

Handshake

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

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

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

​

Ejemplo de conexión de nodo

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

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

​

Roles y alcances

• operator: cliente de plano de control (CLI/UI/automatización).
• node: host de capacidades (camera/screen/canvas/system.run).

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

​

Presencia

• system-presence devuelve entradas indexadas por identidad de dispositivo, incluidos deviceId, roles y scopes, para que las UI puedan mostrar una fila por dispositivo incluso cuando se conecta como operador y como nodo.
• node.list incluye lastSeenAtMs y lastSeenReason opcionales. Los nodos conectados informan la hora de conexión actual con motivo connect; los nodos emparejados también pueden informar presencia en segundo plano durable mediante un evento de nodo de confianza.

​

Evento de nodo vivo en segundo plano

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

​

Alcance de eventos de difusión

• Las tramas de chat, agente y resultados de herramientas (eventos agent transmitidos, eventos de resultados de herramientas) requieren al menos operator.read. Las sesiones sin ese alcance omiten estas tramas por completo.
• Las difusiones plugin.* definidas por Plugins se restringen de forma predeterminada a operator.write u operator.admin; las entradas explícitas como plugin.approval.requested / plugin.approval.resolved usan operator.approvals en su lugar.
• Los eventos de estado/transporte (heartbeat, presence, tick, ciclo de vida de conexión/desconexión) permanecen sin restricciones para que la salud del transporte sea observable para toda sesión autenticada.
• Las familias de eventos de difusión desconocidas se restringen por alcance de forma predeterminada (fail-closed), salvo que un handler registrado las relaje explícitamente.

​

Familias de métodos RPC

​

Familias de eventos comunes

• chat: actualizaciones de chat de la UI como chat.inject y otros eventos de chat solo de transcripción. En el protocolo v4, las cargas útiles 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, 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 sesiones o los metadatos.
• presence: actualizaciones de instantánea de presencia del sistema.
• tick: evento periódico de mantenimiento de conexión/actividad.
• 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 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 exec.
• plugin.approval.requested / plugin.approval.resolved: ciclo de vida de aprobación de Plugin.

​

Métodos auxiliares de Node

​

RPC del libro de auditoría

• Parámetros: agentId, sessionKey o runId exactos opcionales; kind opcional ("agent_run" o "tool_action"); status opcional ("started", "succeeded", "failed", "cancelled", "timed_out", "blocked" o "unknown"); límites inclusivos opcionales after / before en milisegundos Unix; limit opcional de 1 a 500; y cadena cursor opcional de la página anterior.
• Resultado: { "events": AuditEvent[], "nextCursor"?: string }.

​

RPCs del libro de tareas

• 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 tenía una tarea coincidente. cancelled informa si el runtime aceptó o registró la cancelación.

​

Métodos auxiliares de operador

• commands.list (operator.read) obtiene el inventario de comandos de runtime 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 principal de 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 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 de la respuesta los metadatos de argumentos serializados.
• tools.catalog (operator.read) obtiene el catálogo de herramientas de runtime 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
• tools.effective (operator.read) obtiene el inventario de herramientas efectivo en runtime para una sesión.
  • sessionKey es obligatorio.
  • El Gateway deriva el contexto de runtime confiable de la sesión del lado del servidor en lugar de aceptar autenticación o contexto de entrega proporcionados por el llamador.
  • La respuesta es una proyección con alcance de sesión, derivada por el servidor, del inventario activo, incluidas herramientas de core, Plugin, canal y servidores MCP ya descubiertos.
  • tools.effective es de solo lectura para MCP: puede proyectar un catálogo MCP de sesión caliente 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 caliente 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".
• tools.invoke (operator.write) invoca 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 tanto sessionKey como agentId están presentes, el agente de sesión resuelto debe coincidir con agentId.
  • Los wrappers de core solo para propietario, como cron, gateway y nodes, requieren identidad de propietario/admin (operator.admin) aunque 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 negativas por aprobación o política devuelven ok:false en la carga útil en lugar de omitir la canalización de política de herramientas del Gateway.
• skills.status (operator.read) obtiene 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.
• skills.search y skills.detail (operator.read) devuelven metadatos de descubrimiento de ClawHub.
• skills.upload.begin, skills.upload.chunk y skills.upload.commit (operator.admin) preparan un archivo privado de skill antes de instalarlo. Esta es una ruta de carga de admin separada para clientes confiables, no el flujo normal de instalación de skills de ClawHub, y está desactivada de forma predeterminada a menos que skills.install.allowUploadedArchives esté activado.
  • 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 }) anexa 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 skill cargados son archivos zip que contienen una raíz SKILL.md. El nombre de directorio interno del archivo nunca selecciona el destino de instalación.
• skills.install (operator.admin) tiene 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. Se rechaza a menos que skills.install.allowUploadedArchives esté activado; la configuración no afecta a las instalaciones de ClawHub.
  • Modo instalador del 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.
• skills.update (operator.admin) tiene dos modos:
  • El modo ClawHub actualiza un slug rastreado o todas las instalaciones de ClawHub rastreadas en el espacio de trabajo del agente predeterminado.
  • El modo configuración parchea valores skills.entries.<skillKey> como enabled, apiKey y env.

​

Vistas de models.list

• Omitido o "default": si agents.defaults.models está configurado, la respuesta es el catálogo permitido, incluidos los 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.<provider>.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 UIs de diagnóstico/descubrimiento, no para selectores de modelos normales.

​

Aprobaciones de exec

• Cuando una solicitud de exec necesita aprobación, el Gateway difunde exec.approval.requested.
• Los clientes operadores resuelven llamando a exec.approval.resolve (requiere operator.approvals).
• Para host=node, exec.approval.request debe incluir systemRunPlan (argv/cwd/rawCommand/metadatos de sesión canónicos). Las solicitudes que no tengan systemRunPlan se rechazan.
• Después de la aprobación, las llamadas reenviadas node.invoke system.run reutilizan ese systemRunPlan canónico como 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.

​

Fallback de entrega de agente

• Las solicitudes agent pueden incluir deliver=true para solicitar entrega saliente.
• bestEffortDeliver=false (el valor predeterminado) mantiene 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 ninguna 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, MIN_CLIENT_PROTOCOL_VERSION, MIN_NODE_PROTOCOL_VERSION y MIN_PROBE_PROTOCOL_VERSION viven en packages/gateway-protocol/src/version.ts.
• Los clientes envían minProtocol + maxProtocol. Los clientes de operador y de UI deben incluir el protocolo actual en ese rango; los clientes y servidores actuales ejecutan el protocolo v4.
• Los clientes autenticados con role: "node" y client.mode: "node" pueden usar el protocolo de Node N-1 (actualmente v3). Las sondas ligeras de reinicio usan la misma ventana N-1. La autenticación de dispositivos, el emparejamiento, los ámbitos, la política de comandos y las aprobaciones de ejecución no cambian por esta ventana de compatibilidad. Las capacidades y comandos de Node propiedad del Plugin se retienen hasta que el Node se actualiza al protocolo actual porque sus superficies alojadas no forman parte del contrato N-1.
• Los esquemas y modelos se generan desde definiciones de TypeBox:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

​

Constantes de cliente

​

Autenticación

• La autenticación de Gateway con secreto compartido usa connect.params.auth.token o connect.params.auth.password, según el gateway.auth.mode configurado ("none" | "token" | "password" | "trusted-proxy").
• Los modos que portan identidad, como Tailscale Serve (gateway.auth.allowTailscale: true) o gateway.auth.mode: "trusted-proxy" sin loopback, satisfacen la comprobación de autenticación de conexión desde los encabezados de la solicitud en lugar de connect.params.auth.*.
• gateway.auth.mode: "none" de ingreso privado omite por completo la autenticación de conexión con secreto compartido; no expongas ese modo en ingresos públicos/no confiables.
• Tras el emparejamiento, el Gateway emite un token de dispositivo limitado al rol de conexión
  • ámbitos, devuelto en hello-ok.auth.deviceToken. Los clientes deben persistirlo después de cualquier conexión correcta.
• Reconectar con ese token de dispositivo almacenado también debe reutilizar el conjunto de ámbitos aprobados almacenado para ese token. Esto conserva el acceso de lectura/sonda/estado ya concedido y evita reducir silenciosamente las reconexiones a un ámbito implícito más estrecho solo de administrador.
• Ensamblaje de autenticación de conexión del lado del cliente (selectConnectAuth en packages/gateway-client/src/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, luego un token almacenado por dispositivo (indexado por deviceId + role).
  • auth.bootstrapToken se envía solo cuando ninguno de los anteriores resolvió 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 solo a endpoints confiables: loopback, o wss:// con una tlsFingerprint fijada. wss:// público sin fijación no califica.
• El bootstrap integrado con código de configuración devuelve el hello-ok.auth.deviceToken del Node primario 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 bootstrap 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. Sigue reconectando con el mismo token de bootstrap hasta que la solicitud se apruebe 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/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 almacenado por dispositivo.
• Los tokens de dispositivo se pueden rotar/revocar mediante device.token.rotate y device.token.revoke (requiere 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. Hace eco del token portador de reemplazo solo para llamadas del mismo dispositivo ya 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 hacen eco del 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 con token de dispositivo emparejado, la administración de dispositivos se limita a sí misma salvo que el llamador también tenga operator.admin: los llamadores no administradores solo pueden administrar el token de operador de su propia entrada de dispositivo. La administración de tokens de Node y otros no operadores es solo de administrador, 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 de destino frente a los ámbitos de sesión actuales del llamador. Los llamadores no 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: uno de retry_with_device_token, update_auth_configuration, update_auth_credentials, wait_then_retry, review_auth_configuration (packages/gateway-protocol/src/connect-error-details.ts).
• 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, detén los bucles de reconexión automática y muestra la guía 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. No lo presentes como un token incorrecto; pide al operador volver a emparejar o aprobar el contrato de ámbitos más estrecho/más amplio.

​

Identidad de dispositivo y emparejamiento

• Los Nodes deben incluir una identidad de dispositivo estable (device.id) derivada de una huella de keypair.
• Los Gateways emiten tokens por dispositivo + rol.
• Se requieren aprobaciones de emparejamiento para nuevos IDs 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 del mismo host o LAN se siguen tratando como remotas para el emparejamiento y requieren aprobación.
• Los clientes WS normalmente incluyen identidad 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 Control UI de operador con gateway.auth.mode: "trusted-proxy".
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (emergencia, degradación de seguridad severa).
  • RPCs de backend de gateway-client por loopback directo en la ruta auxiliar interna reservada.
• 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 aún limpia los ámbitos autodeclarados a un conjunto vacío salvo que esa ruta tenga una excepción de preservación de ámbitos nombrada. Los métodos protegidos por ámbito fallan entonces 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 de backend personalizados arbitrarios ni con forma de CLI.
• La ruta auxiliar reservada de backend de gateway-client por loopback directo preserva ámbitos solo para RPCs internas de plano de control local; los IDs 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 dispositivos

• 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 (buildDeviceAuthPayloadV3 en packages/gateway-client/src/device-auth.ts), que vincula platform y deviceFamily, además de los campos de dispositivo/cliente/rol/alcances/token/nonce.
• Las firmas heredadas v2 siguen aceptándose por compatibilidad, pero la fijación de metadatos de dispositivos emparejados sigue controlando la política de comandos al reconectar.

​

TLS y fijación

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

​

Alcance

​

Relacionado

• Protocolo de puente
• Runbook del Gateway