--- read_when: - Implementar o actualizar clientes WS de Gateway - Depurar discrepancias de protocolo o fallos de conexión - Regenerando esquemas/modelos de protocolo summary: 'Protocolo WebSocket del Gateway: handshake, tramas, versionado' title: Protocolo de Gateway x-i18n: generated_at: "2026-07-04T17:48:51Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: 763dd5cba2f1aa0de95243a4996b4da1b4aa32c5c1a4b5b6c112d605e677bd70 source_path: gateway/protocol.md workflow: 16 --- El protocolo WS del Gateway es el **plano de control único + transporte de nodos** para OpenClaw. Todos los clientes (CLI, interfaz web, app de macOS, nodos iOS/Android, nodos sin interfaz) se conectan por WebSocket y declaran su **rol** + **ámbito** durante el handshake. ## Transporte - WebSocket, tramas de texto con cargas útiles JSON. - La primera trama **debe** ser una solicitud `connect`. - Las tramas previas a la conexión tienen un límite de 64 KiB. Después de un handshake correcto, los clientes deben seguir los límites `hello-ok.policy.maxPayload` y `hello-ok.policy.maxBufferedBytes`. Con diagnósticos activados, las tramas entrantes sobredimensionadas y los búferes salientes lentos emiten eventos `payload.large` antes de que el gateway cierre o descarte la trama afectada. Estos eventos conservan tamaños, límites, superficies y códigos de motivo seguros. No conservan el cuerpo del mensaje, el contenido de adjuntos, el cuerpo bruto de la trama, tokens, cookies ni valores secretos. ## Handshake (connect) Gateway → Cliente (desafío previo a la conexión): ```json { "type": "event", "event": "connect.challenge", "payload": { "nonce": "…", "ts": 1737264000000 } } ``` Cliente → Gateway: ```json { "type": "req", "id": "…", "method": "connect", "params": { "minProtocol": 3, "maxProtocol": 4, "client": { "id": "cli", "version": "1.2.3", "platform": "macos", "mode": "operator" }, "role": "operator", "scopes": ["operator.read", "operator.write"], "caps": [], "commands": [], "permissions": {}, "auth": { "token": "…" }, "locale": "en-US", "userAgent": "openclaw-cli/1.2.3", "device": { "id": "device_fingerprint", "publicKey": "…", "signature": "…", "signedAt": 1737264000000, "nonce": "…" } } } ``` Gateway → Cliente: ```json { "type": "res", "id": "…", "ok": true, "payload": { "type": "hello-ok", "protocol": 4, "server": { "version": "…", "connId": "…" }, "features": { "methods": ["…"], "events": ["…"] }, "snapshot": { "…": "…" }, "auth": { "role": "operator", "scopes": ["operator.read", "operator.write"] }, "policy": { "maxPayload": 26214400, "maxBufferedBytes": 52428800, "tickIntervalMs": 15000 } } } ``` Mientras el Gateway todavía está terminando sidecars de arranque, la solicitud `connect` puede devolver un error reintentable `UNAVAILABLE` con `details.reason` establecido en `"startup-sidecars"` y `retryAfterMs`. Los clientes deben reintentar esa respuesta dentro de su presupuesto general de conexión en lugar de mostrarla como un fallo terminal de handshake. `server`, `features`, `snapshot` y `policy` son todos obligatorios según el esquema (`packages/gateway-protocol/src/schema/frames.ts`). `auth` también es obligatorio e informa el rol/los ámbitos negociados. `pluginSurfaceUrls` es opcional y asigna nombres de superficies de plugins, como `canvas`, a URL alojadas con ámbito. Las URL de superficies de plugins con ámbito pueden expirar. Los nodos pueden llamar a `node.pluginSurface.refresh` con `{ "surface": "canvas" }` para recibir una entrada nueva en `pluginSurfaceUrls`. La refactorización experimental del Plugin Canvas no admite la ruta de compatibilidad obsoleta `canvasHostUrl`, `canvasCapability` ni `node.canvas.capability.refresh`; los clientes nativos y gateways actuales deben usar superficies de plugins. Cuando no se emite ningún token de dispositivo, `hello-ok.auth` informa los permisos negociados sin campos de token: ```json { "auth": { "role": "operator", "scopes": ["operator.read", "operator.write"] } } ``` Los clientes backend confiables del mismo proceso (`client.id: "gateway-client"`, `client.mode: "backend"`) pueden omitir `device` en conexiones directas local loopback cuando se autentican con el token/contraseña compartidos del gateway. Esta ruta está reservada para RPC internos del plano de control y evita que las líneas base obsoletas de emparejamiento CLI/dispositivo bloqueen trabajo backend local, como actualizaciones de sesiones de subagentes. Los clientes remotos, clientes con origen de navegador, clientes de nodo y clientes explícitos con token de dispositivo/identidad de dispositivo siguen usando las comprobaciones normales de emparejamiento y ampliación de ámbito. Cuando se emite un token de dispositivo, `hello-ok` también incluye: ```json { "auth": { "deviceToken": "…", "role": "operator", "scopes": ["operator.read", "operator.write"] } } ``` El arranque integrado mediante QR/código de configuración es una ruta nueva de traspaso móvil. Una conexión correcta con código de configuración de línea base devuelve un token de nodo principal más un token de operador limitado: ```json { "auth": { "deviceToken": "…", "role": "node", "scopes": [], "deviceTokens": [ { "deviceToken": "…", "role": "operator", "scopes": ["operator.approvals", "operator.read", "operator.talk.secrets", "operator.write"] } ] } } ``` El traspaso de operador está limitado intencionadamente para que el onboarding QR pueda iniciar el bucle de operador móvil y completar la configuración nativa sin conceder ámbitos de mutación de emparejamiento ni `operator.admin`. Incluye `operator.talk.secrets` para que el cliente nativo pueda leer la configuración de Talk que necesita después del arranque. El acceso más amplio de emparejamiento y administración requiere un flujo separado aprobado de emparejamiento de operador o token. Los clientes deben persistir `hello-ok.auth.deviceTokens` solo cuando la conexión usó autenticación de arranque en un transporte confiable como `wss://` o emparejamiento local/loopback. ### Ejemplo de Node ```json { "type": "req", "id": "…", "method": "connect", "params": { "minProtocol": 3, "maxProtocol": 4, "client": { "id": "ios-node", "version": "1.2.3", "platform": "ios", "mode": "node" }, "role": "node", "scopes": [], "caps": ["camera", "canvas", "screen", "location", "voice"], "commands": ["camera.snap", "canvas.navigate", "screen.record", "location.get"], "permissions": { "camera.capture": true, "screen.record": false }, "auth": { "token": "…" }, "locale": "en-US", "userAgent": "openclaw-ios/1.2.3", "device": { "id": "device_fingerprint", "publicKey": "…", "signature": "…", "signedAt": 1737264000000, "nonce": "…" } } } ``` ## Encuadre - **Solicitud**: `{type:"req", id, method, params}` - **Respuesta**: `{type:"res", id, ok, payload|error}` - **Evento**: `{type:"event", event, payload, seq?, stateVersion?}` Los métodos con efectos secundarios requieren **claves de idempotencia** (consulta el esquema). ## Roles + ámbitos Para ver el modelo completo de ámbitos de operador, las comprobaciones en tiempo de aprobación y la semántica de secretos compartidos, consulta [Ámbitos de operador](/es/gateway/operator-scopes). ### Roles - `operator` = cliente del plano de control (CLI/UI/automatización). - `node` = host de capacidades (cámara/pantalla/canvas/system.run). ### Ámbitos (operador) Ámbitos comunes: - `operator.read` - `operator.write` - `operator.admin` - `operator.approvals` - `operator.pairing` - `operator.talk.secrets` `talk.config` con `includeSecrets: true` requiere `operator.talk.secrets` (o `operator.admin`). Cuando se incluyen secretos, los clientes deben leer la credencial activa del proveedor de Talk desde `talk.resolved.config.apiKey`; `talk.providers..apiKey` conserva la forma de origen y puede ser un objeto SecretRef o una cadena redactada. Los métodos RPC del gateway registrados por plugins pueden solicitar su propio ámbito de operador, pero los prefijos reservados de administración del núcleo (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) siempre se resuelven como `operator.admin`. El ámbito de método es solo la primera barrera. Algunos comandos slash alcanzados mediante `chat.send` aplican comprobaciones más estrictas a nivel de comando encima. Por ejemplo, las escrituras persistentes `/config set` y `/config unset` requieren `operator.admin`. `node.pair.approve` también tiene una comprobación adicional de ámbito en tiempo de aprobación encima del ámbito base del método: - solicitudes sin comandos: `operator.pairing` - solicitudes con comandos de nodo no exec: `operator.pairing` + `operator.write` - solicitudes que incluyen `system.run`, `system.run.prepare` o `system.which`: `operator.pairing` + `operator.admin` ### Capacidades/comandos/permisos (nodo) Los nodos declaran reivindicaciones de capacidad en el momento de la conexión: - `caps`: categorías de capacidad de alto nivel como `camera`, `canvas`, `screen`, `location`, `voice` y `talk`. - `commands`: lista de permitidos de comandos para invocación. - `permissions`: interruptores granulares (por ejemplo, `screen.record`, `camera.capture`). El Gateway trata estas como **reivindicaciones** y aplica listas de permitidos del lado del servidor. ## Presencia - `system-presence` devuelve entradas indexadas por identidad de dispositivo. - Las entradas de presencia incluyen `deviceId`, `roles` y `scopes` para que las UI puedan mostrar una sola fila por dispositivo incluso cuando se conecta como **operator** y **node**. - `node.list` incluye campos opcionales `lastSeenAtMs` y `lastSeenReason`. Los nodos conectados informan su hora de conexión actual como `lastSeenAtMs` con el motivo `connect`; los nodos emparejados también pueden informar presencia duradera en segundo plano cuando un evento de nodo confiable actualiza sus metadatos de emparejamiento. ### Evento alive en segundo plano de Node Los nodos pueden llamar a `node.event` con `event: "node.presence.alive"` para registrar que un nodo emparejado estaba activo durante una activación en segundo plano sin marcarlo como conectado. ```json { "event": "node.presence.alive", "payloadJSON": "{\"trigger\":\"silent_push\",\"sentAtMs\":1737264000000,\"displayName\":\"Peter's iPhone\",\"version\":\"2026.4.28\",\"platform\":\"iOS 18.4.0\",\"deviceFamily\":\"iPhone\",\"modelIdentifier\":\"iPhone17,1\",\"pushTransport\":\"relay\"}" } ``` `trigger` es una enumeración cerrada: `background`, `silent_push`, `bg_app_refresh`, `significant_location`, `manual` o `connect`. Las cadenas de activador desconocidas se normalizan a `background` en el gateway antes de persistir. El evento es duradero solo para sesiones de dispositivo de nodo autenticadas; las sesiones sin dispositivo o no emparejadas devuelven `handled: false`. Los gateways correctos devuelven un resultado estructurado: ```json { "ok": true, "event": "node.presence.alive", "handled": true, "reason": "persisted" } ``` Los gateways antiguos aún pueden devolver `{ "ok": true }` para `node.event`; los clientes deben tratarlo como un RPC reconocido, no como persistencia duradera de presencia. ## Delimitación de ámbito de eventos de difusión Los eventos de difusión WebSocket enviados por el servidor están protegidos por ámbito para que las sesiones con ámbito de emparejamiento o solo de nodo no reciban pasivamente contenido de sesión. - **Tramas de chat, agente y resultados de herramientas** (incluidos eventos `agent` transmitidos y resultados de llamadas a herramientas) requieren al menos `operator.read`. Las sesiones sin `operator.read` omiten estas tramas por completo. - **Difusiones `plugin.*` definidas por plugins** están restringidas a `operator.write` o `operator.admin`, según cómo las haya registrado el plugin. - **Eventos de estado y transporte** (`heartbeat`, `presence`, `tick`, ciclo de vida de conexión/desconexión, etc.) permanecen sin restricciones para que la salud del transporte siga siendo observable para cada sesión autenticada. - **Familias de eventos de difusión desconocidas** están protegidas por ámbito de forma predeterminada (fallo cerrado) salvo que un controlador registrado las relaje explícitamente. Cada conexión de cliente conserva su propio número de secuencia por cliente para que las difusiones preserven el orden monótono en ese socket incluso cuando distintos clientes ven subconjuntos diferentes filtrados por ámbito del flujo de eventos. ## Familias comunes de métodos RPC La superficie WS pública es más amplia que los ejemplos de handshake/autenticación anteriores. Esto no es un volcado generado: `hello-ok.features.methods` es una lista conservadora de descubrimiento creada a partir de `src/gateway/server-methods-list.ts` más las exportaciones de métodos de plugins/canales cargadas. Trátala como descubrimiento de funcionalidades, no como una enumeración completa de `src/gateway/server-methods/*.ts`. - `health` devuelve la instantánea de salud del Gateway almacenada en caché o sondeada recientemente. - `diagnostics.stability` devuelve el registrador reciente y acotado de estabilidad diagnóstica. Conserva metadatos operativos como nombres de eventos, recuentos, tamaños en bytes, lecturas de memoria, estado de colas/sesiones, nombres de canales/Plugins e ids de sesión. No conserva texto de chats, cuerpos de Webhook, salidas de herramientas, cuerpos sin procesar de solicitudes o respuestas, tokens, cookies ni valores secretos. Se requiere alcance de lectura de operador. - `status` devuelve el resumen del Gateway con estilo `/status`; los campos sensibles se incluyen solo para clientes de operador con alcance de administrador. - `gateway.identity.get` devuelve la identidad de dispositivo del Gateway usada por los flujos de retransmisión y emparejamiento. - `system-presence` devuelve la instantánea de presencia actual para dispositivos de operador/Node conectados. - `system-event` agrega un evento del sistema y puede actualizar/difundir el contexto de presencia. - `last-heartbeat` devuelve el evento de Heartbeat persistido más reciente. - `set-heartbeats` activa o desactiva el procesamiento de Heartbeat en el Gateway. - `models.list` devuelve el catálogo de modelos permitido por el runtime. Pasa `{ "view": "configured" }` para modelos configurados de tamaño selector (`agents.defaults.models` primero, luego `models.providers.*.models`), o `{ "view": "all" }` para el catálogo completo. - `usage.status` devuelve resúmenes de ventanas de uso/cuota restante del proveedor. - `usage.cost` devuelve resúmenes agregados de uso de costos para un intervalo de fechas. Pasa `agentId` para un agente, o `agentScope: "all"` para agregar agentes configurados. - `doctor.memory.status` devuelve la preparación de memoria vectorial / embeddings almacenados en caché para el espacio de trabajo del agente predeterminado activo. Pasa `{ "probe": true }` o `{ "deep": true }` solo cuando el llamador quiera explícitamente un ping en vivo al proveedor de embeddings. Los clientes compatibles con Dreaming también pueden pasar `{ "agentId": "agent-id" }` para limitar las estadísticas del almacén de Dreaming a un espacio de trabajo de agente seleccionado; omitir `agentId` conserva el fallback del agente predeterminado y agrega los espacios de trabajo de Dreaming configurados. - `doctor.memory.dreamDiary`, `doctor.memory.backfillDreamDiary`, `doctor.memory.resetDreamDiary`, `doctor.memory.resetGroundedShortTerm`, `doctor.memory.repairDreamingArtifacts` y `doctor.memory.dedupeDreamDiary` aceptan parámetros opcionales `{ "agentId": "agent-id" }` para vistas/acciones de Dreaming del agente seleccionado. Cuando se omite `agentId`, operan sobre el espacio de trabajo del agente predeterminado configurado. - `doctor.memory.remHarness` devuelve una vista previa acotada y de solo lectura del arnés REM para clientes remotos del plano de control. Puede incluir rutas de espacios de trabajo, fragmentos de memoria, markdown fundamentado renderizado y candidatos de promoción profunda, por lo que los llamadores necesitan `operator.read`. - `sessions.usage` devuelve resúmenes de uso por sesión. Pasa `agentId` para un agente, o `agentScope: "all"` para listar juntos los agentes configurados. - `sessions.usage.timeseries` devuelve el uso de serie temporal para una sesión. - `sessions.usage.logs` devuelve entradas de registro de uso para una sesión. - `channels.status` devuelve resúmenes de estado de canales/Plugins incorporados + integrados. - `channels.logout` cierra la sesión de un canal/cuenta específico donde el canal admite cierre de sesión. - `web.login.start` inicia un flujo de inicio de sesión QR/web para el proveedor de canal web actual compatible con QR. - `web.login.wait` espera a que ese flujo de inicio de sesión QR/web se complete e inicia el canal si tiene éxito. - `push.test` envía una notificación push APNs de prueba a un Node iOS registrado. - `voicewake.get` devuelve los disparadores de palabra de activación almacenados. - `voicewake.set` actualiza los disparadores de palabra de activación y difunde el cambio. - `send` es el RPC directo de entrega saliente para envíos dirigidos a canal/cuenta/hilo fuera del ejecutor de chat. - `logs.tail` devuelve la cola del registro de archivo configurado del Gateway con controles de cursor/límite y bytes máximos. - `talk.catalog` devuelve el catálogo de solo lectura de proveedores de Talk para voz, transcripción en streaming y voz en tiempo real. Incluye ids canónicos de proveedor, alias de registro, etiquetas, estado configurado, un resultado opcional `ready` a nivel de grupo, ids expuestos de modelo/voz, modos canónicos, transportes, estrategias de cerebro y flags de audio/capacidad en tiempo real sin devolver secretos del proveedor ni mutar la configuración global. Los Gateways actuales establecen `ready` después de aplicar la selección de proveedor del runtime; los clientes deben tratar su ausencia como no verificada para compatibilidad con Gateways más antiguos. - `talk.config` devuelve la carga útil efectiva de configuración de Talk; `includeSecrets` requiere `operator.talk.secrets` (o `operator.admin`). - `talk.session.create` crea una sesión de Talk propiedad del Gateway para `realtime/gateway-relay`, `transcription/gateway-relay` o `stt-tts/managed-room`. Para `stt-tts/managed-room`, los llamadores `operator.write` que pasan `sessionKey` también deben pasar `spawnedBy` para visibilidad acotada de clave de sesión; la creación no acotada de `sessionKey` y `brain: "direct-tools"` requieren `operator.admin`. - `talk.session.join` valida un token de sesión de sala administrada, emite eventos `session.ready` o `session.replaced` según sea necesario y devuelve metadatos de sala/sesión más eventos recientes de Talk sin el token en texto plano ni el hash de token almacenado. - `talk.session.appendAudio` agrega audio de entrada PCM en base64 a sesiones de retransmisión en tiempo real y transcripción propiedad del Gateway. - `talk.session.startTurn`, `talk.session.endTurn` y `talk.session.cancelTurn` controlan el ciclo de vida de turnos de sala administrada con rechazo de turnos obsoletos antes de que se borre el estado. - `talk.session.cancelOutput` detiene la salida de audio del asistente, principalmente para interrupciones con compuerta VAD en sesiones de retransmisión del Gateway. - `talk.session.submitToolResult` completa una llamada de herramienta de proveedor emitida por una sesión de retransmisión en tiempo real propiedad del Gateway. Pasa `options: { willContinue: true }` para salida provisional de herramienta cuando vaya a seguir un resultado final, u `options: { suppressResponse: true }` cuando el resultado de herramienta deba satisfacer la llamada del proveedor sin iniciar otra respuesta de asistente en tiempo real. - `talk.session.steer` envía control de voz de ejecución activa a una sesión de Talk respaldada por agente y propiedad del Gateway. Acepta `{ sessionId, text, mode? }`, donde `mode` es `status`, `steer`, `cancel` o `followup`; el modo omitido se clasifica a partir del texto hablado. - `talk.session.close` cierra una sesión de retransmisión, transcripción o sala administrada propiedad del Gateway y emite eventos terminales de Talk. - `talk.mode` establece/difunde el estado actual del modo Talk para clientes WebChat/Control UI. - `talk.client.create` crea una sesión de proveedor en tiempo real propiedad del cliente usando `webrtc` o `provider-websocket` mientras el Gateway posee la configuración, credenciales, instrucciones y política de herramientas. - `talk.client.toolCall` permite que transportes en tiempo real propiedad del cliente reenvíen llamadas de herramientas del proveedor a la política del Gateway. La primera herramienta admitida es `openclaw_agent_consult`; los clientes reciben un id de ejecución y esperan los eventos normales del ciclo de vida del chat antes de enviar el resultado de herramienta específico del proveedor. - `talk.client.steer` envía control de voz de ejecución activa para transportes en tiempo real propiedad del cliente. El Gateway resuelve la ejecución incrustada activa desde `sessionKey` y devuelve un resultado estructurado aceptado/rechazado en lugar de descartar silenciosamente la dirección. - `talk.event` es el canal único de eventos de Talk para adaptadores de tiempo real, transcripción, STT/TTS, sala administrada, telefonía y reuniones. - `talk.speak` sintetiza voz mediante el proveedor de voz de Talk activo. - `tts.status` devuelve el estado habilitado de TTS, el proveedor activo, proveedores de fallback y el estado de configuración del proveedor. - `tts.providers` devuelve el inventario visible de proveedores TTS. - `tts.enable` y `tts.disable` activan o desactivan el estado de preferencias de TTS. - `tts.setProvider` actualiza el proveedor TTS preferido. - `tts.convert` ejecuta una conversión puntual de texto a voz. - `secrets.reload` vuelve a resolver SecretRefs activos e intercambia el estado de secretos del runtime solo si todo tiene éxito. - `secrets.resolve` resuelve asignaciones de secretos dirigidas a comandos para un conjunto específico de comando/destino. - `config.get` devuelve la instantánea y el hash de la configuración actual. - `config.set` escribe una carga útil de configuración validada. - `config.patch` fusiona una actualización parcial de configuración. El reemplazo destructivo de arrays requiere la ruta afectada en `replacePaths`; los arrays anidados bajo entradas de array usan rutas `[]` como `agents.list[].skills`. - `config.apply` valida + reemplaza la carga útil completa de configuración. - `config.schema` devuelve la carga útil del esquema de configuración en vivo usada por Control UI y herramientas CLI: esquema, `uiHints`, versión y metadatos de generación, incluidos metadatos de esquema de Plugins + canales cuando el runtime puede cargarlos. El esquema incluye metadatos de campo `title` / `description` derivados de las mismas etiquetas y texto de ayuda usados por la UI, incluidas ramas de composición de objeto anidado, comodín, elemento de array y `anyOf` / `oneOf` / `allOf` cuando existe documentación de campo coincidente. - `config.schema.lookup` devuelve una carga útil de búsqueda acotada a ruta para una ruta de configuración: ruta normalizada, un nodo de esquema superficial, indicio coincidente + `hintPath`, `reloadKind` opcional y resúmenes de hijos inmediatos para exploración detallada de UI/CLI. `reloadKind` es uno de `restart`, `hot` o `none` y refleja el planificador de recarga de configuración del Gateway para la ruta solicitada. Los nodos de esquema de búsqueda conservan la documentación orientada al usuario y los campos comunes de validación (`title`, `description`, `type`, `enum`, `const`, `format`, `pattern`, límites numéricos/de cadena/array/objeto y flags como `additionalProperties`, `deprecated`, `readOnly`, `writeOnly`). Los resúmenes de hijos exponen `key`, `path` normalizada, `type`, `required`, `hasChildren`, `reloadKind` opcional, más el `hint` / `hintPath` coincidente. - `update.run` ejecuta el flujo de actualización del Gateway y programa un reinicio solo cuando la actualización en sí tuvo éxito; los llamadores con una sesión pueden incluir `continuationMessage` para que el inicio reanude un turno de agente de seguimiento mediante la cola de continuación de reinicio. Las actualizaciones del gestor de paquetes y las actualizaciones supervisadas de checkout de git desde el plano de control usan una entrega a servicio administrado desacoplada en lugar de reemplazar el árbol de paquetes o mutar la salida de checkout/build dentro del Gateway en vivo. Una entrega iniciada devuelve `ok: true` con `result.reason: "managed-service-handoff-started"` y `handoff.status: "started"`; las entregas no disponibles o fallidas devuelven `ok: false` con `managed-service-handoff-unavailable` o `managed-service-handoff-failed`, más `handoff.command` cuando se requiere una actualización manual por shell. Una entrega no disponible significa que OpenClaw carece de un límite seguro de supervisor o una identidad de servicio durable, como `OPENCLAW_SYSTEMD_UNIT` para systemd. Durante una entrega iniciada, el centinela de reinicio puede informar brevemente `stats.reason: "restart-health-pending"`; la continuación se retrasa hasta que la CLI verifica el Gateway reiniciado y escribe el centinela final `ok`. - `update.status` actualiza y devuelve el centinela de reinicio de actualización más reciente, incluida la versión en ejecución posterior al reinicio cuando esté disponible. - `wizard.start`, `wizard.next`, `wizard.status` y `wizard.cancel` exponen el asistente de incorporación mediante WS RPC. - `agents.list` devuelve las entradas de agente configuradas, incluidos el modelo efectivo y los metadatos de runtime. - `agents.create`, `agents.update` y `agents.delete` gestionan los registros de agente y el cableado del espacio de trabajo. - `agents.files.list`, `agents.files.get` y `agents.files.set` gestionan los archivos de espacio de trabajo de arranque expuestos para un agente. - `tasks.list`, `tasks.get` y `tasks.cancel` exponen el registro de tareas del Gateway a los clientes de SDK y operador. - `artifacts.list`, `artifacts.get` y `artifacts.download` exponen resúmenes de artefactos derivados de transcripciones y descargas para un ámbito explícito de `sessionKey`, `runId` o `taskId`. Las consultas de ejecución y tarea resuelven la sesión propietaria en el servidor y solo devuelven medios de transcripción con procedencia coincidente; las fuentes de URL no seguras o locales devuelven descargas no compatibles en lugar de obtenerlas del lado del servidor. - `environments.list` y `environments.status` exponen el descubrimiento de entornos locales del Gateway y de nodos de solo lectura para clientes de SDK. - `agent.identity.get` devuelve la identidad efectiva del asistente para un agente o sesión. - `agent.wait` espera a que finalice una ejecución y devuelve la instantánea terminal cuando está disponible. - `sessions.list` devuelve el índice de sesiones actual, incluidos los metadatos `agentRuntime` por fila cuando hay configurado un backend de runtime de agente. - `sessions.subscribe` y `sessions.unsubscribe` activan o desactivan las suscripciones a eventos de cambios de sesión para el cliente WS actual. - `sessions.messages.subscribe` y `sessions.messages.unsubscribe` activan o desactivan las suscripciones a eventos de transcripción/mensaje para una sesión. - `sessions.preview` devuelve vistas previas acotadas de transcripciones para claves de sesión específicas. - `sessions.describe` devuelve una fila de sesión del Gateway para una clave de sesión exacta. - `sessions.resolve` resuelve o canoniza un destino de sesión. - `sessions.create` crea una nueva entrada de sesión. - `sessions.send` envía un mensaje a una sesión existente. - `sessions.steer` es la variante de interrupción y redirección para una sesión activa. - `sessions.abort` aborta el trabajo activo de una sesión. Un llamador puede pasar `key` más un `runId` opcional, o pasar solo `runId` para ejecuciones activas que el Gateway pueda resolver a una sesión. - `sessions.patch` actualiza metadatos/anulaciones de sesión e informa el modelo canónico resuelto más el `agentRuntime` efectivo. - `sessions.reset`, `sessions.delete` y `sessions.compact` realizan mantenimiento de sesión. - `sessions.get` devuelve la fila de sesión almacenada completa. - La ejecución de chat sigue usando `chat.history`, `chat.send`, `chat.abort` y `chat.inject`. `chat.history` se normaliza para visualización para clientes de UI: las etiquetas de directivas en línea se eliminan del texto visible, las cargas XML de llamadas a herramientas en texto plano (incluidos `...`, `...`, `...`, `...` y bloques truncados de llamadas a herramientas) y los tokens de control de modelo ASCII/ancho completo filtrados se eliminan, se omiten las filas de asistente que son tokens silenciosos puros, como exactamente `NO_REPLY` / `no_reply`, y las filas demasiado grandes pueden reemplazarse con marcadores de posición. - `chat.message.get` es el lector aditivo acotado de mensaje completo para una sola entrada visible de transcripción. Los clientes pasan `sessionKey`, `agentId` opcional cuando la selección de sesión está acotada al agente, más un `messageId` de transcripción expuesto previamente mediante `chat.history`, y el Gateway devuelve la misma proyección normalizada para visualización sin el límite de truncamiento del historial ligero cuando la entrada almacenada todavía está disponible y no es demasiado grande. - `chat.send` acepta `fastMode: "auto"` de un turno para usar el modo rápido en llamadas al modelo iniciadas antes del corte automático y luego iniciar llamadas posteriores de reintento, fallback, resultado de herramienta o continuación sin modo rápido. El corte predeterminado es de 60 segundos y puede configurarse por modelo con `agents.defaults.models["/"].params.fastAutoOnSeconds`. Un llamador de `chat.send` puede pasar `fastAutoOnSeconds` de un turno para anular el corte para esa solicitud. - `device.pair.list` devuelve dispositivos emparejados pendientes y aprobados. - `device.pair.setupCode` crea un código de configuración móvil y, de forma predeterminada, una URL de datos QR PNG. Requiere `operator.admin` y se omite intencionadamente del descubrimiento anunciado. El resultado incluye `setupCode`, `qrDataUrl` opcional, `gatewayUrl`, la etiqueta `auth` no secreta y `urlSource`. - `device.pair.approve`, `device.pair.reject` y `device.pair.remove` gestionan los registros de emparejamiento de dispositivos. - `device.token.rotate` rota un token de dispositivo emparejado dentro de los límites de su rol aprobado y ámbito del llamador. - `device.token.revoke` revoca un token de dispositivo emparejado dentro de los límites de su rol aprobado y ámbito del llamador. El código de configuración incrusta una credencial de arranque de corta duración. Los clientes no deben registrarla ni conservarla más allá del flujo de emparejamiento. - `node.pair.request`, `node.pair.list`, `node.pair.approve`, `node.pair.reject`, `node.pair.remove` y `node.pair.verify` cubren el emparejamiento de nodos y la verificación de arranque. - `node.list` y `node.describe` devuelven el estado de nodos conocidos/conectados. - `node.rename` actualiza una etiqueta de nodo emparejado. - `node.invoke` reenvía un comando a un nodo conectado. - `node.invoke.result` devuelve el resultado de una solicitud de invocación. - `node.event` transporta eventos originados por nodos de vuelta al gateway. - `node.pending.pull` y `node.pending.ack` son las API de cola de nodos conectados. - `node.pending.enqueue` y `node.pending.drain` gestionan trabajo pendiente duradero para nodos sin conexión/desconectados. - `exec.approval.request`, `exec.approval.get`, `exec.approval.list` y `exec.approval.resolve` cubren solicitudes de aprobación de exec de un solo uso más consulta/reproducción de aprobaciones pendientes. - `exec.approval.waitDecision` espera una aprobación de exec pendiente y devuelve la decisión final (o `null` al agotarse el tiempo de espera). - `exec.approvals.get` y `exec.approvals.set` gestionan instantáneas de política de aprobación de exec del gateway. - `exec.approvals.node.get` y `exec.approvals.node.set` gestionan la política de aprobación de exec local del nodo mediante comandos de relé de nodo. - `plugin.approval.request`, `plugin.approval.list`, `plugin.approval.waitDecision` y `plugin.approval.resolve` cubren flujos de aprobación definidos por plugins. - Automatización: `wake` programa una inyección de texto de activación inmediata o en el siguiente Heartbeat; `cron.get`, `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`, `cron.run`, `cron.runs` gestionan trabajo programado. - `cron.run` sigue siendo un RPC de estilo puesta en cola para ejecuciones manuales. Los clientes que necesiten semántica de finalización deben leer el `runId` devuelto y sondear `cron.runs`. - `cron.runs` acepta un filtro opcional no vacío de `runId` para que los clientes puedan seguir una ejecución manual en cola sin competir con otras entradas del historial del mismo trabajo. - Skills y herramientas: `commands.list`, `skills.*`, `tools.catalog`, `tools.effective`, `tools.invoke`. ### Familias de eventos comunes - `chat`: actualizaciones de chat de UI como `chat.inject` y otros eventos de chat solo de transcripción. En el protocolo v4, las cargas delta llevan `deltaText`; `message` sigue siendo la instantánea acumulativa del asistente. Los reemplazos sin prefijo establecen `replace=true` y usan `deltaText` como texto de reemplazo. - `session.message`, `session.operation` y `session.tool`: actualizaciones de transcripción, operación de sesión en curso y flujo de eventos para una sesión suscrita. - `sessions.changed`: cambió el índice de sesiones o los metadatos. - `presence`: actualizaciones de instantánea de presencia del sistema. - `tick`: evento periódico de keepalive / vivacidad. - `health`: actualización de instantánea de salud del gateway. - `heartbeat`: actualización de flujo de eventos de Heartbeat. - `cron`: evento de cambio de ejecución/trabajo de Cron. - `shutdown`: notificación de apagado del gateway. - `node.pair.requested` / `node.pair.resolved`: ciclo de vida del emparejamiento de nodos. - `node.invoke.request`: difusión de solicitud de invocación de nodo. - `device.pair.requested` / `device.pair.resolved`: ciclo de vida de dispositivo emparejado. - `voicewake.changed`: cambió la configuración del disparador de palabra de activación. - `exec.approval.requested` / `exec.approval.resolved`: ciclo de vida de aprobación de exec. - `plugin.approval.requested` / `plugin.approval.resolved`: ciclo de vida de aprobación de plugin. ### Métodos auxiliares de nodo - Los nodos pueden llamar a `skills.bins` para obtener la lista actual de ejecutables de Skills para comprobaciones de permiso automático. ### RPC del registro de tareas Los clientes operador pueden inspeccionar y cancelar registros de tareas en segundo plano del Gateway mediante los RPC del registro de tareas. Estos métodos devuelven resúmenes saneados de tareas, no el estado bruto del runtime. - `tasks.list` requiere `operator.read`. - Parámetros: `status` opcional (`"queued"`, `"running"`, `"completed"`, `"failed"`, `"cancelled"` o `"timed_out"`) o un arreglo de esos estados, `agentId` opcional, `sessionKey` opcional, `limit` opcional de `1` a `500` y cadena `cursor` opcional. - Resultado: `{ "tasks": TaskSummary[], "nextCursor"?: string }`. - `tasks.get` requiere `operator.read`. - Parámetros: `{ "taskId": string }`. - Resultado: `{ "task": TaskSummary }`. - Los ids de tarea faltantes devuelven la forma de error no encontrado del Gateway. - `tasks.cancel` requiere `operator.write`. - Parámetros: `{ "taskId": string, "reason"?: string }`. - Resultado: `{ "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }`. - `found` informa si el registro tenía una tarea coincidente. `cancelled` informa si el runtime aceptó o registró la cancelación. `TaskSummary` incluye `id`, `status` y metadatos opcionales como `kind`, `runtime`, `title`, `agentId`, `sessionKey`, `childSessionKey`, `ownerKey`, `runId`, `taskId`, `flowId`, `parentTaskId`, `sourceId`, marcas de tiempo, progreso, resumen terminal y texto de error saneado. `agentId` identifica al agente que ejecuta la tarea; `sessionKey` y `ownerKey` conservan el contexto del solicitante y de control. ### Métodos auxiliares de operador - Los operadores pueden llamar a `commands.list` (`operator.read`) para obtener el inventario de comandos en tiempo de ejecución para un agente. - `agentId` es opcional; omítelo para leer el espacio de trabajo del agente predeterminado. - `scope` controla a qué superficie apunta el `name` principal: - `text` devuelve el token de comando de texto principal sin la `/` inicial - `native` y la ruta predeterminada `both` devuelven nombres nativos conscientes del proveedor cuando están disponibles - `textAliases` contiene alias exactos con barra, como `/model` y `/m`. - `nativeName` contiene el nombre de comando nativo consciente del proveedor cuando existe. - `provider` es opcional y solo afecta la nomenclatura nativa y la disponibilidad de comandos nativos de Plugin. - `includeArgs=false` omite los metadatos de argumentos serializados de la respuesta. - Los operadores pueden llamar a `tools.catalog` (`operator.read`) para obtener el catálogo de herramientas en tiempo de ejecución para un agente. La respuesta incluye herramientas agrupadas y metadatos de procedencia: - `source`: `core` o `plugin` - `pluginId`: propietario del Plugin cuando `source="plugin"` - `optional`: si una herramienta de Plugin es opcional - Los operadores pueden llamar a `tools.effective` (`operator.read`) para obtener el inventario de herramientas efectivo en tiempo de ejecución para una sesión. - `sessionKey` es obligatorio. - El Gateway deriva contexto de ejecución confiable desde la sesión en el servidor en lugar de aceptar contexto de autenticación o entrega proporcionado por el llamador. - La respuesta es una proyección derivada por el servidor y delimitada a la sesión del inventario activo, incluidos core, Plugin, canal y herramientas de servidores MCP ya descubiertas. - `tools.effective` es de solo lectura para MCP: puede proyectar un catálogo MCP de sesión ya inicializado a través de la política final de herramientas, pero no crea runtimes MCP, no conecta transportes ni emite `tools/list`. Si no existe un catálogo ya inicializado coincidente, la respuesta puede incluir un aviso como `mcp-not-yet-connected`, `mcp-not-yet-listed` o `mcp-stale-catalog`. - Las entradas de herramientas efectivas usan `source="core"`, `source="plugin"`, `source="channel"` o `source="mcp"`. - Los operadores pueden llamar a `tools.invoke` (`operator.write`) para invocar una herramienta disponible a través de la misma ruta de política de Gateway que `/tools/invoke`. - `name` es obligatorio. `args`, `sessionKey`, `agentId`, `confirm` e `idempotencyKey` son opcionales. - Si `sessionKey` y `agentId` están presentes, el agente de sesión resuelto debe coincidir con `agentId`. - Los envoltorios core solo para propietarios, como `cron`, `gateway` y `nodes`, requieren identidad de propietario/administrador (`operator.admin`), aunque el método `tools.invoke` en sí sea `operator.write`. - La respuesta es un sobre orientado al SDK con `ok`, `toolName`, `output` opcional y campos `error` tipados. Las aprobaciones o rechazos de política devuelven `ok:false` en la carga útil en lugar de omitir la canalización de política de herramientas del Gateway. - Los operadores pueden llamar a `skills.status` (`operator.read`) para obtener el inventario visible de Skills para un agente. - `agentId` es opcional; omítelo para leer el espacio de trabajo del agente predeterminado. - La respuesta incluye elegibilidad, requisitos faltantes, comprobaciones de configuración y opciones de instalación saneadas sin exponer valores secretos sin procesar. - Los operadores pueden llamar a `skills.search` y `skills.detail` (`operator.read`) para metadatos de descubrimiento de ClawHub. - Los operadores pueden llamar a `skills.upload.begin`, `skills.upload.chunk` y `skills.upload.commit` (`operator.admin`) para preparar un archivo privado de skill antes de instalarlo. Esta es una ruta de carga de administrador separada para clientes confiables, no el flujo normal de instalación de Skills de ClawHub, y está deshabilitada de forma predeterminada a menos que `skills.install.allowUploadedArchives` esté habilitado. - `skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? })` crea una carga vinculada a ese slug y valor de force. - `skills.upload.chunk({ uploadId, offset, dataBase64 })` agrega bytes en el desplazamiento decodificado exacto. - `skills.upload.commit({ uploadId, sha256? })` verifica el tamaño final y el SHA-256. Commit solo finaliza la carga; no instala la skill. - Los archivos de Skills cargados son archivos zip que contienen una raíz `SKILL.md`. El nombre del directorio interno del archivo nunca selecciona el destino de instalación. - Los operadores pueden llamar a `skills.install` (`operator.admin`) en tres modos: - Modo ClawHub: `{ source: "clawhub", slug, version?, force? }` instala una carpeta de skill en el directorio `skills/` del espacio de trabajo del agente predeterminado. - Modo de carga: `{ source: "upload", uploadId, slug, force?, sha256?, timeoutMs? }` instala una carga confirmada en el directorio `skills/` del espacio de trabajo del agente predeterminado. El slug y el valor de force deben coincidir con la solicitud original de `skills.upload.begin`. Este modo se rechaza a menos que `skills.install.allowUploadedArchives` esté habilitado. La configuración no afecta las instalaciones de ClawHub. - Modo instalador de Gateway: `{ name, installId, timeoutMs? }` ejecuta una acción declarada `metadata.openclaw.install` en el host del Gateway. Los clientes más antiguos aún pueden enviar `dangerouslyForceUnsafeInstall`; este campo está obsoleto, se acepta solo por compatibilidad de protocolo y se ignora. Usa `security.installPolicy` para decisiones de instalación propiedad del operador. - Los operadores pueden llamar a `skills.update` (`operator.admin`) en dos modos: - El modo ClawHub actualiza un slug rastreado o todas las instalaciones rastreadas de ClawHub en el espacio de trabajo del agente predeterminado. - El modo de configuración parchea valores de `skills.entries.` como `enabled`, `apiKey` y `env`. ### Vistas de `models.list` `models.list` acepta un parámetro opcional `view`: - Omitido o `"default"`: comportamiento actual en tiempo de ejecución. Si `agents.defaults.models` está configurado, la respuesta es el catálogo permitido, incluidos modelos descubiertos dinámicamente para entradas `provider/*`. De lo contrario, la respuesta es el catálogo completo del Gateway. - `"configured"`: comportamiento con tamaño de selector. Si `agents.defaults.models` está configurado, aún prevalece, incluido el descubrimiento con ámbito de proveedor para entradas `provider/*`. Sin una lista de permitidos, la respuesta usa entradas explícitas de `models.providers.*.models`, recurriendo al catálogo completo solo cuando no existen filas de modelos configuradas. - `"all"`: catálogo completo del Gateway, omitiendo `agents.defaults.models`. Úsalo para diagnósticos e interfaces de descubrimiento, no para selectores de modelos normales. ## Aprobaciones de exec - Cuando una solicitud exec necesita aprobación, el Gateway transmite `exec.approval.requested`. - Los clientes operadores la resuelven llamando a `exec.approval.resolve` (requiere el alcance `operator.approvals`). - Para `host=node`, `exec.approval.request` debe incluir `systemRunPlan` (`argv`/`cwd`/`rawCommand` canónicos/metadatos de sesión). Las solicitudes sin `systemRunPlan` se rechazan. - Después de la aprobación, las llamadas reenviadas `node.invoke system.run` reutilizan ese `systemRunPlan` canónico como el contexto autoritativo de comando/cwd/sesión. - Si un llamador muta `command`, `rawCommand`, `cwd`, `agentId` o `sessionKey` entre la preparación y el reenvío final aprobado de `system.run`, el Gateway rechaza la ejecución en lugar de confiar en la carga útil mutada. ## Respaldo de entrega del agente - Las solicitudes `agent` pueden incluir `deliver=true` para solicitar entrega saliente. - `bestEffortDeliver=false` mantiene el comportamiento estricto: los destinos de entrega no resueltos o solo internos devuelven `INVALID_REQUEST`. - `bestEffortDeliver=true` permite recurrir a la ejecución solo de sesión cuando no se puede resolver una ruta entregable externa (por ejemplo, sesiones internas/webchat o configuraciones multicanal ambiguas). - Los resultados finales de `agent` pueden incluir `result.deliveryStatus` cuando se solicitó entrega, usando los mismos estados `sent`, `suppressed`, `partial_failed` y `failed` documentados para [`openclaw agent --json --deliver`](/es/cli/agent#json-delivery-status). ## Versionado - `PROTOCOL_VERSION` vive en `packages/gateway-protocol/src/version.ts`. - Los clientes envían `minProtocol` + `maxProtocol`; el servidor rechaza rangos que no incluyan su protocolo actual. Los clientes y servidores actuales requieren el protocolo v4. - Los esquemas + modelos se generan a partir de definiciones TypeBox: - `pnpm protocol:gen` - `pnpm protocol:gen:swift` - `pnpm protocol:check` ### Constantes del cliente El cliente de referencia en `src/gateway/client.ts` usa estos valores predeterminados. Los valores son estables en el protocolo v4 y son la línea base esperada para clientes de terceros. | Constante | Valor predeterminado | Fuente | | ----------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------- | | `PROTOCOL_VERSION` | `4` | `packages/gateway-protocol/src/version.ts` | | `MIN_CLIENT_PROTOCOL_VERSION` | `4` | `packages/gateway-protocol/src/version.ts` | | Tiempo de espera de solicitud (por RPC) | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) | | Tiempo de espera de preauth / connect-challenge | `15_000` ms | `src/gateway/handshake-timeouts.ts` (config/env pueden aumentar el presupuesto emparejado de servidor/cliente) | | Backoff de reconexión inicial | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) | | Backoff máximo de reconexión | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) | | Límite de reintento rápido después del cierre por device-token | `250` ms | `src/gateway/client.ts` | | Gracia de force-stop antes de `terminate()` | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` | | Tiempo de espera predeterminado de `stopAndWait()` | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` | | Intervalo de tick predeterminado (antes de `hello-ok`) | `30_000` ms | `src/gateway/client.ts` | | Cierre por tiempo de espera de tick | código `4000` cuando el silencio supera `tickIntervalMs * 2` | `src/gateway/client.ts` | | `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 MB) | `src/gateway/server-constants.ts` | El servidor anuncia los valores efectivos de `policy.tickIntervalMs`, `policy.maxPayload` y `policy.maxBufferedBytes` en `hello-ok`; los clientes deben respetar esos valores en lugar de los valores predeterminados previos al handshake. ## Auth - La autenticación del Gateway con secreto compartido usa `connect.params.auth.token` o `connect.params.auth.password`, según el modo de autenticación configurado. - Los modos que llevan identidad, como Tailscale Serve (`gateway.auth.allowTailscale: true`) o `gateway.auth.mode: "trusted-proxy"` sin local loopback satisfacen la comprobación de autenticación de conexión desde los encabezados de solicitud en lugar de `connect.params.auth.*`. - `gateway.auth.mode: "none"` con entrada privada omite por completo la autenticación de conexión con secreto compartido; no expongas ese modo en una entrada pública o no confiable. - Después del emparejamiento, el Gateway emite un **token de dispositivo** limitado al rol de conexión + los ámbitos. Se devuelve en `hello-ok.auth.deviceToken` y el cliente debe persistirlo para conexiones futuras. - Los clientes deben persistir el `hello-ok.auth.deviceToken` principal después de cualquier conexión correcta. - Al reconectar con ese token de dispositivo **almacenado**, también se debe reutilizar el conjunto de ámbitos aprobado almacenado para ese token. Esto conserva el acceso de lectura/sondeo/estado que ya se concedió y evita reducir silenciosamente las reconexiones a un ámbito implícito más estrecho solo de administrador. - Ensamblado de autenticación de conexión del lado del cliente (`selectConnectAuth` en `src/gateway/client.ts`): - `auth.password` es ortogonal y siempre se reenvía cuando está establecido. - `auth.token` se rellena por orden de prioridad: primero el token compartido explícito, luego un `deviceToken` explícito, y después un token por dispositivo almacenado (indexado por `deviceId` + `role`). - `auth.bootstrapToken` se envía solo cuando nada de lo anterior resolvió un `auth.token`. Un token compartido o cualquier token de dispositivo resuelto lo suprime. - La promoción automática de un token de dispositivo almacenado en el reintento único `AUTH_TOKEN_MISMATCH` está limitada a **endpoints confiables**: loopback, o `wss://` con un `tlsFingerprint` fijado. `wss://` público sin fijación no cumple los requisitos. - El arranque integrado con código de configuración devuelve el `hello-ok.auth.deviceToken` del nodo principal más un token de operador acotado en `hello-ok.auth.deviceTokens` para transferencia móvil confiable. El token de operador incluye `operator.talk.secrets` para lecturas de configuración nativa de Talk, pero excluye ámbitos de mutación de emparejamiento y `operator.admin`. - Mientras un arranque con código de configuración no base espera aprobación, los detalles de `PAIRING_REQUIRED` incluyen `recommendedNextStep: "wait_then_retry"`, `retryable: true` y `pauseReconnect: false`. Los clientes deben seguir reconectando con el mismo token de arranque hasta que se apruebe la solicitud o el token deje de ser válido. - Persiste `hello-ok.auth.deviceTokens` solo cuando la conexión usó autenticación de arranque en un transporte confiable como `wss://` o emparejamiento por loopback/local. - Si un cliente proporciona un `deviceToken` **explícito** o `scopes` explícitos, ese conjunto de ámbitos solicitado por el llamador sigue siendo autoritativo; los ámbitos en caché solo se reutilizan cuando el cliente reutiliza el token por dispositivo almacenado. - Los tokens de dispositivo pueden rotarse/revocarse mediante `device.token.rotate` y `device.token.revoke` (requiere el ámbito `operator.pairing`). Rotar o revocar un nodo u otro rol que no sea de operador también requiere `operator.admin`. - `device.token.rotate` devuelve metadatos de rotación. Solo refleja el token portador de reemplazo para llamadas del mismo dispositivo que ya están autenticadas con ese token de dispositivo, para que los clientes solo con token puedan persistir su reemplazo antes de reconectar. Las rotaciones compartidas/de administrador no reflejan el token portador. - La emisión, rotación y revocación de tokens permanecen acotadas al conjunto de roles aprobado registrado en la entrada de emparejamiento de ese dispositivo; la mutación de tokens no puede ampliar ni apuntar a un rol de dispositivo que la aprobación de emparejamiento nunca concedió. - Para sesiones de token de dispositivo emparejado, la administración de dispositivos tiene ámbito propio salvo que el llamador también tenga `operator.admin`: los llamadores que no son administradores solo pueden administrar el token de operador de la entrada de su **propio** dispositivo. La administración de tokens de nodo y otros que no sean de operador es solo para administradores, incluso para el propio dispositivo del llamador. - `device.token.rotate` y `device.token.revoke` también comprueban el conjunto de ámbitos del token de operador objetivo contra los ámbitos de sesión actuales del llamador. Los llamadores que no son administradores no pueden rotar ni revocar un token de operador más amplio que el que ya poseen. - Los fallos de autenticación incluyen `error.details.code` más sugerencias de recuperación: - `error.details.canRetryWithDeviceToken` (booleano) - `error.details.recommendedNextStep` (`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`) - Comportamiento del cliente para `AUTH_TOKEN_MISMATCH`: - Los clientes confiables pueden intentar un reintento acotado con un token por dispositivo en caché. - Si ese reintento falla, los clientes deben detener los bucles de reconexión automática y mostrar orientación de acción para el operador. - `AUTH_SCOPE_MISMATCH` significa que el token de dispositivo fue reconocido, pero no cubre el rol/los ámbitos solicitados. Los clientes no deben presentarlo como un token incorrecto; solicita al operador que vuelva a emparejar o que apruebe el contrato de ámbitos más estrecho/amplio. ## Identidad de dispositivo + emparejamiento - Los nodos deben incluir una identidad de dispositivo estable (`device.id`) derivada de una huella digital de par de claves. - Los Gateways emiten tokens por dispositivo + rol. - Las aprobaciones de emparejamiento son necesarias para nuevos ID de dispositivo salvo que la aprobación automática local esté habilitada. - La aprobación automática de emparejamiento se centra en conexiones directas de local loopback. - OpenClaw también tiene una ruta estrecha de autoconexión local al backend/contenedor para flujos auxiliares confiables con secreto compartido. - Las conexiones de tailnet o LAN del mismo host siguen tratándose como remotas para el emparejamiento y requieren aprobación. - Los clientes WS normalmente incluyen identidad `device` durante `connect` (operador + nodo). Las únicas excepciones de operador sin dispositivo son rutas de confianza explícitas: - `gateway.controlUi.allowInsecureAuth=true` para compatibilidad HTTP insegura solo en localhost. - autenticación correcta del operador de la Control UI con `gateway.auth.mode: "trusted-proxy"`. - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (ruptura de emergencia, degradación grave de seguridad). - RPCs de backend `gateway-client` por loopback directo en la ruta auxiliar interna reservada. - Omitir la identidad de dispositivo tiene consecuencias de ámbito. Cuando se permite una conexión de operador sin dispositivo mediante una ruta de confianza explícita, OpenClaw aun así borra los ámbitos autodeclarados a un conjunto vacío salvo que esa ruta tenga una excepción nombrada de preservación de ámbitos. Los métodos protegidos por ámbito entonces fallan con `missing scope`. - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` es una ruta de preservación de ámbitos de ruptura de emergencia para la Control UI. No concede ámbitos a clientes WebSocket personalizados arbitrarios con forma de backend o CLI. - La ruta auxiliar de backend `gateway-client` reservada por loopback directo preserva ámbitos solo para RPCs internas del plano de control local; los ID de backend personalizados no reciben esta excepción. - Todas las conexiones deben firmar el nonce `connect.challenge` proporcionado por el servidor. ### Diagnósticos de migración de autenticación de dispositivo Para clientes heredados que aún usan el comportamiento de firma anterior al desafío, `connect` ahora devuelve códigos de detalle `DEVICE_AUTH_*` bajo `error.details.code` con un `error.details.reason` estable. Fallos comunes de migración: | Mensaje | details.code | details.reason | Significado | | --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- | | `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | El cliente omitió `device.nonce` (o lo envió vacío). | | `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | El cliente firmó con un nonce obsoleto/incorrecto. | | `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | La carga útil de la firma no coincide con la carga útil v2. | | `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | La marca de tiempo firmada está fuera del desfase permitido. | | `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` no coincide con la huella digital de la clave pública. | | `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Falló el formato/canonicalización de la clave pública. | Objetivo de migración: - Espera siempre `connect.challenge`. - Firma la carga útil v2 que incluye el nonce del servidor. - Envía el mismo nonce en `connect.params.device.nonce`. - La carga útil de firma preferida es `v3`, que vincula `platform` y `deviceFamily` además de los campos de dispositivo/cliente/rol/ámbitos/token/nonce. - Las firmas heredadas `v2` siguen aceptándose por compatibilidad, pero la fijación de metadatos de dispositivo emparejado aún controla la política de comandos al reconectar. ## TLS + fijación - TLS es compatible con conexiones WS. - Los clientes pueden fijar opcionalmente la huella digital del certificado del Gateway (consulta la configuración `gateway.tls` más `gateway.remote.tlsFingerprint` o la CLI `--tls-fingerprint`). ## Ámbito Este protocolo expone la **API completa del gateway** (estado, canales, modelos, chat, agente, sesiones, nodos, aprobaciones, etc.). La superficie exacta la definen los esquemas TypeBox en `packages/gateway-protocol/src/schema.ts`. ## Relacionado - [Protocolo de puente](/es/gateway/bridge-protocol) - [Runbook del Gateway](/es/gateway)