Web interfaces

WebChat

Estado: la interfaz de chat SwiftUI de macOS/iOS se comunica directamente con el WebSocket del Gateway. No hay ningún navegador integrado ni servidor estático local.

Qué es

Una interfaz de chat nativa para el Gateway.
Utiliza las mismas sesiones y reglas de enrutamiento que otros canales.
Enrutamiento determinista: las respuestas siempre vuelven a WebChat.
El historial siempre se obtiene del Gateway (sin supervisión de archivos locales). Si no se puede acceder al Gateway, WebChat es de solo lectura.

Inicio rápido

Inicie el Gateway.
Abra la interfaz de WebChat (aplicación para macOS/iOS) o la pestaña de chat de la interfaz de control.
Asegúrese de que haya configurada una ruta de autenticación válida para el Gateway (secreto compartido de forma predeterminada, incluso en loopback).

Cómo funciona

La interfaz se conecta al WebSocket del Gateway y utiliza los métodos RPC chat.history, chat.send, chat.inject y chat.message.get.
chat.history está limitado para garantizar la estabilidad: el Gateway puede truncar campos de texto largos, omitir metadatos pesados y sustituir las entradas demasiado grandes por [chat.history omitted: message too large]. Los clientes de API pueden enviar un maxChars por solicitud para anular el límite predeterminado en una llamada.
Cuando un mensaje visible del asistente se ha truncado en chat.history, la interfaz de control puede abrir un lector lateral y obtener bajo demanda la entrada completa normalizada para su visualización mediante chat.message.get, sin aumentar la carga útil predeterminada del historial. chat.message.get utiliza la misma rama de la transcripción y las mismas reglas de visualización que chat.history, pero selecciona una entrada mediante messageId y devuelve un motivo veraz de indisponibilidad cuando ya no se puede devolver el contenido completo.
chat.history sigue la rama activa de la transcripción en los archivos de sesión de solo adición, por lo que las ramas de reescritura abandonadas y las copias de prompts sustituidas no se muestran en WebChat.
Las entradas de Compaction se muestran como un separador «Historial compactado» que explica que la transcripción compactada se conserva como punto de control, con una acción para abrir los puntos de control de la sesión (crear una rama o restaurar, cuando los permisos lo permitan).
La interfaz de control recuerda el sessionId subyacente del Gateway devuelto por chat.history y lo incluye en las llamadas posteriores a chat.send, por lo que las reconexiones y las actualizaciones de la página continúan la misma conversación almacenada, a menos que se inicie o restablezca una sesión.
Los envíos en primer plano también incluyen la hoja de la rama mostrada del historial renderizado como expectedLeafEntryId; si otro cliente cambió de rama primero, la interfaz de control retiene el mensaje para su revisión y actualiza la transcripción en lugar de publicarlo en la nueva rama. Las repeticiones tras una reconexión o desde la bandeja de salida restaurada omiten intencionadamente esta condición previa después de conciliar el historial actual.
chat.send acepta una clave de idempotencia (la interfaz de control utiliza el identificador de ejecución); el Gateway deduplica las solicitudes repetidas que reutilizan la misma clave, por lo que los reintentos o envíos duplicados en curso de la misma sesión, mensaje y archivos adjuntos no crean una segunda ejecución.
Responder a un mensaje específico (clic derecho → Reply) envía el identificador de transcripción del destino como replyToId en chat.send. El Gateway resuelve ese mensaje a partir del historial de la sesión y completa los mismos metadatos de contexto de respuesta independientes del canal que utilizan las respuestas de Discord: los agentes ven has_reply_context y el bloque no confiable «Objetivo de respuesta del mensaje actual del usuario» con la etiqueta del remitente y el cuerpo. (Los prompts de WebChat siguen omitiendo los identificadores volátiles de conversaciones, como reply_to_id, de acuerdo con la política vigente de prompts estables a nivel de bytes para las sesiones directas de WebChat). Los destinos de respuesta sin un identificador de transcripción persistente (por ejemplo, los envíos pendientes) recurren a una cita insertada en el cuerpo del mensaje.
Los archivos de inicio del espacio de trabajo y las instrucciones BOOTSTRAP.md pendientes se proporcionan mediante la sección # Project Context del prompt del sistema del agente, en lugar de copiarse en el mensaje de usuario de WebChat. Si se trunca el contenido de arranque, el prompt del sistema recibe en su lugar un breve «Aviso de contexto de arranque»; los recuentos detallados y las opciones de configuración permanecen en las superficies de diagnóstico.
La normalización de visualización de chat.history elimina: el contexto de OpenClaw exclusivo del entorno de ejecución, los envoltorios de los mensajes entrantes, las etiquetas insertadas de directivas de entrega, como [[reply_to_current]], [[reply_to:<id>]] y [[audio_as_voice]], las cargas útiles XML en texto sin formato de llamadas a herramientas (<tool_call>, <function_call>, <tool_calls>, <function_calls>, incluidos los bloques truncados) y los tokens de control del modelo ASCII o de ancho completo filtrados. Se omiten las entradas del asistente cuyo único texto visible sea el token silencioso NO_REPLY (sin distinguir mayúsculas y minúsculas).
Las cargas útiles de respuesta marcadas como razonamiento (isReasoning: true) se excluyen del contenido del asistente de WebChat, del texto reproducido de la transcripción y de los bloques de contenido de audio, para que las cargas útiles que solo contienen razonamiento no aparezcan como mensajes visibles del asistente ni como audio reproducible.
chat.inject añade una nota del asistente directamente a la transcripción y la transmite a la interfaz (sin ejecutar el agente).
Las ejecuciones canceladas pueden mantener visible en la interfaz la salida parcial del asistente. El Gateway conserva ese texto parcial en el historial de la transcripción cuando existe una salida en búfer y marca la entrada con metadatos de cancelación.

