Protocolo del Gateway

El protocolo WS del Gateway es el único plano de control y transporte de nodos de OpenClaw. Los clientes de operador y de nodo (CLI, interfaz web, aplicación para macOS, nodos iOS/Android, nodos sin interfaz gráfica) se conectan mediante WebSocket y declaran un rol y un ámbito durante el protocolo de enlace.

Transporte y entramado

• WebSocket, tramas de texto, 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 (MAX_PREAUTH_PAYLOAD_BYTES). Tras el protocolo de enlace, se siguen hello-ok.policy.maxPayload y hello-ok.policy.maxBufferedBytes. Con los diagnósticos habilitados, las tramas entrantes que superan el tamaño permitido y los búferes de salida 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 incluyen cuerpos de mensajes, contenido de archivos adjuntos, bytes sin procesar de las tramas, tokens, cookies ni secretos.

Formas de las tramas:

• 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 (consulte el esquema).

Protocolo de enlace

El Gateway envía un desafío previo a la conexión:

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

El cliente responde con connect:

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

El Gateway responde con hello-ok:

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

server, features, snapshot, policy y auth son obligatorios para HelloOkSchema (packages/gateway-protocol/src/schema/frames.ts). auth informa del rol y los ámbitos negociados incluso cuando no se emite ningún token de dispositivo (forma anterior). pluginSurfaceUrls es opcional y asigna nombres de superficies de plugins (por ejemplo, canvas) a URL alojadas con ámbito; puede caducar, por lo que los nodos llaman a node.pluginSurface.refresh con { "surface": "canvas" } para obtener una entrada nueva. La ruta obsoleta canvasHostUrl / canvasCapability / node.canvas.capability.refresh no es compatible; utilice superficies de plugins.

Mientras el Gateway aún termina de iniciar los procesos auxiliares, connect puede devolver un error reintentable UNAVAILABLE con details.reason: "startup-sidecars" y retryAfterMs. Vuelva a intentarlo dentro del presupuesto de conexión en lugar de tratarlo como un fallo terminal del protocolo de enlace.

Cuando se emite un token de dispositivo, hello-ok.auth lo añade:

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

El arranque integrado mediante QR/código de configuración es una ruta de transferencia móvil. Una conexión correcta con un código de configuración de referencia devuelve un token de nodo principal y un token de operador limitado:

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

