TUI

Avvio rapido

Modalità Gateway

1. Avvia il Gateway.

openclaw gateway

2. Apri la TUI.

openclaw tui

3. Digita un messaggio e premi Invio.

Gateway remoto:

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

Usa --password se il tuo Gateway usa l'autenticazione con password.

Modalità locale

Esegui la TUI senza un Gateway:

openclaw chat# oropenclaw tui --local

Note:

• openclaw chat e openclaw terminal sono alias di openclaw tui --local.
• --local non può essere combinato con --url, --token o --password.
• La modalità locale usa direttamente il runtime agente incorporato. La maggior parte degli strumenti locali funziona, ma le funzionalità disponibili solo tramite Gateway non sono disponibili.
• Dopo che un file di configurazione contiene impostazioni definite, anche openclaw e openclaw crestodian usano questa shell TUI, con Crestodian come backend di chat locale per configurazione e riparazione.

Cosa vedi

• Intestazione: URL di connessione, agente corrente, sessione corrente.
• Registro chat: messaggi utente, risposte dell'assistente, avvisi di sistema, schede degli strumenti.
• Riga di stato: stato della connessione/esecuzione (connessione in corso, in esecuzione, streaming, inattivo, errore).
• Piè di pagina: agente + sessione + modello + stato dell'obiettivo + think/fast/verbose/trace/reasoning + conteggi dei token + consegna. Quando tui.footer.showRemoteHost è abilitato, le connessioni Gateway remote mostrano anche l'host della connessione.
• Input: editor di testo con completamento automatico.

Modello mentale: agenti + sessioni

• Gli agenti sono slug univoci (ad esempio main, research). Il Gateway espone l'elenco.

• Le sessioni appartengono all'agente corrente.

• Le chiavi di sessione vengono archiviate come agent:<agentId>:<sessionKey>.

  • Se digiti /session main, la TUI la espande in agent:<currentAgent>:main.
  • Se digiti /session agent:other:main, passi esplicitamente a quella sessione agente.

• Ambito della sessione:

  • per-sender (predefinito): ogni agente ha molte sessioni.
  • global: la TUI usa sempre la sessione global (il selettore può essere vuoto).

• L'agente + la sessione correnti sono sempre visibili nel piè di pagina.

• Per mostrare l'host del Gateway per connessioni non locali basate su URL, abilitalo con:

  openclaw config set tui.footer.showRemoteHost true

  Le connessioni loopback e locali incorporate non mostrano mai un'etichetta host.

• Se la sessione ha un obiettivo, il piè di pagina mostra il suo stato compatto come Pursuing goal, Goal paused (/goal resume) o Goal achieved.

• Quando viene avviata senza --session, la TUI in modalità gateway riprende l'ultima sessione selezionata per lo stesso gateway, agente e ambito di sessione, se quella sessione esiste ancora. Passare --session, /session, /new o /reset resta esplicito.

Invio + consegna

• I messaggi vengono inviati al Gateway; la consegna ai provider è disattivata per impostazione predefinita.
• La TUI è una superficie sorgente interna come WebChat, non un canale in uscita generico. Gli harness che richiedono tools.message per risposte visibili possono soddisfare il turno TUI attivo con un message.send senza destinazione; la consegna esplicita al provider usa comunque i normali canali configurati e non ripiega mai su lastChannel.
• Attiva la consegna:
  • /deliver on
  • oppure il pannello Impostazioni
  • oppure avvia con openclaw tui --deliver

Selettori + overlay

• Selettore modello: elenca i modelli disponibili e imposta l'override della sessione.
• Selettore agente: scegli un agente diverso.
• Selettore sessione: mostra fino a 50 sessioni per l'agente corrente aggiornate negli ultimi 7 giorni. Usa /session <key> per passare a una sessione nota più vecchia.
• Impostazioni: attiva/disattiva consegna, espansione dell'output degli strumenti e visibilità del ragionamento.

Scorciatoie da tastiera

• Invio: invia messaggio
• Esc: interrompi l'esecuzione attiva
• Ctrl+C: cancella input (premi due volte per uscire)
• Ctrl+D: esci
• Ctrl+L: selettore modello
• Ctrl+G: selettore agente
• Ctrl+P: selettore sessione
• Ctrl+O: attiva/disattiva espansione dell'output degli strumenti
• Ctrl+T: attiva/disattiva visibilità del ragionamento (ricarica la cronologia)

Comandi slash

Core:

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

Controlli sessione:

