TUI

# Inicio rápido

# Modo Gateway

1. Inicia el Gateway.

openclaw gateway

2. Abre la TUI.

openclaw tui

3. Escribe un mensaje y pulsa Intro.

Gateway remoto:

openclaw tui --url ws://<host>:<port> --token <gateway-token>

Usa --password si tu Gateway usa autenticación con contraseña.

# Modo local

Ejecuta la TUI sin un Gateway:

openclaw chat
# or
openclaw tui --local

Notas:

• openclaw chat y openclaw terminal son alias de openclaw tui --local.
• --local no se puede combinar con --url, --token ni --password.
• El modo local usa directamente el runtime de agente integrado. La mayoría de las herramientas locales funcionan, pero las funciones exclusivas de Gateway no están disponibles.
• openclaw y openclaw crestodian también usan este shell de TUI, con Crestodian como backend local de chat de configuración y reparación.

# Qué ves

• Encabezado: URL de conexión, agente actual, sesión actual.
• Registro de chat: mensajes del usuario, respuestas del asistente, avisos del sistema, tarjetas de herramientas.
• Línea de estado: estado de conexión/ejecución (conectando, ejecutando, transmitiendo, inactivo, error).
• Pie: estado de conexión + agente + sesión + modelo + pensar/rápido/detallado/traza/razonamiento + recuentos de tokens + entrega.
• Entrada: editor de texto con autocompletado.

# Modelo mental: agentes + sesiones

• Los agentes son slugs únicos (por ejemplo, main, research). El Gateway expone la lista.
• Las sesiones pertenecen al agente actual.
• Las claves de sesión se almacenan como agent:<agentId>:<sessionKey>.
  • Si escribes /session main, la TUI lo expande a agent:<currentAgent>:main.
  • Si escribes /session agent:other:main, cambias explícitamente a esa sesión de agente.
• Alcance de sesión:
  • per-sender (predeterminado): cada agente tiene muchas sesiones.
  • global: la TUI siempre usa la sesión global (el selector puede estar vacío).
• El agente + la sesión actuales siempre están visibles en el pie.
• Cuando se inicia sin --session, la TUI en modo Gateway reanuda la última sesión seleccionada para el mismo gateway, agente y alcance de sesión si esa sesión aún existe. Pasar --session, /session, /new o /reset sigue siendo explícito.

# Envío + entrega

• Los mensajes se envían al Gateway; la entrega a proveedores está desactivada de forma predeterminada.
• Activa la entrega:
  • /deliver on
  • o el panel de Configuración
  • o inicia con openclaw tui --deliver

# Selectores + superposiciones

• Selector de modelo: lista los modelos disponibles y establece la anulación de sesión.
• Selector de agente: elige otro agente.
• Selector de sesión: muestra hasta 50 sesiones del agente actual actualizadas en los últimos 7 días. Usa /session <key> para saltar a una sesión conocida más antigua.
• Configuración: alterna la entrega, la expansión de salida de herramientas y la visibilidad del pensamiento.

# Atajos de teclado

• Intro: enviar mensaje
• Esc: abortar ejecución activa
• Ctrl+C: borrar entrada (púlsalo dos veces para salir)
• Ctrl+D: salir
• Ctrl+L: selector de modelo
• Ctrl+G: selector de agente
• Ctrl+P: selector de sesión
• Ctrl+O: alternar expansión de salida de herramientas
• Ctrl+T: alternar visibilidad del pensamiento (recarga el historial)

# Comandos slash

Núcleo:

• /help
• /status
• /agent <id> (o /agents)
• /session <key> (o /sessions)
• /model <provider/model> (o /models)

Controles de sesión:

• /think <off|minimal|low|medium|high>
• /fast <status|on|off>
• /verbose <on|full|off>
• /trace <on|off>
• /reasoning <on|off|stream>
• /usage <off|tokens|full>
• /elevated <on|off|ask|full> (alias: /elev)
• /activation <mention|always>
• /deliver <on|off>

Ciclo de vida de sesión:

• /new o /reset (restablecer la sesión)
• /abort (abortar la ejecución activa)
• /settings
• /exit

Solo en modo local:

• /auth [provider] abre el flujo de autenticación/inicio de sesión del proveedor dentro de la TUI.

Otros comandos slash de Gateway (por ejemplo, /context) se reenvían al Gateway y se muestran como salida del sistema. Consulta Comandos slash.

# Comandos de shell locales

