---
read_when:
    - Vuoi una guida dettagliata della TUI adatta ai principianti
    - Ti serve l'elenco completo delle funzionalità, dei comandi e delle scorciatoie TUI
summary: 'Interfaccia terminale (TUI): connettersi al Gateway o eseguire localmente in modalità incorporata'
title: TUI
x-i18n:
    generated_at: "2026-06-27T18:26:31Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: ed02875ea5dcb8cef987d16fe11701eba11160525caf9791f74c610b1b6bec6e
    source_path: web/tui.md
    workflow: 16
---

## Avvio rapido

### Modalità Gateway

1. Avvia il Gateway.

```bash
openclaw gateway
```

2. Apri la TUI.

```bash
openclaw tui
```

3. Digita un messaggio e premi Invio.

Gateway remoto:

```bash
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:

```bash
openclaw chat
# or
openclaw 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:

  ```bash
  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](/it/tools/goal), 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](/it/tools/slash-commands).

## 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:

```bash
openclaw chat
```

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

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

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

```text
!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`)

<Warning>
Quando imposti `--url`, la TUI non ripiega sulle credenziali di configurazione o di ambiente. Passa `--token` o `--password` esplicitamente. La mancanza di credenziali esplicite è un errore. In modalità locale, non passare `--url`, `--token` o `--password`.
</Warning>

## 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](/it/web/control-ui) — interfaccia di controllo basata sul web
- [Config](/it/cli/config) — ispeziona, valida e modifica `openclaw.json`
- [Doctor](/it/cli/doctor) — controlli guidati di riparazione e migrazione
- [Riferimento CLI](/it/cli) — riferimento completo dei comandi CLI