Protocolo de Gateway

Documentation Index

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

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

​

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 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 de la trama sin procesar, tokens, cookies ni valores secretos.

​

Handshake (connect)

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

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

{
  "type": "res",
  "id": "…",
  "ok": true,
  "payload": {
    "type": "hello-ok",
    "protocol": 4,
    "server": { "version": "…", "connId": "…" },
    "features": { "methods": ["…"], "events": ["…"] },
    "snapshot": { "…": "…" },
    "auth": {
      "role": "operator",
      "scopes": ["operator.read", "operator.write"]
    },
    "policy": {
      "maxPayload": 26214400,
      "maxBufferedBytes": 52428800,
      "tickIntervalMs": 15000
    }
  }
}

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

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

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

​

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

​

Enmarcado

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

​

Roles + alcances

​

Roles

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

​

Alcances (operador)

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

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

​

Caps/comandos/permisos (nodo)

• caps: categorías de capacidad de alto nivel como camera, canvas, screen, location, voice y talk.
• commands: lista de permitidos de comandos para invoke.
• permissions: conmutadores granulares (p. ej., screen.record, camera.capture).

​

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 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 alive de nodo 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 broadcast

• Tramas de chat, agente y resultados de herramientas (incluidos eventos agent transmitidos y resultados de llamadas de herramientas) requieren al menos operator.read. Las sesiones sin operator.read omiten estas tramas por completo.
• Broadcasts plugin.* definidos por plugins se limitan a operator.write u operator.admin, según cómo los 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 el estado del transporte siga siendo observable para cada sesión autenticada.
• Familias de eventos broadcast desconocidas se limitan por alcance de forma predeterminada (fallo cerrado) salvo que un manejador registrado las relaje explícitamente.

​

Familias comunes de métodos RPC

​

Familias de eventos comunes

• chat: actualizaciones del chat de la interfaz, como chat.inject y otros eventos de chat solo de transcripción.
• session.message y session.tool: actualizaciones de transcripción/flujo de eventos para una sesión suscrita.
• sessions.changed: el índice o los metadatos de sesión cambiaron.
• presence: actualizaciones de instantáneas de presencia del sistema.
• tick: evento periódico de keepalive / 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/tarea de Cron.
• shutdown: notificación de apagado del Gateway.
• node.pair.requested / node.pair.resolved: ciclo de vida de 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 dispositivos emparejados.
• voicewake.changed: la configuración del disparador de palabra de activación cambió.
• 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

• Los nodos pueden llamar a skills.bins para obtener la lista actual de ejecutables de Skills para comprobaciones de autorización automática.

​

RPC del registro 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 cursor de cadena 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 registro tenía una tarea coincidente. cancelled informa si el runtime aceptó o registró la cancelación.

​

Métodos auxiliares de operador

• Los operadores pueden llamar a commands.list (operator.read) para obtener el inventario de comandos del runtime para un agente.
  • agentId es opcional; omítelo para leer el espacio de trabajo predeterminado del agente.
  • 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 más la disponibilidad de comandos nativos de plugin.
  • 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 del 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
• Los operadores pueden llamar a tools.effective (operator.read) para obtener el inventario de herramientas efectivo en runtime para una sesión.
  • sessionKey es obligatorio.
  • El gateway deriva contexto de runtime confiable de la sesión en el servidor en lugar de aceptar contexto de autenticación o entrega suministrado por el llamador.
  • La respuesta tiene alcance de sesión y refleja lo que la conversación activa puede usar ahora mismo, incluidas herramientas de core, plugin y canal.
• 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 tanto sessionKey como agentId están presentes, el agente de la sesión resuelta debe coincidir con agentId.
  • La respuesta es un sobre orientado al SDK con ok, toolName, output opcional y campos error tipados. Los rechazos de aprobación o política devuelven ok:false en la carga útil en lugar de omitir la canalización de políticas 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 predeterminado del agente.
  • 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 Skills antes de instalarlo. Esta es una ruta de carga de administrador separada para clientes de confianza, no el flujo normal de instalación de Skills de ClawHub, y está deshabilitada de forma predeterminada salvo 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 }) 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 Skills 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.