• Añade el prefijo ! a una línea para ejecutar un comando de shell local en el host de la TUI.
• La TUI solicita una vez por sesión permitir la ejecución local; si se rechaza, ! queda desactivado para la sesión.
• Los comandos se ejecutan en un shell nuevo, no interactivo, en el directorio de trabajo de la TUI (sin cd/env persistente).
• Los comandos de shell locales reciben OPENCLAW_SHELL=tui-local en su entorno.
• Un ! solo se envía como mensaje normal; los espacios iniciales no activan la ejecución local.

# Reparar configuraciones desde la TUI local

Usa el modo local cuando la configuración actual ya se valida y quieres que el agente integrado la inspeccione en la misma máquina, la compare con la documentación y ayude a reparar desviaciones sin depender de un Gateway en ejecución.

Si openclaw config validate ya está fallando, empieza primero con openclaw configure o openclaw doctor --fix. openclaw chat no omite la protección de configuración no válida.

Bucle típico:

1. Inicia el modo local:

openclaw chat

2. Pide al agente qué quieres comprobar, por ejemplo:

Compare my gateway auth config with the docs and suggest the smallest fix.

3. Usa comandos de shell locales para obtener evidencia exacta y validación:

!openclaw config file
!openclaw docs gateway auth token secretref
!openclaw config validate
!openclaw doctor

4. Aplica cambios acotados con openclaw config set o openclaw configure, y luego vuelve a ejecutar !openclaw config validate.
5. Si Doctor recomienda una migración o reparación automática, revísala y ejecuta !openclaw doctor --fix.

Consejos:

• Prefiere openclaw config set o openclaw configure antes que editar openclaw.json a mano.
• openclaw docs "<query>" busca en el índice de documentación en vivo desde la misma máquina.
• openclaw config validate --json es útil cuando quieres errores estructurados de esquema y de SecretRef/resolución.

# Salida de herramientas

• Las llamadas a herramientas se muestran como tarjetas con argumentos + resultados.
• Ctrl+O alterna entre vistas contraídas/expandidas.
• Mientras las herramientas se ejecutan, las actualizaciones parciales se transmiten en la misma tarjeta.

# Colores de terminal

• La TUI mantiene el texto del cuerpo del asistente en el color de primer plano predeterminado de tu terminal para que los terminales oscuros y claros sigan siendo legibles.
• Si tu terminal usa un fondo claro y la detección automática es incorrecta, establece OPENCLAW_THEME=light antes de iniciar openclaw tui.
• Para forzar en su lugar la paleta oscura original, establece OPENCLAW_THEME=dark.

# Historial + streaming

• Al conectarse, la TUI carga el historial más reciente (predeterminado: 200 mensajes).
• Las respuestas en streaming se actualizan en el mismo lugar hasta finalizar.
• La TUI también escucha eventos de herramientas del agente para tarjetas de herramientas más completas.

# Detalles de conexión

• La TUI se registra con el Gateway como mode: "tui".
• Las reconexiones muestran un mensaje del sistema; los vacíos de eventos se muestran en el registro.

# Opciones

• --local: Ejecutar contra el runtime de agente local integrado
• --url <url>: URL WebSocket de Gateway (usa de forma predeterminada la configuración o ws://127.0.0.1:<port>)
• --token <token>: Token de Gateway (si se requiere)
• --password <password>: Contraseña de Gateway (si se requiere)
• --session <key>: Clave de sesión (predeterminada: main, o global cuando el alcance es global)
• --deliver: Entregar respuestas del asistente al proveedor (desactivado de forma predeterminada)
• --thinking <level>: Anular el nivel de pensamiento para los envíos
• --message <text>: Enviar un mensaje inicial después de conectarse
• --timeout-ms <ms>: Tiempo de espera del agente en ms (usa de forma predeterminada agents.defaults.timeoutSeconds)
• --history-limit <n>: Entradas de historial que cargar (predeterminado 200)

# Solución de problemas

No hay salida después de enviar un mensaje:

• Ejecuta /status en la TUI para confirmar que el Gateway está conectado e inactivo/ocupado.
• Revisa los registros del Gateway: openclaw logs --follow.
• Confirma que el agente puede ejecutarse: openclaw status y openclaw models status.
• Si esperas mensajes en un canal de chat, activa la entrega (/deliver on o --deliver).

# Solución de problemas de conexión

• disconnected: asegúrate de que el Gateway esté en ejecución y de que tu --url/--token/--password sea correcto.
• No hay agentes en el selector: revisa openclaw agents list y tu configuración de enrutamiento.
• Selector de sesión vacío: puede que estés en alcance global o que aún no tengas sesiones.

# Relacionado

• UI de control — interfaz de control basada en web
• Configuración — inspeccionar, validar y editar openclaw.json
• Doctor — comprobaciones guiadas de reparación y migración
• Referencia de CLI — referencia completa de comandos de CLI