• /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|reset> (reset/inherit/clear/default cancella l'override della sessione)
• /goal [status] | /goal start <objective> | /goal pause|resume|complete|block|clear
• /elevated <on|off|ask|full> (alias: /elev)
• /activation <mention|always>
• /deliver <on|off>

Ciclo di vita della sessione:

• /new o /reset (reimposta la sessione)
• /abort (interrompi l'esecuzione attiva)
• /settings
• /exit

Solo modalità locale:

• /auth [provider] apre il flusso di autenticazione/accesso del provider dentro la TUI.

Gli altri comandi slash del Gateway (ad esempio, /context) vengono inoltrati al Gateway e mostrati come output di sistema. Vedi Comandi slash.

Comandi shell locali

• Anteponi a una riga ! per eseguire un comando shell locale sull'host della TUI.
• La TUI chiede una volta per sessione di consentire l'esecuzione locale; se rifiuti, ! resta disabilitato per la sessione.
• I comandi vengono eseguiti in una shell nuova, non interattiva, nella directory di lavoro della TUI (nessun cd/env persistente).
• I comandi shell locali ricevono OPENCLAW_SHELL=tui-local nel loro ambiente.
• Un singolo ! viene inviato come messaggio normale; gli spazi iniziali non attivano l'esecuzione locale.

Riparare le configurazioni dalla TUI locale

Usa la modalità locale quando la configurazione corrente è già valida e vuoi che l'agente incorporato la ispezioni sulla stessa macchina, la confronti con la documentazione e aiuti a riparare le divergenze senza dipendere da un Gateway in esecuzione.

Se openclaw config validate sta già fallendo, inizia prima con openclaw configure o openclaw doctor --fix. openclaw chat non aggira la protezione contro la configurazione non valida.

Flusso tipico:

1. Avvia la modalità locale:

openclaw chat

2. Chiedi all'agente cosa vuoi controllare, ad esempio:

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

3. Usa comandi shell locali per prove e validazione precise:

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

4. Applica modifiche mirate con openclaw config set o openclaw configure, poi riesegui !openclaw config validate.
5. Se Doctor consiglia una migrazione o riparazione automatica, esaminala ed esegui !openclaw doctor --fix.

Suggerimenti:

• Preferisci openclaw config set o openclaw configure alla modifica manuale di openclaw.json.
• openclaw docs "<query>" cerca nell'indice della documentazione live dalla stessa macchina.
• openclaw config validate --json è utile quando vuoi errori strutturati di schema e SecretRef/risolvibilità.

Output degli strumenti

• Le chiamate agli strumenti vengono mostrate come schede con argomenti + risultati.
• Ctrl+O alterna tra viste compresse/espanse.
• Mentre gli strumenti sono in esecuzione, gli aggiornamenti parziali vengono trasmessi in streaming nella stessa scheda.

Colori del terminale

• La TUI mantiene il testo del corpo dell'assistente nel colore di primo piano predefinito del terminale, così i terminali scuri e chiari restano entrambi leggibili.
• Se il tuo terminale usa uno sfondo chiaro e il rilevamento automatico è errato, imposta OPENCLAW_THEME=light prima di avviare openclaw tui.
• Per forzare invece la tavolozza scura originale, imposta OPENCLAW_THEME=dark.

Cronologia + streaming

• Alla connessione, la TUI carica la cronologia più recente (predefinito 200 messaggi).
• Le risposte in streaming vengono aggiornate sul posto fino alla finalizzazione.
• La TUI ascolta anche gli eventi degli strumenti agente per schede degli strumenti più ricche.

Dettagli di connessione

• La TUI si registra presso il Gateway come mode: "tui".
• Le riconnessioni mostrano un messaggio di sistema; le lacune negli eventi vengono evidenziate nel registro.

Opzioni

• --local: esegui contro il runtime agente incorporato locale
• --url <url>: URL WebSocket del Gateway (predefinito dalla configurazione o ws://127.0.0.1:<port>)
• --token <token>: token del Gateway (se richiesto)
• --password <password>: password del Gateway (se richiesta)
• --session <key>: chiave di sessione (predefinito: main, o global quando l'ambito è globale)
• --deliver: consegna le risposte dell'assistente al provider (disattivato per impostazione predefinita)
• --thinking <level>: sovrascrivi il livello di ragionamento per gli invii
• --message <text>: invia un messaggio iniziale dopo la connessione
• --timeout-ms <ms>: timeout agente in ms (predefinito da agents.defaults.timeoutSeconds)
• --history-limit <n>: voci di cronologia da caricare (predefinito 200)

Risoluzione dei problemi

Nessun output dopo l'invio di un messaggio:

• Esegui /status nella TUI per confermare che il Gateway sia connesso e inattivo/occupato.
• Controlla i log del Gateway: openclaw logs --follow.
• Conferma che l'agente possa essere eseguito: openclaw status e openclaw models status.
• Se ti aspetti messaggi in un canale chat, abilita la consegna (/deliver on o --deliver).

Risoluzione dei problemi di connessione

• disconnected: assicurati che il Gateway sia in esecuzione e che --url/--token/--password siano corretti.
• Nessun agente nel selettore: controlla openclaw agents list e la tua configurazione di routing.
• Selettore sessione vuoto: potresti essere nell'ambito globale o non avere ancora sessioni.

Correlati

• Control UI — interfaccia di controllo basata sul web
• Config — ispeziona, valida e modifica openclaw.json
• Doctor — controlli guidati di riparazione e migrazione
• Riferimento CLI — riferimento completo dei comandi CLI