• Los operadores pueden llamar a skills.install (operator.admin) en tres modos:
  • Modo ClawHub: { source: "clawhub", slug, version?, force? } instala una carpeta de Skills en el directorio skills/ del espacio de trabajo predeterminado del agente.
  • Modo de carga: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } instala una carga confirmada en el directorio skills/<slug> del espacio de trabajo predeterminado del agente. El slug y el valor de force deben coincidir con la solicitud original skills.upload.begin. Este modo se rechaza salvo que skills.install.allowUploadedArchives esté habilitado. La configuración no afecta las instalaciones de ClawHub.
  • Modo instalador de Gateway: { name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? } ejecuta una acción declarada metadata.openclaw.install en el host del Gateway.
• 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 predeterminado del agente.
  • El modo de configuración parchea valores de skills.entries.<skillKey> como enabled, apiKey y env.

​

Vistas de models.list

• Omitido o "default": comportamiento actual del runtime. 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 de tamaño adecuado para 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 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. Usa 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 difunde 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/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 agentes

• 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 fallback 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 haya solicitado la entrega, usando los mismos estados sent, suppressed, partial_failed y failed documentados para openclaw agent --json --deliver.

​

Versionado

• PROTOCOL_VERSION vive en src/gateway/protocol/version.ts.
• Los clientes envían minProtocol + maxProtocol; el servidor rechaza rangos que no incluyen su protocolo actual. Los clientes nativos usan un límite inferior v3 para que los clientes v4 aditivos aún puedan alcanzar gateways v3.
• Los esquemas + modelos se generan a partir de definiciones TypeBox:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

​

Constantes de cliente

​

Autenticación

• 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 con identidad, como Tailscale Serve (gateway.auth.allowTailscale: true) o gateway.auth.mode: "trusted-proxy" que no sea 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" para ingreso privado omite por completo la autenticación de conexión con secreto compartido; no expongas ese modo en ingresos públicos o no confiables.
• Después del emparejamiento, el Gateway emite un token de dispositivo limitado al rol y los alcances de la conexión. 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 debe reutilizarse el conjunto de alcances aprobados almacenado para ese token. Esto conserva el acceso de lectura/sondeo/estado que ya se había concedido y evita que las reconexiones se reduzcan silenciosamente a un alcance implícito más estrecho de solo administrador.
• Ensamblaje 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á configurado.
  • auth.token se rellena por orden de prioridad: primero el token compartido explícito, luego un deviceToken explícito y después un token almacenado por dispositivo (con clave 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.
• Las entradas adicionales de hello-ok.auth.deviceTokens son tokens de traspaso de bootstrap. Persístelas solo cuando la conexión haya usado 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 alcances solicitado por el llamador sigue siendo autoritativo; los alcances 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 alcance operator.pairing).
• device.token.rotate devuelve metadatos de rotación. Repite 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 que solo usan token puedan persistir su reemplazo antes de reconectar. Las rotaciones compartidas/de administrador no repiten 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 dirigirse a un rol de dispositivo que la aprobación de emparejamiento nunca concedió.
• Para sesiones de token de dispositivo emparejado, la gestión de dispositivos tiene alcance propio salvo que el llamador también tenga operator.admin: los llamadores que no son administradores solo pueden eliminar/revocar/rotar su propia entrada de dispositivo.
• device.token.rotate y device.token.revoke también comprueban el conjunto de alcances del token de operador de destino contra los alcances 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 además de 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 al operador.
• AUTH_SCOPE_MISMATCH significa que se reconoció el token de dispositivo, pero no cubre el rol/los alcances solicitados. Los clientes no deben presentarlo como un token incorrecto; solicita al operador que vuelva a emparejar o apruebe el contrato de alcance más estrecho/amplio.

​

Identidad del dispositivo + emparejamiento

• Los nodos deben 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 de local loopback.
• OpenClaw también tiene una ruta estrecha de autoconexión local de backend/contenedor para flujos auxiliares 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 device durante connect (operador + nodo). Las únicas excepciones de operador sin dispositivo son rutas de confianza explícitas:
  • gateway.controlUi.allowInsecureAuth=true para compatibilidad con HTTP inseguro solo en localhost.
  • autenticación correcta de operador en Control UI con gateway.auth.mode: "trusted-proxy".
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (ruptura de emergencia, degradación grave de seguridad).
  • RPCs backend directos por loopback de gateway-client autenticados con el token/contraseña compartidos del Gateway.
• Todas las conexiones deben firmar el nonce connect.challenge proporcionado por el servidor.

​

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

• Espera siempre a 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/alcances/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 además de gateway.remote.tlsFingerprint o la CLI --tls-fingerprint).

​

Alcance

​

Relacionado

• Protocolo de puente
• Runbook del Gateway