Modelo de transcripción y entrega

WebChat tiene dos rutas de datos independientes:

Las filas de la transcripción de SQLite son la transcripción duradera del modelo y el entorno de ejecución. En las ejecuciones normales del agente, el entorno de ejecución integrado de OpenClaw conserva los mensajes user, assistant y toolResult visibles para el modelo mediante el descriptor de acceso a la sesión. WebChat no escribe texto arbitrario de entrega, estado o ayuda en esa transcripción.
Los eventos ReplyPayload del Gateway son la proyección de entrega en tiempo real: se normalizan para su visualización en WebChat o el canal, la transmisión por bloques, las etiquetas de directivas, la incorporación de contenido multimedia, los indicadores de TTS/audio y el comportamiento alternativo de la interfaz. No constituyen por sí mismos el registro canónico de la sesión.
Los arneses que requieren respuestas visibles mediante tools.message siguen utilizando WebChat como destino interno de las respuestas de origen de la ejecución actual. Un message.send sin destino procedente de esa ejecución activa de WebChat se proyecta en el mismo chat y se refleja en la transcripción de la sesión; WebChat no se convierte en un canal de salida reutilizable y nunca hereda lastChannel.
WebChat inserta entradas del asistente en la transcripción únicamente cuando el Gateway es propietario de un mensaje mostrado fuera de un turno normal del agente integrado: chat.inject, respuestas a comandos no generadas por el agente, salida parcial cancelada y complementos de transcripción multimedia gestionados por WebChat.
Si aparece texto del asistente en tiempo real durante una ejecución, pero desaparece tras volver a cargar el historial, compruebe en este orden: si la transcripción de SQLite contiene el texto del asistente, si la proyección de visualización chat.history lo eliminó y, después, si la combinación de la cola optimista de la interfaz de control sustituyó el estado local de entrega por la instantánea persistente.

Las respuestas finales de las ejecuciones normales del agente deberían ser duraderas porque el entorno de ejecución integrado escribe el message_end del asistente. Cualquier mecanismo alternativo que refleje una carga útil final entregada en la transcripción debe evitar primero duplicar un turno del asistente que el entorno de ejecución integrado ya haya escrito.

Panel de herramientas de agentes de la interfaz de control

El panel de herramientas /agents de la interfaz de control incluye una vista «Disponible ahora» respaldada por tools.effective(sessionKey=...): una proyección de solo lectura derivada del servidor del inventario de herramientas de la sesión actual, incluidas las herramientas principales, de plugins, propiedad de los canales y de servidores MCP ya descubiertos.
Una vista independiente para editar la configuración (respaldada por tools.catalog) abarca los perfiles, las anulaciones por agente y la semántica del catálogo.
La disponibilidad del entorno de ejecución se limita a la sesión. Cambiar de sesión en el mismo agente puede modificar la lista «Disponible ahora». Si los servidores MCP configurados no se han conectado o han cambiado desde el último descubrimiento, el panel muestra un aviso en lugar de iniciar silenciosamente los transportes MCP desde la ruta de lectura.
El editor de configuración no implica disponibilidad en el entorno de ejecución; el acceso efectivo sigue la precedencia de las políticas (allow/deny, anulaciones por agente y por proveedor/canal).

Uso remoto

El modo remoto crea un túnel para el WebSocket del Gateway mediante SSH/Tailscale.
No es necesario ejecutar un servidor de WebChat independiente.

Referencia de configuración (WebChat)

Configuración completa: Configuración

WebChat no tiene una sección de configuración persistente. El Gateway utiliza el límite de visualización integrado chat.history; los clientes de API pueden enviar maxChars por solicitud para anularlo en una sola llamada. La configuración heredada channels.webchat y gateway.webchat está retirada; ejecute openclaw doctor --fix para eliminarla.

Opciones globales relacionadas:

gateway.port, gateway.bind: host/puerto del WebSocket.
gateway.auth.mode, gateway.auth.token, gateway.auth.password: autenticación del WebSocket mediante secreto compartido.
gateway.auth.allowTailscale: la pestaña de chat de la interfaz de control del navegador puede utilizar los encabezados de identidad de Tailscale Serve cuando están habilitados.
gateway.auth.mode: "trusted-proxy": autenticación de proxy inverso para clientes de navegador detrás de un origen de proxy sin loopback que reconoce identidades (consulte Autenticación mediante proxy de confianza).
gateway.remote.url, gateway.remote.token, gateway.remote.password: destino remoto del Gateway.
session.*: almacenamiento de sesiones y valores predeterminados de la clave principal.

Temas relacionados

Was this useful?