Esta transferencia de operador está limitada deliberadamente: es suficiente para iniciar el bucle del operador móvil y la configuración nativa, incluido operator.talk.secrets para las lecturas de configuración de Talk, pero sin ámbitos para modificar emparejamientos ni operator.admin. Un acceso más amplio de emparejamiento o administración requiere un flujo independiente de emparejamiento aprobado o de tokens. Conserve hello-ok.auth.deviceTokens únicamente cuando la autenticación de arranque se haya ejecutado mediante un transporte de confianza (wss:// o emparejamiento local/de bucle invertido).

Los clientes de backend de confianza que se ejecutan en el mismo proceso (client.id: "gateway-client", client.mode: "backend") pueden omitir device en conexiones directas de bucle invertido cuando se autentican con el token o la contraseña compartidos del Gateway. Esta ruta está reservada para RPC internos del plano de control (por ejemplo, actualizaciones de sesiones de subagentes) y evita que las referencias obsoletas de emparejamiento de la CLI o del dispositivo bloqueen el trabajo local del backend. Los clientes remotos, con origen en el navegador, de nodo y con token o identidad de dispositivo explícitos siguen las comprobaciones normales de emparejamiento y ampliación de ámbitos.

Rol de trabajador y protocolo cerrado

Los trabajadores en la nube utilizan una entrada de bucle invertido dedicada mediante el túnel SSH propiedad del Gateway y anclado a la clave del host. Solo acepta la identidad del trabajador y nunca distribuye autenticación general, eventos de nodo, RPC de operador ni métodos de plugins. Un connect estricto verifica una credencial de corta duración, almacenada como hash y vinculada al entorno, al hash del paquete, a la época del propietario, a la versión del conjunto de RPC, a la caducidad y a una sesión anulable; además, comprueba por separado la versión y el conjunto de características actuales. Si se realiza correctamente, devuelve un worker-hello-ok mínimo; la negociación de características es independiente de la versión general del protocolo. Las tramas se mantienen por debajo de 64 KiB, excepto una trama worker.inference.start negociada, que puede tener hasta 25 MiB. La lista cerrada de elementos permitidos contiene worker.heartbeat, worker.transcript.commit, worker.live-event, worker.inference.start y worker.inference.cancel.

Las confirmaciones de transcripciones utilizan delimitación por época del propietario, una vinculación de sesión propiedad del Gateway, comparación e intercambio de la hoja base y repetición duradera de secuencias; el Gateway genera los identificadores de las entradas y sus elementos principales mediante el escritor de sesiones normal. La propiedad y la caducidad se vuelven a comprobar en cada RPC.

Capacidades del cliente

Los clientes de operador pueden anunciar capacidades opcionales en connect.params.caps:

• tool-events: acepta eventos estructurados del ciclo de vida de las herramientas.
• inline-widgets: puede representar resultados de herramientas de widgets integrados alojados.

Las capacidades del cliente describen al cliente conectado, no la autorización. Las herramientas del agente pueden declarar capacidades obligatorias; el Gateway omite esas herramientas salvo que todos los requisitos estén presentes en caps del cliente de origen. Las ejecuciones originadas en canales no tienen capacidades de cliente del Gateway, por lo que las herramientas restringidas por capacidades no están disponibles aunque la política de herramientas las permita explícitamente.

Ejemplo de conexión de un 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": "…"    }  }}

Los nodos declaran afirmaciones de capacidades al conectarse:

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

El Gateway los trata como afirmaciones y aplica listas de elementos permitidos en el servidor.

Roles y ámbitos

Para consultar el modelo completo de ámbitos de operador, las comprobaciones durante la aprobación y la semántica de los secretos compartidos, consulte Ámbitos de operador.

Roles:

• operator: cliente del plano de control (CLI/interfaz de usuario/automatización).
• node: host de capacidades (cámara/pantalla/lienzo/system.run).
• worker: host de ejecución en la nube en el protocolo de trabajador dedicado y cerrado.

Ámbitos de operador (src/gateway/operator-scopes.ts), el conjunto cerrado completo:

• 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, se lee 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 censurada.

Los métodos RPC del Gateway registrados por plugins pueden solicitar su propio ámbito de operador, pero estos prefijos reservados del núcleo siempre se resuelven como operator.admin (src/shared/gateway-method-policy.ts): config.*, exec.approvals.*, wizard.*, update.*.

El ámbito del método es solo el primer control. Algunos comandos con barra a los que se accede mediante chat.send aplican comprobaciones más estrictas en el nivel del comando: las escrituras persistentes /config set y /config unset requieren operator.admin incluso para clientes del Gateway que ya poseen un ámbito de operador inferior.

node.pair.approve tiene una comprobación de ámbito adicional durante la aprobación, además del ámbito base del método (operator.pairing), en función de los commands declarados por la solicitud pendiente (src/infra/node-pairing-authz.ts):

Capacidades/comandos/permisos (nodo)

Los nodos declaran afirmaciones de capacidades al conectarse:

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

El Gateway los trata como afirmaciones y aplica listas de elementos permitidos en el servidor. Los nodos conectados pueden publicar descriptores opcionales de herramientas de plugins o MCP visibles para el agente mediante node.pluginTools.update tras una conexión o reconexión correcta. Los hosts de nodos sin interfaz gráfica se reinician para aplicar cambios declarativos en el inventario de MCP. Este método de actualización es la única ruta de publicación; los descriptores de herramientas de plugins no se aceptan en los parámetros de connect. Cada descriptor debe utilizar un name de herramienta seguro para el proveedor y nombrar un command de la lista actual de comandos permitidos del nodo. El Gateway confía en los metadatos de los descriptores del nodo emparejado, filtra los descriptores ajenos a la superficie de comandos aprobada, los elimina cuando el nodo se desconecta y rechaza los intentos de los operadores de modificar el catálogo de otro nodo. Establezca gateway.nodes.pluginTools.enabled: false para ignorar los descriptores publicados por nodos.

Los hosts de Node conectados publican su catálogo completo de reemplazo de Skills mediante node.skills.update. Este método de rol de Node es la única vía de publicación de Skills de Node; no se aceptan Skills en los parámetros de connect. Cada descriptor contiene un nombre seguro, una descripción y contenido SKILL.md acotado. El Gateway analiza ese contenido con el cargador normal de Skills, lo incluye en las instantáneas de Skills del agente mientras el Node está conectado y lo elimina cuando se desconecta. Establezca gateway.nodes.skills.enabled: false para ignorar las Skills publicadas por el Node.

Presencia

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

Los Nodes nativos de macOS también pueden enviar eventos node.presence.activity autenticados con un tiempo de inactividad de entrada acotado. El Gateway deriva las marcas de tiempo de actividad según su propio reloj, expone el Mac conectado más reciente mediante node.list y node.describe, y transmite las actualizaciones de node.presence a los clientes con ámbito de lectura. Consulte Presencia del ordenador activo para conocer el comportamiento de selección, privacidad, contexto del modelo y enrutamiento de notificaciones.

Evento de actividad en segundo plano del Node

Los Nodes llaman a node.event con event: "node.presence.alive" para registrar que un Node emparejado estuvo 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, connect. Los valores desconocidos se normalizan a background (src/shared/node-presence.ts). El evento solo se conserva para sesiones autenticadas de dispositivos Node; las sesiones sin dispositivo o sin emparejar devuelven handled: false.

Los Gateways que procesan la solicitud correctamente devuelven un resultado estructurado:

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

Los Gateways antiguos pueden devolver únicamente { "ok": true } para node.event; considérelo una RPC confirmada, no una persistencia duradera de presencia.

Ámbito de los eventos de transmisión

Los eventos de transmisión enviados por el servidor se restringen por ámbito para que las sesiones con ámbito de emparejamiento o exclusivas de Node no reciban pasivamente contenido de sesión (src/gateway/server-broadcast.ts):

• Los marcos de chat, agente y resultados de herramientas (eventos agent transmitidos, eventos de resultados de herramientas) requieren al menos operator.read. Las sesiones que no lo tengan omiten estos marcos por completo.
• Las transmisiones plugin.* definidas por Plugins se restringen de forma predeterminada a operator.write o operator.admin; las entradas explícitas como plugin.approval.requested / plugin.approval.resolved utilizan 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 todas las sesiones autenticadas puedan observar el estado del transporte.
• Las familias de eventos de transmisión desconocidas se restringen por ámbito de forma predeterminada (cierre seguro) salvo que un controlador registrado las flexibilice explícitamente.

Cada conexión de cliente mantiene su propio número de secuencia por cliente, por lo que las transmisiones conservan un orden monótonamente creciente en ese socket, incluso cuando distintos clientes ven subconjuntos diferentes del flujo de eventos filtrados por ámbito.

Familias de métodos RPC

hello-ok.features.methods es una lista de detección conservadora creada a partir de src/gateway/server-methods-list.ts junto con las exportaciones de métodos de Plugins/canales cargados; no es un volcado generado de todos los métodos, y algunos métodos (por ejemplo, push.test, web.login.start, web.login.wait, sessions.usage) se excluyen deliberadamente de la detección aunque sean métodos reales que se pueden invocar. Considérela un mecanismo de detección de funciones, no una enumeración completa de src/gateway/server-methods/*.ts.

Familias de eventos comunes

• chat: actualizaciones del chat de la UI, como chat.inject y otros eventos de chat exclusivos de la transcripción. En el protocolo v4, las cargas útiles delta contienen deltaText; message sigue siendo la instantánea acumulativa del asistente. Los reemplazos que no son prefijos establecen replace=true y usan deltaText como texto de reemplazo.
• session.message, session.operation, session.tool: actualizaciones de la transcripción, de la operación de sesión en curso y del flujo de eventos de una sesión suscrita.
• session.approval: estado depurado de aprobaciones pendientes y terminales para un suscriptor de sesión exacta que haya aceptado explícitamente. Las aprobaciones secundarias usan la audiencia persistida del antecesor; los eventos nunca modifican las transcripciones ni activan agentes.
• sessions.changed: el índice o los metadatos de la sesión han cambiado.
• presence: actualizaciones de la instantánea de presencia del sistema.
• tick: evento periódico de mantenimiento de conexión/actividad.
• health: actualización de la instantánea de estado del Gateway.
• heartbeat: actualización del flujo de eventos de Heartbeat.
• cron: evento de cambio de una ejecución o tarea de Cron.
• shutdown: notificación de cierre del Gateway.
• node.pair.requested / node.pair.resolved: ciclo de vida del emparejamiento de nodos.
• node.invoke.request: difusión de una solicitud de invocación de nodo.
• device.pair.requested / device.pair.resolved: ciclo de vida de los dispositivos emparejados.
• voicewake.changed: ha cambiado la configuración del activador por palabra de activación.
• exec.approval.requested / exec.approval.resolved: ciclo de vida de la aprobación de ejecución.
• plugin.approval.requested / plugin.approval.resolved: ciclo de vida de la aprobación del Plugin.

Métodos auxiliares de los nodos

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

RPC del registro de auditoría

audit.activity.list proporciona a los clientes de operador una vista estable, ordenada de más reciente a más antigua, de los metadatos del ciclo de vida de ejecuciones de agentes, acciones de herramientas y mensajes con registro opcional. Requiere operator.read. Las consultas excluyen los registros con más de 30 días de antigüedad y el registro SQLite compartido está limitado a 100,000 registros. Las filas caducadas se eliminan durante el inicio del Gateway, el mantenimiento horario y las escrituras posteriores. Consulte Historial de auditoría para conocer el modelo de datos y la semántica de privacidad.

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

La unión de resultados V1 con nombre tiene esquemas separados para ejecuciones de agentes, acciones de herramientas, mensajes entrantes y mensajes salientes. El discriminador eventType es, respectivamente, agent_run, tool_action, inbound_message o outbound_message; kind y el direction del mensaje siguen disponibles para filtrar y mostrar. Cada evento tiene un schemaVersion: 1 entero. Las referencias de identidad de mensajes usan el formato exacto hmac-sha256:v1:<32 hex key id>:<64 hex digest>; un identificador de actor remitente del canal usa el mismo formato.

Todas las variantes requieren eventType, schemaVersion, eventId, sequence, sourceSequence, occurredAt, kind, action, status, actor y redaction. Los campos de las variantes son:

Las enumeraciones cerradas de mensajes son:

• conversationKind: direct, group, channel o unknown.
• outcome entrante: completed, skipped o failed; reasonCode opcional: duplicate, reply_operation_active, reply_operation_aborted, fast_abort, plugin_bound_handled, plugin_bound_unavailable, plugin_bound_declined, plugin_bound_error, before_dispatch_handled, acp_dispatch_completed, acp_dispatch_failed, acp_dispatch_empty o acp_dispatch_aborted.
• outcome saliente: sent, suppressed, failed o unknown; reasonCode opcional: cancelled_by_message_sending_hook, cancelled_by_reply_payload_sending_hook, empty_after_message_sending_hook, empty_after_reply_payload_sending_hook o no_visible_payload. Un adaptador que no devuelve ninguna identidad de plataforma es unknown, porque no puede descartarse el efecto secundario externo.
• deliveryKind: text, media o other; failureStage: platform_send, queue o unknown.

Los campos terminales están correlacionados, no son opcionales de forma independiente:

Cada evento de actividad incluye un identificador de evento estable, una secuencia monotónica del registro, una secuencia del evento de origen, una marca de tiempo, un actor, una acción, un estado, un schemaVersion: 1 entero y redaction: "metadata_only". Los registros de ejecuciones y herramientas requieren la procedencia del agente y de la ejecución, y pueden incluir la procedencia de la sesión. Los registros de mensajes pueden incluir identificadores del agente y de la ejecución, pero intencionadamente nunca incluyen sessionKey ni sessionId; por tanto, el filtro de consulta sessionKey se aplica solo a las filas de ejecuciones y herramientas. Los eventos de herramientas pueden incluir el identificador de llamada a la herramienta y el nombre de la herramienta.

Los registros de mensajes usan message.inbound.processed o message.outbound.finished y añaden la dirección, el canal, el tipo de conversación, el resultado normalizado y, opcionalmente, el tipo de entrega, la etapa del fallo, la duración, el recuento de resultados, el código de motivo y seudónimos de cuenta, conversación, mensaje y destino con clave local de la instalación. Estos seudónimos facilitan la correlación, pero no constituyen anonimización: la base de datos de estado contiene su clave, mientras que las exportaciones de RPC y CLI no la incluyen. El registro no almacena prompts, cuerpos de mensajes, argumentos de herramientas, resultados de herramientas, salida de comandos ni texto de error sin procesar. Los valores sessionKey de ejecuciones/herramientas siguen siendo metadatos de correlación sin procesar y pueden contener identificadores de cuentas o pares de la plataforma; los registros de mensajes omiten las claves de sesión.

En las filas entrantes, durationMs mide el procesamiento central hasta su estado terminal y resultCount cuenta las cargas útiles finalizadas en cola de herramientas, bloqueos y respuestas. En las filas salientes, durationMs abarca desde la asunción de responsabilidad de la entrega hasta la confirmación, la cola de mensajes no entregados o la reconciliación (incluido el tiempo de espera en cola), y resultCount cuenta los envíos físicos identificados a la plataforma. deliveryKind, cuando está presente, describe la carga útil efectiva después de los hooks y el renderizado; las filas suprimidas o con ambigüedad por bloqueo inesperado lo omiten.

La cobertura actual de mensajes incluye los mensajes entrantes aceptados que llegan al procesamiento central, incluidos los resultados duplicados/terminales del núcleo. La cobertura saliente escribe una fila terminal por cada carga útil de respuesta lógica original que llega a la entrega duradera compartida; la fragmentación y la distribución del adaptador se agregan en resultCount. Los envíos reintentables o ambiguos en cola solo se registran después de la confirmación, la cola de mensajes no entregados o la reconciliación. Las rutas locales del Plugin y de envío directo que eluden esos límites compartidos aún no están cubiertas. La cola acotada de procesos de trabajo funciona según el mejor esfuerzo y puede descartar registros en caso de fallo o saturación, por lo que esta superficie no es un archivo de cumplimiento sin pérdidas.

El registro está activado de forma predeterminada y se controla mediante audit.enabled. El registro de mensajes se controla por separado mediante audit.messages y su valor predeterminado es "off". Cuando el registro está desactivado, audit.activity.list continúa sirviendo los registros escritos anteriormente hasta que caducan.

Los esquemas publicados de solicitud, resultado y AuditEvent de audit.list permanecen sin cambios y solo devuelven registros de ejecuciones de agentes y acciones de herramientas. Los nuevos clientes de operador deben llamar a audit.activity.list cuando el Gateway lo anuncie. Los Gateways anteriores pueden devolver unknown method: audit.activity.list o, debido a que en las versiones publicadas la autorización precedía a la búsqueda del método, missing scope: operator.admin ante una solicitud con ámbito de lectura. Trate este último como ausencia del método solo cuando el método no se haya anunciado. Un cliente puede volver a intentar audit.list solo cuando sus filtros no requieran compatibilidad con el tipo, la dirección o el canal del mensaje.

Use openclaw audit para consultas de texto y exportaciones JSON acotadas.

RPC del registro de tareas

Los clientes de operador inspeccionan y cancelan los registros de tareas en segundo plano del Gateway mediante los RPC del registro de tareas (packages/gateway-protocol/src/schema/tasks.ts). Estos devuelven resúmenes depurados de las tareas, no el estado de ejecución sin procesar.

• tasks.list requiere operator.read.
  • Parámetros: status opcional ("queued", "running", "completed", "failed", "cancelled" o "timed_out") o una matriz de esos estados, agentId opcional, sessionKey opcional, limit opcional de 1 a 500 y la cadena opcional cursor.
  • Resultado: { "tasks": TaskSummary[], "nextCursor"?: string }.
• tasks.get requiere operator.read.
  • Parámetros: { "taskId": string }.
  • Resultado: { "task": TaskSummary }.
  • Los identificadores de tarea inexistentes devuelven el formato de error de elemento 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 indica si el registro contenía una tarea coincidente. cancelled indica si el entorno de ejecución aceptó o registró la cancelación.

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

Métodos auxiliares para operadores

• commands.list (operator.read) obtiene el inventario de comandos del entorno de ejecución para un agente.
  • agentId es opcional; omítalo para leer el espacio de trabajo predeterminado del agente.
  • scope controla a qué superficie se dirige el name principal: text devuelve el token principal del comando de texto sin el / inicial; native y la ruta predeterminada both devuelven nombres nativos adaptados al proveedor cuando están disponibles.
  • textAliases contiene alias exactos con barra diagonal, como /model y /m.
  • nativeName contiene el nombre del comando nativo adaptado al proveedor cuando existe.
  • provider es opcional y solo afecta a la nomenclatura nativa y a la disponibilidad de comandos nativos de plugins.
  • includeArgs=false omite de la respuesta los metadatos serializados de argumentos.
• tools.catalog (operator.read) obtiene el catálogo de herramientas del entorno de ejecución para un agente. La respuesta incluye herramientas agrupadas y metadatos de procedencia:
  • source: core o plugin
  • pluginId: plugin propietario cuando source="plugin"
  • optional: indica si una herramienta de plugin es opcional
• tools.effective (operator.read) obtiene el inventario efectivo de herramientas del entorno de ejecución para una sesión.
  • sessionKey es obligatorio.
  • El Gateway deriva del lado del servidor el contexto fiable del entorno de ejecución a partir de la sesión, en lugar de aceptar un contexto de autenticación o entrega suministrado por el llamador.
  • La respuesta es una proyección derivada por el servidor y limitada a la sesión del inventario activo, incluidas las herramientas del núcleo, de plugins, de canales y de servidores MCP ya detectadas.
  • tools.effective es de solo lectura para MCP: puede proyectar un catálogo MCP de una sesión activa mediante la política final de herramientas, pero no crea entornos de ejecución MCP, 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".
• tools.invoke (operator.write) invoca una herramienta disponible mediante la misma ruta de políticas del Gateway que /tools/invoke.
  • name es obligatorio. args, sessionKey, agentId, confirm y idempotencyKey son opcionales.
  • Si están presentes tanto sessionKey como agentId, el agente de la sesión resuelta debe coincidir con agentId.
  • Los envoltorios del núcleo exclusivos del propietario, como cron, gateway y nodes, requieren una identidad de propietario/administrador (operator.admin), aunque tools.invoke sea operator.write.
  • La respuesta es un contenedor orientado al SDK con ok, toolName, el campo opcional output y campos error tipados. Los rechazos de aprobación o de políticas devuelven ok:false en la carga útil, en lugar de eludir el flujo de políticas de herramientas del Gateway.
• skills.status (operator.read) obtiene el inventario visible de Skills para un agente.
  • agentId es opcional; omítalo para leer el espacio de trabajo predeterminado del agente.
  • La respuesta incluye la idoneidad, los requisitos que faltan, las comprobaciones de configuración y opciones de instalación depuradas sin exponer valores de secretos sin procesar.
• skills.search y skills.detail (operator.read) devuelven metadatos de detección de ClawHub.
• skills.upload.begin, skills.upload.chunk y skills.upload.commit (operator.admin) preparan un archivo privado de Skills antes de instalarlo. Esta es una ruta de carga administrativa independiente para clientes de confianza, no el flujo normal de instalación de Skills de ClawHub, y está desactivada de forma predeterminada salvo 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 imposición.
  • 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. La confirmación 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.
• 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 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 imposición deben coincidir con la solicitud skills.upload.begin original. Se rechaza salvo que skills.install.allowUploadedArchives esté activado; la configuración no afecta a las instalaciones de ClawHub.
  • Modo de instalador del Gateway: { name, installId, timeoutMs? } ejecuta una acción metadata.openclaw.install declarada en el host del Gateway. Los clientes antiguos aún pueden enviar dangerouslyForceUnsafeInstall; este campo está obsoleto, se acepta únicamente por compatibilidad con el protocolo y se ignora. Use security.installPolicy para decisiones de instalación a cargo del operador.
• skills.update (operator.admin) tiene dos modos:
  • El modo ClawHub actualiza un slug registrado o todas las instalaciones de ClawHub registradas en el espacio de trabajo predeterminado del agente.
  • El modo de configuración modifica valores de skills.entries.<skillKey> como enabled, apiKey y env.

Vistas de models.list

models.list acepta un parámetro view opcional (src/agents/model-catalog-visibility.ts):

• Omitido o "default": si agents.defaults.models está configurado, la respuesta es el catálogo permitido, incluidos los modelos detectados dinámicamente para las entradas provider/*. De lo contrario, la respuesta es el catálogo completo del Gateway.
• "configured": comportamiento con dimensiones de selector. Si agents.defaults.models está configurado, sigue teniendo prioridad, incluida la detección limitada al proveedor para las entradas provider/*. Sin una lista de permitidos, la respuesta usa entradas models.providers.<provider>.models explícitas y recurre al catálogo completo solo cuando no existen filas de modelos configuradas.
• "provider-config": inventario models.providers.*.models definido por la fuente, independiente de las listas de permitidos del selector. Las filas incluyen capacidades públicas de los modelos y disponibilidad según la ruta, pero omiten los puntos de conexión del proveedor, el material de autenticación y la configuración de solicitudes del entorno de ejecución.
• "all": catálogo completo del Gateway, que omite agents.defaults.models. Úselo para interfaces de diagnóstico/detección, no para selectores de modelos normales.

Aprobaciones de ejecución

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

Alternativa de entrega del agente

• Las solicitudes agent pueden incluir deliver=true para solicitar la 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 la ejecución solo en la sesión cuando no se puede resolver ninguna ruta externa de entrega (por ejemplo, sesiones internas/de chat web o configuraciones ambiguas con varios canales).
• Los resultados agent finales pueden incluir result.deliveryStatus cuando se solicitó la entrega, usando los mismos estados sent, suppressed, partial_failed y failed documentados para openclaw agent --json --deliver.

Control de versiones

• PROTOCOL_VERSION, MIN_CLIENT_PROTOCOL_VERSION, MIN_NODE_PROTOCOL_VERSION y MIN_PROBE_PROTOCOL_VERSION residen en packages/gateway-protocol/src/version.ts.
• Los clientes envían minProtocol + maxProtocol. Los clientes operadores y de interfaz deben incluir el protocolo actual en ese intervalo; los clientes y servidores actuales usan 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 el mismo intervalo N-1. La autenticación de dispositivos, el emparejamiento, los ámbitos, la política de comandos y las aprobaciones de ejecución no cambian debido a esta ventana de compatibilidad. Las capacidades y los comandos de Node pertenecientes a plugins se omiten 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 a partir de definiciones de TypeBox:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

Constantes del cliente

La implementación de referencia del cliente reside en packages/gateway-client/src/ (OpenClaw la encapsula mediante la delgada fachada src/gateway/client.ts). Estos valores predeterminados son estables en todo el protocolo v4 y constituyen la referencia 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 anteriores al protocolo de enlace.

El cliente de referencia permite que las solicitudes finitas controlen el plazo configurado cuando cada solicitud pendiente tiene uno. Una solicitud expectFinal sin un timeoutMs finito, cualquier solicitud con timeoutMs: null o una combinación de solicitudes finitas y sin límite mantiene activo el mecanismo de vigilancia de ticks. Si no se reciben eventos ni respuestas durante un período superior al umbral de tiempo de espera de tick, el cliente cierra el socket con el código 4000, rechaza todas las solicitudes pendientes y se vuelve a conectar. No repite las solicitudes rechazadas después de volver a conectarse.

Autenticación

• La autenticación del Gateway mediante secreto compartido utiliza connect.params.auth.token o connect.params.auth.password, según el gateway.auth.mode configurado ("none" | "token" | "password" | "trusted-proxy").
• Los modos que contienen identidad, como Tailscale Serve (gateway.auth.allowTailscale: true) o gateway.auth.mode: "trusted-proxy" que no sea de bucle invertido, satisfacen la comprobación de autenticación de conexión mediante los encabezados de la solicitud en lugar de connect.params.auth.*.
• El gateway.auth.mode: "none" de ingreso privado omite por completo la autenticación de conexión mediante secreto compartido; no se debe exponer ese modo en ingresos públicos o no fiables.
• Tras el emparejamiento, el Gateway emite un token de dispositivo limitado al rol y los ámbitos de la conexión, devuelto en hello-ok.auth.deviceToken. Los clientes deben conservarlo después de cualquier conexión correcta.
• Al volver a conectarse con ese token de dispositivo almacenado, también se debe reutilizar el conjunto de ámbitos aprobados almacenado para dicho token. Esto conserva el acceso de lectura, sondeo y estado ya concedido y evita que las reconexiones se reduzcan silenciosamente a un ámbito implícito más restringido, exclusivo de administración.
• Composición de la autenticación de conexión del lado del cliente (selectConnectAuth en packages/gateway-client/src/client.ts):
  • auth.password es independiente y siempre se reenvía cuando está establecido.
  • auth.token se rellena por orden de prioridad: primero el token compartido explícito, después un deviceToken explícito y, por último, un token almacenado por dispositivo (indexado por deviceId + role).
  • auth.bootstrapToken solo se envía cuando ninguna de las opciones anteriores ha resuelto auth.token. Un token compartido o cualquier token de dispositivo resuelto lo suprime.
  • La promoción automática de un token de dispositivo almacenado durante el reintento único de AUTH_TOKEN_MISMATCH se limita exclusivamente a puntos de conexión fiables: bucle invertido o wss:// con un tlsFingerprint fijado. Un wss:// público sin fijación no cumple los requisitos.
• El arranque integrado mediante código de configuración devuelve el hello-ok.auth.deviceToken del nodo principal y un token de operador limitado en hello-ok.auth.deviceTokens para la transferencia móvil fiable. El token de operador incluye operator.talk.secrets para las lecturas de configuración nativas de Talk, pero excluye los ámbitos de modificación del emparejamiento y operator.admin.
• Mientras un arranque mediante código de configuración que no sea de referencia espera la aprobación, los detalles de PAIRING_REQUIRED incluyen recommendedNextStep: "wait_then_retry", retryable: true y pauseReconnect: false. Se debe seguir intentando la conexión con el mismo token de arranque hasta que se apruebe la solicitud o el token deje de ser válido.
• Se debe conservar hello-ok.auth.deviceTokens únicamente cuando la conexión haya utilizado la autenticación de arranque en un transporte fiable, como wss://, o mediante emparejamiento local o de bucle invertido.
• Si un cliente proporciona un deviceToken explícito o un scopes explícito, el conjunto de ámbitos solicitado por el invocador sigue siendo el autoritativo; los ámbitos almacenados en caché solo se reutilizan cuando el cliente reutiliza el token almacenado por dispositivo.
• Los tokens de dispositivo se pueden rotar o revocar mediante device.token.rotate y device.token.revoke (requiere 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 devuelve el token portador de sustitución en las llamadas del mismo dispositivo que ya estén autenticadas con ese token de dispositivo, para que los clientes que solo utilizan tokens puedan conservar el sustituto antes de volver a conectarse. Las rotaciones compartidas o administrativas no devuelven el token portador.
• La emisión, rotación y revocación de tokens permanecen limitadas al conjunto de roles aprobados registrado en la entrada de emparejamiento de ese dispositivo; la modificación de tokens no puede ampliar ni dirigirse a un rol de dispositivo que la aprobación del emparejamiento nunca haya concedido.
• En las sesiones de tokens de dispositivos emparejados, la administración de dispositivos se limita al propio dispositivo, salvo que el invocador también tenga operator.admin: los invocadores sin privilegios administrativos solo pueden administrar el token de operador de su propia entrada de dispositivo. La administración de tokens de nodos y otros tokens que no sean de operador es exclusiva de administración, incluso para el propio dispositivo del invocador.
• device.token.rotate y device.token.revoke también comparan el conjunto de ámbitos del token de operador de destino con los ámbitos de la sesión actual del invocador. Los invocadores sin privilegios administrativos no pueden rotar ni revocar un token de operador con un ámbito más amplio que el que ya poseen.
• Los fallos de autenticación incluyen error.details.code y 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 fiables pueden intentar un único reintento limitado con un token almacenado por dispositivo.
  • Si ese reintento falla, se deben detener los bucles de reconexión automática y mostrar indicaciones sobre la intervención necesaria del operador.
• AUTH_SCOPE_MISMATCH significa que se reconoció el token de dispositivo, pero no abarca el rol ni los ámbitos solicitados. No se debe presentar como un token incorrecto; se debe indicar al operador que vuelva a emparejar el dispositivo o que apruebe el contrato de ámbitos más restringido o más amplio.

Identidad y emparejamiento de dispositivos

• Los nodos deben incluir una identidad de dispositivo estable (device.id) derivada de una huella digital del par de claves.
• Los Gateways emiten tokens por dispositivo y rol.
• Se requiere la aprobación del emparejamiento para los nuevos identificadores de dispositivo, salvo que esté habilitada la aprobación automática local.
• La aprobación automática del emparejamiento se centra en las conexiones directas mediante bucle invertido local.
• OpenClaw también dispone de una ruta restringida de conexión consigo mismo, local al backend o al contenedor, para flujos auxiliares fiables mediante secreto compartido.
• Las conexiones mediante tailnet o LAN en el mismo host siguen tratándose como remotas para el emparejamiento y requieren aprobación.
• Los clientes WS normalmente incluyen la identidad device durante connect (operador + nodo). Las únicas excepciones para operadores sin dispositivo son rutas de confianza explícitas:
  • gateway.controlUi.allowInsecureAuth=true para la compatibilidad con HTTP no seguro exclusivamente en localhost.
  • autenticación correcta del operador de la interfaz de control mediante gateway.auth.mode: "trusted-proxy".
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (medida de emergencia, reducción grave de la seguridad).
  • RPC de backend de gateway-client mediante bucle invertido directo en la ruta auxiliar interna reservada.
• Omitir la identidad del dispositivo tiene consecuencias para los ámbitos. Cuando se permite una conexión de operador sin dispositivo mediante una ruta de confianza explícita, OpenClaw sigue borrando los ámbitos autodeclarados y los deja como un conjunto vacío, salvo que dicha ruta tenga una excepción específica de conservación de ámbitos. Los métodos restringidos por ámbitos fallan entonces con missing scope.
• gateway.controlUi.dangerouslyDisableDeviceAuth=true es una ruta de conservación de ámbitos de emergencia de la interfaz de control. No concede ámbitos a clientes WebSocket arbitrarios personalizados con forma de backend o CLI.
• La ruta auxiliar de backend reservada de gateway-client mediante bucle invertido directo conserva los ámbitos únicamente para RPC internas del plano de control local; los identificadores 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 la autenticación de dispositivos

Para los clientes heredados que aún utilizan el comportamiento de firma anterior al desafío, connect devuelve códigos de detalle DEVICE_AUTH_* en error.details.code con un error.details.reason estable.

Fallos comunes de migración:

Objetivo de migración:

• Espere siempre a connect.challenge.
• Firme la carga útil v2 que incluye el nonce del servidor.
• Envíe 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, ámbitos, token y nonce.
• Las firmas heredadas v2 siguen aceptándose por compatibilidad, pero la fijación de los metadatos del dispositivo emparejado continúa controlando la política de comandos al reconectarse.

TLS y fijación

• Se admite TLS para las conexiones WS (configuración gateway.tls).
• Los clientes pueden fijar opcionalmente la huella digital del certificado del Gateway mediante gateway.remote.tlsFingerprint o la opción de la CLI --tls-fingerprint.

Alcance

Este protocolo expone la API completa del Gateway: estado, canales, modelos, chat, agente, sesiones, nodos, aprobaciones y más. La superficie exacta se define mediante los esquemas de TypeBox reexportados desde packages/gateway-protocol/src/schema.ts.

Contenido relacionado

• Protocolo de puente
• Guía operativa del Gateway