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 nodo (CLI, interfaz web, aplicación para macOS, nodos iOS/Android, nodos sin interfaz) se conectan mediante WebSocket y declaran un rol y un ámbito durante el protocolo de enlace.

Paquetes npm

Estos paquetes se distribuyen con los ciclos de lanzamiento de OpenClaw. Durante el despliegue inicial, npm puede devolver E404 hasta que se publique la primera versión que incluya paquetes.

• @openclaw/gateway-protocol publica los esquemas, validadores, tipos de TypeScript, utilidades ligeras para tramas y errores, y constantes de versión. Su archivo tar incluye el contrato generado protocol.schema.json legible por máquina.
• @openclaw/gateway-client publica el cliente Node de referencia y un punto de entrada compatible con navegadores en @openclaw/gateway-client/browser.

Para obtener orientación sobre el ciclo de vida de las aplicaciones, consulte Crear un cliente de Gateway. Para las aplicaciones que supervisan el Gateway como proceso secundario, consulte Integrar OpenClaw.

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). Después del protocolo de enlace, se siguen hello-ok.policy.maxPayload y hello-ok.policy.maxBufferedBytes. Con los diagnósticos habilitados, 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 contienen surface, tamaños en bytes, límites y un código de motivo seguro, pero nunca cuerpos de mensajes, contenido de archivos adjuntos, bytes de trama sin procesar, 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 errores de respuesta usan { code, message, details?, retryable?, retryAfterMs? }. Los clientes deben realizar la bifurcación según code y details.code; message sigue siendo legible para las personas y puede cambiar, excepto cuando una nota de compatibilidad indique lo contrario. Los fallos de autorización a nivel de método usan code: "FORBIDDEN" en el nivel superior, con detalles estructurados de los ámbitos ausentes:

• Ámbito ausente: { code: "MISSING_SCOPE", missingScope, requiredScopes }. requiredScopes es el conjunto completo de ámbitos conocidos para la operación solicitada. El mensaje heredado missing scope: <scope> se conserva para clientes antiguos.

Los clientes deben leer primero details y usar el mensaje heredado únicamente como alternativa de compatibilidad. readMissingScopeError y readMissingScopeErrorDetails se exportan desde @openclaw/gateway-protocol/gateway-error-details; el cliente de Gateway compatible con navegadores los reexporta desde @openclaw/gateway-client/browser.

Los esquemas se exportan como GatewayErrorDetailsSchema, MissingScopeErrorDetailsSchema desde @openclaw/gateway-protocol/schema. Los fallos de ámbito HTTP reflejan el objeto MISSING_SCOPE bajo error.details y usan el estado HTTP 403.

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 Plugin (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; use superficies de Plugin. El campo opcional appliedConfigHash de la instantánea es la revisión resuelta de la configuración de origen aceptada por el entorno de ejecución activo del Gateway. Los clientes pueden compararla con config.get.configRevisionHash para determinar si una configuración guardada más reciente aún requiere un reinicio. config.get.hash sigue siendo la revisión sin procesar del archivo raíz usada por las protecciones contra conflictos de escritura de configuración.

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

La inicialización integrada mediante QR/código de configuración es una ruta de transferencia móvil. Una conexión correcta con el 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 al operador se limita 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 el emparejamiento ni operator.admin. Un acceso más amplio de emparejamiento o administración requiere un flujo separado de emparejamiento aprobado o de tokens. Conserve hello-ok.auth.deviceTokens únicamente cuando la autenticación de inicialización se haya ejecutado mediante un transporte de confianza (wss:// o emparejamiento de bucle invertido/local).

Los clientes de backend de confianza dentro del 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 internas del plano de control (por ejemplo, actualizaciones de sesiones de subagentes) y evita que las referencias de emparejamiento obsoletas de la CLI o del dispositivo bloqueen el trabajo local del backend. Los clientes remotos, con origen en navegador, de nodo y los clientes explícitos de token o identidad de dispositivo siguen los controles normales de emparejamiento y ampliación de ámbitos.

Rol de trabajador y protocolo cerrado

Los trabajadores en la nube usan una entrada de bucle invertido dedicada a través del túnel SSH propiedad del Gateway, con la clave del host fijada. Solo acepta la identidad del trabajador y nunca distribuye autenticación general, eventos de nodo, RPC de operador ni métodos de Plugin. 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; también comprueba por separado la versión y el conjunto de características actuales. El éxito 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 alcanzar 25 MiB. La lista cerrada de permitidos contiene worker.heartbeat, worker.transcript.commit, worker.live-event, worker.inference.start y worker.inference.cancel.

Las confirmaciones de transcripciones usan 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 de transcripción y de sus elementos superiores mediante el escritor normal de sesiones. 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 a menos que todos los requisitos aparezcan 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, incluso cuando la política de herramientas las permite explícitamente.

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

Los nodos declaran capacidades durante la conexión:

• 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 declaraciones y aplica listas de permitidos en el servidor.

Roles y ámbitos

Para consultar el modelo completo de ámbitos del operador, las comprobaciones durante la aprobación y la semántica de los secretos compartidos, consulte Ámbitos del 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 mediante el protocolo de trabajador dedicado y cerrado.

Ámbitos del 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, lea 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 la primera barrera. Algunos comandos con barra diagonal a los que se accede mediante chat.send aplican comprobaciones más estrictas a nivel de 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), basada en el commands declarado 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: opciones granulares (p. ej., screen.record, camera.capture).

El Gateway las 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 después de conectarse o reconectarse correctamente. Los hosts de nodos sin interfaz reinician para aplicar los cambios declarativos del inventario MCP. Este método de actualización es la única vía de publicación; no se aceptan descriptores de herramientas de plugins en los parámetros de connect. Cada descriptor debe usar un name de herramienta seguro para el proveedor y nombrar un command incluido en la lista actual de comandos permitidos del nodo. El Gateway confía en los metadatos de los descriptores procedentes del nodo emparejado, filtra los descriptores que están fuera de la superficie de comandos aprobada, los elimina cuando el nodo se desconecta y rechaza los intentos del operador de modificar el catálogo de otro nodo. Establezca gateway.nodes.pluginTools.enabled: false para ignorar los descriptores publicados por los nodos.

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

Presencia

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

Los nodos nativos de macOS también pueden enviar eventos autenticados node.presence.activity con un tiempo de inactividad de entrada limitado. El Gateway deriva las marcas de tiempo de actividad con su propio reloj, expone el Mac conectado más reciente mediante node.list y node.describe, y difunde actualizaciones de node.presence a los clientes con ámbito de lectura. La aplicación envía { "action": "clear" } cuando se desactiva el uso compartido de actividad; el Gateway borra las marcas de tiempo solo para esa conexión exacta del nodo autenticado. Los Gateways anteriores a esta acción confirmada la devuelven como no gestionada, por lo que el nodo Mac se reconecta una vez y permite que la limpieza de la desconexión elimine el estado de la conexión anterior. 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 nodo

Los nodos llaman a node.event con event: "node.presence.alive" para registrar que un nodo emparejado estuvo activo durante una reactivación en segundo plano, sin marcarlo como conectado:

{  "event": "node.presence.alive",  "payloadJSON": "{\"trigger\":\"silent_push\",\"sentAtMs\":1737264000000,\"displayName\":\"iPhone de Peter\",\"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 como background (src/shared/node-presence.ts). El evento solo se conserva para sesiones autenticadas de dispositivos de nodo; las sesiones sin dispositivo o sin emparejar devuelven handled: false.

Los Gateways compatibles devuelven un resultado estructurado:

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

Los Gateways más antiguos pueden devolver únicamente { "ok": true } para node.event; debe tratarse como una RPC confirmada, no como persistencia duradera de la presencia.

Ámbito de los eventos de difusión

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

• Los fotogramas 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 fotogramas por completo.
• Las difusiones 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 usan operator.approvals en su lugar.
• Los eventos de estado/transporte (heartbeat, presence, tick y el 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 desconocidas de eventos de difusión se restringen por ámbito de forma predeterminada (se deniega en caso de duda), salvo que un gestor registrado las flexibilice explícitamente.

Cada conexión de cliente mantiene su propio número de secuencia por cliente, por lo que las difusiones conservan un orden monótono 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 conservadora de descubrimiento creada a partir de src/gateway/server-methods-list.ts y de 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 intencionadamente del descubrimiento aunque sean métodos reales que se pueden invocar. Debe tratarse como descubrimiento de funciones, no como una enumeración completa de src/gateway/server-methods/*.ts.

Familias de eventos comunes

• chat: actualizaciones del chat de la interfaz, como chat.inject y otros eventos de chat exclusivos de la transcripción. En el protocolo v4, las cargas útiles incrementales contienen deltaText; message sigue siendo la instantánea acumulativa del asistente. Los reemplazos que no sean prefijos establecen replace=true y utilizan deltaText como texto de reemplazo.
• session.message, session.operation, session.tool: actualizaciones de la transcripción, de las operaciones de sesión en curso y del flujo de eventos para una sesión suscrita.
• session.approval: estado depurado de las aprobaciones pendientes y terminales para un suscriptor de sesión exacta que haya aceptado explícitamente recibirlo. Las aprobaciones secundarias utilizan la audiencia persistente del antecesor; los eventos nunca modifican las transcripciones ni activan agentes.
• sessions.changed: el índice o los metadatos de la sesión cambiaron.
• presence: actualizaciones de la instantánea de presencia del sistema.
• tick: evento periódico de mantenimiento de conexión y actividad.
• health: actualización de la instantánea del estado del Gateway.
• heartbeat: actualización del flujo de eventos de Heartbeat.
• cron: evento de cambio de una ejecución o un trabajo de Cron.
• shutdown: notificación de apagado del Gateway.
• node.pair.requested / node.pair.resolved: ciclo de vida del emparejamiento de Nodes.
• node.invoke.request: difusión de una solicitud de invocación de Node.
• device.pair.requested / device.pair.resolved: ciclo de vida de los dispositivos emparejados.
• voicewake.changed: cambió la configuración del activador por palabra de activación.
• config.changed: se ha persistido una escritura de configuración (la carga útil contiene la ruta de configuración, el hash de la nueva instantánea y una marca de tiempo, pero nunca el contenido de la configuración). Limitado a la lectura por operadores; los clientes actualizan mediante config.get.
• exec.approval.requested / exec.approval.resolved: ciclo de vida de las aprobaciones de ejecución.
• plugin.approval.requested / plugin.approval.resolved: ciclo de vida de las aprobaciones de plugins.

Métodos auxiliares de Node

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

RPC del libro mayor de auditoría

audit.activity.list proporciona a los clientes operadores una vista estable, comenzando por los más recientes, de los metadatos del ciclo de vida de las ejecuciones de agentes, las acciones de herramientas y los mensajes que requieren aceptación explícita. Requiere operator.read. Las consultas excluyen los registros con más de 30 días de antigüedad y el libro mayor SQLite compartido está limitado a 100,000 registros. Las filas caducadas se eliminan durante el inicio del Gateway, el mantenimiento por hora 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 y 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 una cadena cursor opcional de la página anterior.
• Resultado: { "events": AuditActivityEventV1[], "nextCursor"?: string }.

La unión de resultados V1 con nombre contiene 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 de mensaje siguen disponibles para el filtrado y la visualización. Cada evento tiene un schemaVersion: 1 entero. Las referencias de identidad de mensajes utilizan el formato hmac-sha256:v1:<32 hex key id>:<64 hex digest> exacto; el identificador del actor que envía por un canal utiliza 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 se puede descartar 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 libro mayor, 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 de agentes y ejecuciones, 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 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 con clave local de la instalación para la cuenta, la conversación, el mensaje y el destino. 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. 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 ejecución/herramienta siguen siendo metadatos de correlación sin procesar y pueden incluir identificadores de cuentas o pares de la plataforma; los registros de mensajes omiten las claves de sesión.

Para las filas entrantes, durationMs mide el despacho del núcleo hasta su finalización y resultCount cuenta las cargas útiles finalizadas en cola de herramientas, bloques y respuestas. Para las filas salientes, durationMs abarca la propiedad de la entrega hasta la confirmación, la cola de mensajes fallidos o la conciliació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 la renderización; las filas suprimidas o con ambigüedad por fallos omiten este valor.

La cobertura actual de mensajes incluye los mensajes entrantes aceptados que llegan al despacho del núcleo, incluidos los resultados de duplicación/finalización del núcleo. La cobertura saliente escribe una fila final por cada carga útil de respuesta lógica original que llega a la entrega duradera compartida; la fragmentación y la distribución en abanico 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 fallidos o la conciliación. Las rutas locales de los plugins y de envío directo que omiten esos límites compartidos aún no están cubiertas. La cola de trabajadores acotada 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 sigue sirviendo los registros escritos anteriormente hasta que caduquen.

Los esquemas publicados de solicitud y resultado de audit.list, y de AuditEvent, permanecen sin cambios y devuelven únicamente 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 más antiguos pueden informar de unknown method: audit.activity.list o, dado que la autorización precedía a la búsqueda del método en las versiones publicadas, de missing scope: operator.admin ante una solicitud con ámbito de lectura. Se debe interpretar este último como ausencia del método solo cuando el método no se haya anunciado. A continuación, un cliente puede volver a intentar audit.list únicamente cuando sus filtros no requieran compatibilidad con el tipo de mensaje, la dirección ni el canal.

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 del entorno 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 tareas 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 final 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 del agente predeterminado.
  • scope controla a qué superficie apunta el name principal: text devuelve el token del comando de texto principal sin el / inicial; native y la ruta predeterminada both devuelven nombres nativos que tienen en cuenta al proveedor cuando están disponibles.
  • textAliases contiene alias exactos con barra, como /model y /m.
  • nativeName contiene el nombre del comando nativo que tiene en cuenta 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 los 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: propietario del plugin cuando source="plugin"
  • optional: indica si una herramienta del 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 el contexto de confianza del entorno de ejecución a partir de la sesión en el servidor en lugar de aceptar un contexto de autenticación o entrega proporcionado 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 descubiertas.
  • 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 ningún 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 sesión resuelto debe coincidir con agentId.
  • Los envoltorios del núcleo exclusivos del propietario, como cron, gateway y nodes, requieren 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 omitir el pipeline 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 del agente predeterminado.
  • La respuesta incluye la idoneidad, los requisitos que faltan, las comprobaciones de configuración y las opciones de instalación depuradas sin exponer los valores de 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 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é habilitado.
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) crea una carga vinculada a ese slug y valor de forzado.
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) añade 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 Skills 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 forzado deben coincidir con la solicitud skills.upload.begin original. Se rechaza salvo que skills.install.allowUploadedArchives esté habilitado; el ajuste 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 más 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 las decisiones de instalación propiedad del operador.
• skills.update (operator.admin) tiene dos modos:
  • El modo ClawHub actualiza un slug registrado o todas las instalaciones registradas de ClawHub en el espacio de trabajo del agente predeterminado.
  • El modo de configuración modifica los 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.modelPolicy.allow está configurado, la respuesta es el catálogo permitido, incluidos los modelos descubiertos dinámicamente para las entradas provider/*. De lo contrario, la respuesta es el catálogo completo del Gateway.
• "configured": comportamiento adaptado al selector. Si agents.defaults.modelPolicy.allow está configurado, sigue teniendo prioridad, incluido el descubrimiento limitado 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 únicamente cuando no existe ninguna fila de modelos configurada.
• "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 en función de las rutas, pero omiten los endpoints de los proveedores, el material de autenticación y la configuración de las solicitudes del entorno de ejecución.
• "all": catálogo completo del Gateway, omitiendo agents.defaults.modelPolicy.allow. Úselo para interfaces de usuario de diagnóstico/descubrimiento, 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 del operador 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). Se rechazan las solicitudes que no incluyan systemRunPlan.
• Tras la aprobación, las llamadas reenviadas a node.invoke system.run reutilizan ese systemRunPlan canónico como contexto autoritativo del comando, el directorio de trabajo y la sesión.
• Si un llamador modifica 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 modificada.

Alternativa de entrega del agente

• Las solicitudes agent pueden incluir deliver=true para solicitar la entrega saliente.
• bestEffortDeliver=false (el valor predeterminado) mantiene un 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 o de chat web, o configuraciones multicanal ambiguas).
• Los resultados finales de agent pueden incluir result.deliveryStatus cuando se solicitó la entrega, utilizando 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 se encuentran en packages/gateway-protocol/src/version.ts.
• Los clientes envían minProtocol + maxProtocol. Los clientes del operador y de la interfaz de usuario deben incluir el protocolo actual en ese intervalo; los clientes y servidores actuales ejecutan el protocolo v4.
• Los clientes autenticados que tengan tanto role: "node" como client.mode: "node" pueden utilizar el protocolo de Node N-1 (actualmente v3). Las sondas ligeras de reinicio utilizan 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 no están disponibles hasta que el Node se actualice 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 del cliente de referencia se encuentra en packages/gateway-client/src/ (OpenClaw la encapsula mediante la delgada fachada src/gateway/client.ts). Estos valores predeterminados son estables en el protocolo v4 y constituyen la referencia esperada para los 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 su fecha límite configurada cuando cada solicitud pendiente tiene una. 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 supervisor de tics. Si los eventos entrantes y las respuestas permanecen en silencio más allá del umbral de tiempo de espera del tic, el cliente cierra el socket con el código 4000, rechaza todas las solicitudes pendientes y vuelve a conectarse. No reproduce las solicitudes rechazadas después de volver a conectarse.

Autenticación

• La autenticación del Gateway mediante secreto compartido usa connect.params.auth.token o connect.params.auth.password, según el valor configurado de gateway.auth.mode ("none" | "token" | "password" | "trusted-proxy").
• Los modos que incluyen 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 mediante los encabezados de la solicitud en lugar de connect.params.auth.*.
• El gateway.auth.mode: "none" de entrada privada omite por completo la autenticación de conexión mediante secreto compartido; no exponga ese modo en una entrada pública o no confiable.
• 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 debe reutilizarse el conjunto de ámbitos aprobado y almacenado para dicho token. Esto conserva el acceso de lectura, sondeo y estado ya concedido y evita reducir silenciosamente las reconexiones a un ámbito implícito más limitado y exclusivo para administradores.
• 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 (identificado mediante 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 está restringida únicamente a endpoints confiables: loopback 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 Node principal hello-ok.auth.deviceToken junto con un token de operador limitado en hello-ok.auth.deviceTokens para la transferencia móvil confiable. El token de operador incluye operator.talk.secrets para las lecturas de configuración nativa de Talk, pero excluye los ámbitos de modificación del emparejamiento y operator.admin.
• Mientras un arranque mediante código de configuración no básico espera aprobación, los detalles de PAIRING_REQUIRED incluyen recommendedNextStep: "wait_then_retry", retryable: true y pauseReconnect: false. Siga intentando conectarse con el mismo token de arranque hasta que se apruebe la solicitud o el token deje de ser válido.
• Conserve hello-ok.auth.deviceTokens únicamente cuando la conexión haya usado autenticación de arranque en un transporte confiable, como wss://, o mediante emparejamiento local/loopback.
• Si un cliente proporciona un deviceToken explícito o un scopes explícito, el conjunto de ámbitos solicitado por ese invocador sigue siendo el autoritativo; los ámbitos almacenados en caché solo se reutilizan cuando el cliente vuelve a utilizar el token almacenado por dispositivo.
• Los tokens de dispositivo pueden rotarse o revocarse mediante device.token.rotate y device.token.revoke (requiere operator.pairing). Rotar o revocar un Node 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 de portador de reemplazo en las llamadas del mismo dispositivo que ya estén autenticadas con ese token de dispositivo, para que los clientes que solo usan tokens puedan conservar el reemplazo antes de volver a conectarse. Las rotaciones compartidas o de administrador no devuelven el token de 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 modificación de tokens no puede ampliar ni dirigirse a un rol de dispositivo que nunca haya concedido la aprobación del emparejamiento.
• En las sesiones con 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 de administrador solo pueden administrar el token de operador de su propia entrada de dispositivo. La administración de tokens de Node y de otros tokens que no sean de operador es exclusiva para administradores, incluso en 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 de administrador no pueden rotar ni revocar un token de operador con más ámbitos que los 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 confiables pueden intentar un único reintento limitado con un token almacenado en caché por dispositivo.
  • Si ese reintento falla, detenga los bucles de reconexión automática y muestre indicaciones sobre la acción que debe realizar el operador.
• AUTH_SCOPE_MISMATCH significa que se reconoció el token de dispositivo, pero no cubre el rol ni los ámbitos solicitados. No lo presente como un token incorrecto; solicite al operador que vuelva a emparejar el dispositivo o que apruebe el contrato de ámbitos más limitado o más amplio.

Identidad y emparejamiento de dispositivos

• Los Nodes deben incluir una identidad de dispositivo estable (device.id) derivada de la huella digital de un par de claves.
• Los Gateways emiten tokens por dispositivo y rol.
• Se requieren aprobaciones de 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 locales directas por loopback.
• OpenClaw también dispone de una ruta limitada de autoconexión local al backend/contenedor para flujos auxiliares confiables con secreto compartido.
• Las conexiones desde la misma máquina mediante tailnet o LAN siguen considerándose remotas para el emparejamiento y requieren aprobación.
• Normalmente, los clientes WS incluyen la identidad device durante connect (operador + Node). Las únicas excepciones para operadores sin dispositivo son rutas de confianza explícitas:
  • autenticación correcta de la interfaz de control del operador mediante gateway.auth.mode: "trusted-proxy".
  • RPC del backend gateway-client mediante loopback 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 declarados por la propia conexión y los deja como un conjunto vacío, salvo que esa ruta tenga una excepción explícita para conservarlos. Los métodos restringidos por ámbitos fallan entonces con missing scope.
• La ruta auxiliar reservada del backend gateway-client mediante loopback 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 todavía usan 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 la 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 volver a conectarse.

TLS y fijación

• TLS es compatible con 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, Nodes, aprobaciones y más. La superficie exacta está definida por los esquemas de TypeBox reexportados desde packages/gateway-protocol/src/schema.ts.

Contenido relacionado

• Crear un cliente del Gateway
• Integrar OpenClaw
• Protocolo de puente
• Guía operativa del Gateway