openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh it translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-05 08:27:53 +00:00
parent 881534cc12
commit a25ce61646
10 changed files with 1161 additions and 1096 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

156
docs/it/automation/hooks.md
View File

@ -1,26 +1,26 @@
---
read_when:
- Vuoi un'automazione basata su eventi per /new, /reset, /stop e gli eventi del ciclo di vita dell'agente
- Vuoi creare, installare o eseguire il debug degli hook
summary: 'Hook: automazione basata su eventi per comandi ed eventi del ciclo di vita'
- Vuoi un'automazione basata su eventi per /new, /reset, /stop e per gli eventi del ciclo di vita dell'agente
- Vuoi creare, installare o risolvere problemi degli hook
summary: 'Hook: automazione guidata dagli eventi per comandi ed eventi del ciclo di vita'
title: Agganci
x-i18n:
generated_at: "2026-05-03T21:27:30Z"
generated_at: "2026-05-05T08:25:48Z"
model: gpt-5.5
provider: openai
source_hash: 15f0d120ccf7314a991da5d66e65e5c78375222a846ba01d7a04ddfe1f02cb32
source_hash: 321eb7a583d5e8c90d2c2026f6e1cf46cd207bef52213774b469a8d46b993967
source_path: automation/hooks.md
workflow: 16
---
Gli hook sono piccoli script che vengono eseguiti quando accade qualcosa all'interno del Gateway. Possono essere individuati dalle directory e ispezionati con `openclaw hooks`. Il Gateway carica gli hook interni solo dopo che hai abilitato gli hook o configurato almeno una voce hook, un pacchetto hook, un handler legacy o una directory hook aggiuntiva.
Gli hook sono piccoli script che vengono eseguiti quando accade qualcosa all'interno del Gateway. Possono essere scoperti da directory e ispezionati con `openclaw hooks`. Il Gateway carica gli hook interni solo dopo che hai abilitato gli hook o configurato almeno una voce hook, un pacchetto hook, un gestore legacy o una directory hook aggiuntiva.
In OpenClaw esistono due tipi di hook:
- **Hook interni** (questa pagina): vengono eseguiti all'interno del Gateway quando si attivano eventi dell'agente, come `/new`, `/reset`, `/stop` o eventi del ciclo di vita.
- **Webhook**: endpoint HTTP esterni che consentono ad altri sistemi di avviare attività in OpenClaw. Vedi [Webhook](/it/automation/cron-jobs#webhooks).
- **Hook interni** (questa pagina): vengono eseguiti all'interno del Gateway quando si attivano eventi degli agenti, come `/new`, `/reset`, `/stop` o eventi del ciclo di vita.
- **Webhook**: endpoint HTTP esterni che consentono ad altri sistemi di attivare lavoro in OpenClaw. Vedi [Webhook](/it/automation/cron-jobs#webhooks).
Gli hook possono anche essere inclusi nei plugin. `openclaw hooks list` mostra sia gli hook autonomi sia gli hook gestiti dai plugin.
Gli hook possono anche essere inclusi nei Plugin. `openclaw hooks list` mostra sia gli hook autonomi sia gli hook gestiti dai Plugin.
## Avvio rapido
@ -40,29 +40,29 @@ openclaw hooks info session-memory
## Tipi di evento
| Evento | Quando si attiva |
| ------------------------ | -------------------------------------------------------- |
| `command:new` | Comando `/new` emesso |
| `command:reset` | Comando `/reset` emesso |
| `command:stop` | Comando `/stop` emesso |
| `command` | Qualsiasi evento di comando (listener generale) |
| `session:compact:before` | Prima che la compaction riassuma la cronologia |
| `session:compact:after` | Dopo il completamento della compaction |
| `session:patch` | Quando le proprietà della sessione vengono modificate |
| `agent:bootstrap` | Prima dell'iniezione dei file di bootstrap del workspace |
| `gateway:startup` | Dopo l'avvio dei canali e il caricamento degli hook |
| `gateway:shutdown` | Quando inizia l'arresto del gateway |
| `gateway:pre-restart` | Prima di un riavvio previsto del gateway |
| `message:received` | Messaggio in ingresso da qualsiasi canale |
| `message:transcribed` | Dopo il completamento della trascrizione audio |
| `message:preprocessed` | Dopo il completamento o il salto della pre-elaborazione di media e link |
| `message:sent` | Messaggio in uscita consegnato |
| Evento | Quando si attiva |
| ------------------------ | ---------------------------------------------------------- |
| `command:new` | Comando `/new` emesso |
| `command:reset` | Comando `/reset` emesso |
| `command:stop` | Comando `/stop` emesso |
| `command` | Qualsiasi evento comando (listener generale) |
| `session:compact:before` | Prima che la Compaction riassuma la cronologia |
| `session:compact:after` | Dopo il completamento della Compaction |
| `session:patch` | Quando le proprietà della sessione vengono modificate |
| `agent:bootstrap` | Prima che vengano inseriti i file di bootstrap dell'area di lavoro |
| `gateway:startup` | Dopo l'avvio dei canali e il caricamento degli hook |
| `gateway:shutdown` | Quando inizia l'arresto del Gateway |
| `gateway:pre-restart` | Prima di un riavvio previsto del Gateway |
| `message:received` | Messaggio in ingresso da qualsiasi canale |
| `message:transcribed` | Dopo il completamento della trascrizione audio |
| `message:preprocessed` | Dopo il completamento o il salto della preelaborazione di contenuti multimediali e link |
| `message:sent` | Messaggio in uscita consegnato |
## Scrivere hook
### Struttura degli hook
Ogni hook è una directory che contiene due file:
Ogni hook è una directory contenente due file:
```
my-hook/
@ -91,13 +91,13 @@ Detailed documentation goes here.
| ---------- | ---------------------------------------------------- |
| `emoji` | Emoji visualizzata per la CLI |
| `events` | Array di eventi da ascoltare |
| `export` | Export nominato da usare (predefinito: `"default"`) |
| `export` | Export denominato da usare (predefinito: `"default"`) |
| `os` | Piattaforme richieste (ad es. `["darwin", "linux"]`) |
| `requires` | Percorsi `bins`, `anyBins`, `env` o `config` richiesti |
| `always` | Ignora i controlli di idoneità (booleano) |
| `install` | Metodi di installazione |
### Implementazione dell'handler
### Implementazione del gestore
```typescript
const handler = async (event) => {
@ -115,52 +115,52 @@ const handler = async (event) => {
export default handler;
```
Ogni evento include: `type`, `action`, `sessionKey`, `timestamp`, `messages` (push per inviare all'utente) e `context` (dati specifici dell'evento). I contesti degli hook per agenti e plugin degli strumenti possono includere anche `trace`, un contesto di traccia diagnostica di sola lettura compatibile con W3C che i plugin possono passare nei log strutturati per la correlazione OTEL.
Ogni evento include: `type`, `action`, `sessionKey`, `timestamp`, `messages` (push per inviare all'utente) e `context` (dati specifici dell'evento). I contesti degli hook per agenti e strumenti Plugin possono includere anche `trace`, un contesto di traccia diagnostica di sola lettura compatibile con W3C che i Plugin possono passare nei log strutturati per la correlazione OTEL.
### Elementi principali del contesto degli eventi
### Punti principali del contesto degli eventi
**Eventi di comando** (`command:new`, `command:reset`): `context.sessionEntry`, `context.previousSessionEntry`, `context.commandSource`, `context.workspaceDir`, `context.cfg`.
**Eventi comando** (`command:new`, `command:reset`): `context.sessionEntry`, `context.previousSessionEntry`, `context.commandSource`, `context.workspaceDir`, `context.cfg`.
**Eventi di messaggio** (`message:received`): `context.from`, `context.content`, `context.channelId`, `context.metadata` (dati specifici del provider inclusi `senderId`, `senderName`, `guildId`). `context.content` preferisce un corpo comando non vuoto per i messaggi simili a comandi, poi ripiega sul corpo in ingresso grezzo e sul corpo generico; non include arricchimenti solo per l'agente come cronologia del thread o riepiloghi dei link.
**Eventi messaggio** (`message:received`): `context.from`, `context.content`, `context.channelId`, `context.metadata` (dati specifici del provider, inclusi `senderId`, `senderName`, `guildId`). `context.content` preferisce un corpo comando non vuoto per i messaggi simili a comandi, quindi ripiega sul corpo in ingresso grezzo e sul corpo generico; non include arricchimenti riservati all'agente, come cronologia del thread o riepiloghi dei link.
**Eventi di messaggio** (`message:sent`): `context.to`, `context.content`, `context.success`, `context.channelId`.
**Eventi messaggio** (`message:sent`): `context.to`, `context.content`, `context.success`, `context.channelId`.
**Eventi di messaggio** (`message:transcribed`): `context.transcript`, `context.from`, `context.channelId`, `context.mediaPath`.
**Eventi messaggio** (`message:transcribed`): `context.transcript`, `context.from`, `context.channelId`, `context.mediaPath`.
**Eventi di messaggio** (`message:preprocessed`): `context.bodyForAgent` (corpo arricchito finale), `context.from`, `context.channelId`.
**Eventi messaggio** (`message:preprocessed`): `context.bodyForAgent` (corpo arricchito finale), `context.from`, `context.channelId`.
**Eventi di bootstrap** (`agent:bootstrap`): `context.bootstrapFiles` (array mutabile), `context.agentId`.
**Eventi di patch della sessione** (`session:patch`): `context.sessionEntry`, `context.patch` (solo campi modificati), `context.cfg`. Solo i client privilegiati possono attivare eventi di patch.
**Eventi patch di sessione** (`session:patch`): `context.sessionEntry`, `context.patch` (solo campi modificati), `context.cfg`. Solo i client privilegiati possono attivare eventi patch.
**Eventi di Compaction**: `session:compact:before` include `messageCount`, `tokenCount`. `session:compact:after` aggiunge `compactedCount`, `summaryLength`, `tokensBefore`, `tokensAfter`.
**Eventi Compaction**: `session:compact:before` include `messageCount`, `tokenCount`. `session:compact:after` aggiunge `compactedCount`, `summaryLength`, `tokensBefore`, `tokensAfter`.
`command:stop` osserva l'utente che emette `/stop`; riguarda il ciclo di vita dell'annullamento/comando, non è un gate di finalizzazione dell'agente. I plugin che devono ispezionare una risposta finale naturale e chiedere all'agente un ulteriore passaggio devono invece usare l'hook tipizzato del plugin `before_agent_finalize`. Vedi [Hook dei plugin](/it/plugins/hooks).
`command:stop` osserva l'utente che emette `/stop`; è un ciclo di vita di annullamento/comando, non un gate di finalizzazione dell'agente. I Plugin che devono ispezionare una risposta finale naturale e chiedere all'agente un ulteriore passaggio dovrebbero usare invece l'hook Plugin tipizzato `before_agent_finalize`. Vedi [Hook dei Plugin](/it/plugins/hooks).
**Eventi del ciclo di vita del Gateway**: `gateway:shutdown` include `reason` e `restartExpectedMs` e si attiva quando inizia l'arresto del gateway. `gateway:pre-restart` include lo stesso contesto ma si attiva solo quando l'arresto fa parte di un riavvio previsto e viene fornito un valore finito di `restartExpectedMs`. Durante l'arresto, l'attesa di ogni hook del ciclo di vita è best-effort e limitata, così l'arresto continua se un handler si blocca.
**Eventi del ciclo di vita del Gateway**: `gateway:shutdown` include `reason` e `restartExpectedMs` e si attiva quando inizia l'arresto del Gateway. `gateway:pre-restart` include lo stesso contesto, ma si attiva solo quando l'arresto fa parte di un riavvio previsto e viene fornito un valore finito di `restartExpectedMs`. Durante l'arresto, l'attesa di ogni hook del ciclo di vita è best effort e limitata, così l'arresto continua se un gestore si blocca.
## Rilevamento degli hook
## Scoperta degli hook
Gli hook vengono individuati da queste directory, in ordine di precedenza crescente per l'override:
Gli hook vengono scoperti da queste directory, in ordine di precedenza di override crescente:
1. **Hook inclusi**: distribuiti con OpenClaw
2. **Hook dei plugin**: hook inclusi nei plugin installati
3. **Hook gestiti**: `~/.openclaw/hooks/` (installati dall'utente, condivisi tra workspace). Le directory aggiuntive da `hooks.internal.load.extraDirs` condividono questa precedenza.
4. **Hook del workspace**: `<workspace>/hooks/` (per agente, disabilitati per impostazione predefinita finché non vengono abilitati esplicitamente)
2. **Hook Plugin**: hook inclusi nei Plugin installati
3. **Hook gestiti**: `~/.openclaw/hooks/` (installati dall'utente, condivisi tra le aree di lavoro). Le directory aggiuntive da `hooks.internal.load.extraDirs` condividono questa precedenza.
4. **Hook dell'area di lavoro**: `<workspace>/hooks/` (per agente, disabilitati per impostazione predefinita finché non vengono abilitati esplicitamente)
Gli hook del workspace possono aggiungere nuovi nomi di hook ma non possono sovrascrivere hook inclusi, gestiti o forniti da plugin con lo stesso nome.
Gli hook dell'area di lavoro possono aggiungere nuovi nomi di hook, ma non possono sovrascrivere hook inclusi, gestiti o forniti da Plugin con lo stesso nome.
Il Gateway salta il rilevamento degli hook interni all'avvio finché gli hook interni non sono configurati. Abilita un hook incluso o gestito con `openclaw hooks enable <name>`, installa un pacchetto hook oppure imposta `hooks.internal.enabled=true` per aderire. Quando abiliti un singolo hook nominato, il Gateway carica solo l'handler di quell'hook; `hooks.internal.enabled=true`, le directory hook aggiuntive e gli handler legacy aderiscono al rilevamento ampio.
Il Gateway salta la scoperta degli hook interni all'avvio finché gli hook interni non sono configurati. Abilita un hook incluso o gestito con `openclaw hooks enable <name>`, installa un pacchetto hook oppure imposta `hooks.internal.enabled=true` per aderire esplicitamente. Quando abiliti un hook denominato, il Gateway carica solo il gestore di quell'hook; `hooks.internal.enabled=true`, le directory hook aggiuntive e i gestori legacy abilitano la scoperta ampia.
### Pacchetti hook
I pacchetti hook sono pacchetti npm che esportano hook tramite `openclaw.hooks` in `package.json`. Installa con:
I pacchetti di hook sono pacchetti npm che esportano hook tramite `openclaw.hooks` in `package.json`. Installa con:
```bash
openclaw plugins install <path-or-spec>
```
Le specifiche npm sono solo da registry (nome pacchetto + versione esatta opzionale o dist-tag). Le specifiche Git/URL/file e gli intervalli semver vengono rifiutati.
Le specifiche npm sono solo da registry (nome del pacchetto + versione esatta opzionale o dist-tag). Le specifiche Git/URL/file e gli intervalli semver vengono rifiutati.
## Hook inclusi
@ -169,8 +169,8 @@ Le specifiche npm sono solo da registry (nome pacchetto + versione esatta opzion
| session-memory | `command:new`, `command:reset` | Salva il contesto della sessione in `<workspace>/memory/` |
| bootstrap-extra-files | `agent:bootstrap` | Inietta file di bootstrap aggiuntivi da pattern glob |
| command-logger | `command` | Registra tutti i comandi in `~/.openclaw/logs/commands.log` |
| compaction-notifier | `session:compact:before`, `session:compact:after` | Invia notifiche chat visibili quando la compaction della sessione inizia/termina |
| boot-md | `gateway:startup` | Esegue `BOOT.md` all'avvio del gateway |
| compaction-notifier | `session:compact:before`, `session:compact:after` | Invia avvisi di chat visibili quando la Compaction della sessione inizia/termina |
| boot-md | `gateway:startup` | Esegue `BOOT.md` quando il Gateway si avvia |
Abilita qualsiasi hook incluso:
@ -180,13 +180,13 @@ openclaw hooks enable <hook-name>
<a id="session-memory"></a>
### Dettagli di session-memory
### dettagli di session-memory
Estrae gli ultimi 15 messaggi utente/assistente, genera uno slug descrittivo per il nome file tramite LLM e salva in `<workspace>/memory/YYYY-MM-DD-slug.md` usando la data locale dell'host. Richiede che `workspace.dir` sia configurato.
Estrae gli ultimi 15 messaggi utente/assistente e li salva in `<workspace>/memory/YYYY-MM-DD-HHMM.md` usando la data locale dell'host. L'acquisizione della memoria viene eseguita in background, quindi le conferme di `/new` e `/reset` non sono ritardate dalla lettura della trascrizione o dalla generazione opzionale dello slug. Imposta `hooks.internal.entries.session-memory.llmSlug: true` per generare slug descrittivi per i nomi dei file con il modello configurato. Richiede che `workspace.dir` sia configurato.
<a id="bootstrap-extra-files"></a>
### Configurazione di bootstrap-extra-files
### configurazione di bootstrap-extra-files
```json
{
@ -203,34 +203,34 @@ Estrae gli ultimi 15 messaggi utente/assistente, genera uno slug descrittivo per
}
```
I percorsi si risolvono rispetto al workspace. Vengono caricati solo i basename di bootstrap riconosciuti (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, `MEMORY.md`).
I percorsi vengono risolti rispetto al workspace. Vengono caricati solo i nomi base di bootstrap riconosciuti (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, `MEMORY.md`).
<a id="command-logger"></a>
### Dettagli di command-logger
### dettagli di command-logger
Registra ogni comando slash in `~/.openclaw/logs/commands.log`.
<a id="compaction-notifier"></a>
### Dettagli di compaction-notifier
### dettagli di compaction-notifier
Invia brevi messaggi di stato nella conversazione corrente quando OpenClaw inizia e termina la compaction della trascrizione della sessione. Questo rende i turni lunghi meno confusi sulle superfici di chat, perché l'utente può vedere che l'assistente sta riassumendo il contesto e continuerà dopo la compaction.
Invia brevi messaggi di stato nella conversazione corrente quando OpenClaw inizia e termina la Compaction della trascrizione della sessione. Questo rende i turni lunghi meno confusi nelle superfici di chat, perché l'utente può vedere che l'assistente sta riepilogando il contesto e continuerà dopo la Compaction.
<a id="boot-md"></a>
### Dettagli di boot-md
### dettagli di boot-md
Esegue `BOOT.md` dal workspace attivo all'avvio del gateway.
Esegue `BOOT.md` dal workspace attivo quando il Gateway si avvia.
## Hook dei plugin
## Hook dei Plugin
I plugin possono registrare hook tipizzati tramite il Plugin SDK per un'integrazione più profonda:
intercettare chiamate agli strumenti, modificare prompt, controllare il flusso dei messaggi e altro ancora.
Usa gli hook dei plugin quando hai bisogno di `before_tool_call`, `before_agent_reply`,
I Plugin possono registrare hook tipizzati tramite il Plugin SDK per un'integrazione più profonda:
intercettare chiamate agli strumenti, modificare prompt, controllare il flusso dei messaggi e altro.
Usa gli hook dei Plugin quando ti servono `before_tool_call`, `before_agent_reply`,
`before_install` o altri hook del ciclo di vita in-process.
Per il riferimento completo degli hook dei plugin, vedi [Hook dei plugin](/it/plugins/hooks).
Per il riferimento completo sugli hook dei Plugin, consulta [Hook dei Plugin](/it/plugins/hooks).
## Configurazione
@ -265,7 +265,7 @@ Variabili d'ambiente per hook:
}
```
Directory hook aggiuntive:
Directory di hook aggiuntive:
```json
{
@ -280,7 +280,7 @@ Directory hook aggiuntive:
```
<Note>
Il formato di configurazione legacy dell'array `hooks.internal.handlers` è ancora supportato per compatibilità all'indietro, ma i nuovi hook devono usare il sistema basato sul rilevamento.
Il formato di configurazione legacy dell'array `hooks.internal.handlers` è ancora supportato per compatibilità all'indietro, ma i nuovi hook dovrebbero usare il sistema basato sulla discovery.
</Note>
## Riferimento CLI
@ -300,11 +300,11 @@ openclaw hooks enable <hook-name>
openclaw hooks disable <hook-name>
```
## Migliori pratiche
## Best practice
- **Mantieni rapidi i gestori.** Gli hook vengono eseguiti durante l'elaborazione dei comandi. Avvia il lavoro pesante senza attendere con `void processInBackground(event)`.
- **Gestisci gli errori in modo controllato.** Racchiudi le operazioni rischiose in try/catch; non generare eccezioni, così gli altri gestori possono essere eseguiti.
- **Filtra gli eventi in anticipo.** Ritorna immediatamente se il tipo/azione dell'evento non è pertinente.
- **Mantieni i gestori veloci.** Gli hook vengono eseguiti durante l'elaborazione dei comandi. Esegui le operazioni pesanti senza attenderle con `void processInBackground(event)`.
- **Gestisci gli errori con eleganza.** Racchiudi le operazioni rischiose in try/catch; non generare eccezioni, così gli altri gestori possono essere eseguiti.
- **Filtra gli eventi in anticipo.** Restituisci immediatamente se il tipo/l'azione dell'evento non è rilevante.
- **Usa chiavi evento specifiche.** Preferisci `"events": ["command:new"]` a `"events": ["command"]` per ridurre il sovraccarico.
## Risoluzione dei problemi
@ -312,11 +312,11 @@ openclaw hooks disable <hook-name>
### Hook non rilevato
```bash
# Verify directory structure
# Verifica la struttura della directory
ls -la ~/.openclaw/hooks/my-hook/
# Should show: HOOK.md, handler.ts
# Dovrebbe mostrare: HOOK.md, handler.ts
# List all discovered hooks
# Elenca tutti gli hook rilevati
openclaw hooks list
```
@ -326,17 +326,17 @@ openclaw hooks list
openclaw hooks info my-hook
```
Controlla binari mancanti (PATH), variabili d'ambiente, valori di configurazione o compatibilità con il sistema operativo.
Verifica la presenza di binari mancanti (PATH), variabili d'ambiente, valori di configurazione o compatibilità con il sistema operativo.
### Hook non in esecuzione
1. Verifica che l'hook sia abilitato: `openclaw hooks list`
2. Riavvia il processo Gateway in modo che gli hook vengano ricaricati.
3. Controlla i log del Gateway: `./scripts/clawlog.sh | grep hook`
2. Riavvia il processo del gateway in modo che gli hook vengano ricaricati.
3. Controlla i log del gateway: `./scripts/clawlog.sh | grep hook`
## Correlati
- [Riferimento CLI: hook](/it/cli/hooks)
- [Webhook](/it/automation/cron-jobs#webhooks)
- [Hook dei Plugin](/it/plugins/hooks) — hook del ciclo di vita dei Plugin in-process
- [Hook dei Plugin](/it/plugins/hooks) — hook del ciclo di vita dei plugin in-process
- [Configurazione](/it/gateway/configuration-reference#hooks)

131
docs/it/channels/troubleshooting.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Il trasporto del canale risulta connesso ma le risposte non vanno a buon fine
- Il trasporto del canale risulta connesso, ma le risposte non vanno a buon fine
- Sono necessari controlli specifici per canale prima della documentazione approfondita sui provider
summary: Risoluzione rapida dei problemi a livello di canale con firme di errore e correzioni per canale
title: Risoluzione dei problemi del canale
summary: Risoluzione rapida dei problemi a livello di canale con firme di errore e correzioni per ciascun canale
title: Risoluzione dei problemi dei canali
x-i18n:
generated_at: "2026-05-04T02:22:52Z"
generated_at: "2026-05-05T08:25:47Z"
model: gpt-5.5
provider: openai
source_hash: a3a0737156ae83897c44d18505e0355a5d8e5700106b984496d94874c270deb2
source_hash: 360184c41ce6929c696688af597c5104a8a28b54620c354f7ee400a2e5490519
source_path: channels/troubleshooting.md
workflow: 16
---
@ -27,76 +27,77 @@ openclaw doctor
openclaw channels status --probe
```
Stato di riferimento corretto:
Baseline sana:
- `Runtime: running`
- `Connectivity probe: ok`
- `Capability: read-only`, `write-capable`, o `admin-capable`
- Il probe del canale mostra il transport connesso e, dove supportato, `works` o `audit ok`
- Il probe del canale mostra il trasporto connesso e, dove supportato, `works` o `audit ok`
## WhatsApp
### Segnali di errore di WhatsApp
### Firme di errore di WhatsApp
| Sintomo | Controllo più rapido | Correzione |
| ------------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Connesso ma nessuna risposta DM | `openclaw pairing list whatsapp` | Approva il mittente o cambia policy/allowlist dei DM. |
| Messaggi di gruppo ignorati | Controlla `requireMention` + pattern di menzione nella config | Menziona il bot o rendi meno restrittiva la policy di menzione per quel gruppo. |
| Login QR in timeout con 408 | Controlla env `HTTPS_PROXY` / `HTTP_PROXY` del Gateway | Imposta un proxy raggiungibile; usa `NO_PROXY` solo per i bypass. |
| Disconnessioni casuali/cicli di nuovo login | `openclaw channels status --probe` + log | Le riconnessioni recenti vengono segnalate anche quando ora è connesso; osserva i log, riavvia il Gateway, poi ricollega se l'instabilità continua. |
| Sintomo | Controllo più rapido | Correzione |
| ----------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Connesso ma nessuna risposta DM | `openclaw pairing list whatsapp` | Approva il mittente o cambia la policy DM/allowlist. |
| Messaggi di gruppo ignorati | Controlla `requireMention` + pattern di menzione nella configurazione | Menziona il bot o allenta la policy sulle menzioni per quel gruppo. |
| Il login QR va in timeout con 408 | Controlla le env `HTTPS_PROXY` / `HTTP_PROXY` del Gateway | Imposta un proxy raggiungibile; usa `NO_PROXY` solo per i bypass. |
| Disconnessioni/cicli di nuovo login casuali | `openclaw channels status --probe` + log | Le riconnessioni recenti vengono segnalate anche quando ora è connesso; osserva i log, riavvia il Gateway, poi ricollega se l'instabilità continua. |
| Le risposte arrivano con secondi/minuti di ritardo | `openclaw doctor --fix` | Doctor arresta i client TUI locali stale verificati quando degradano l'event loop del Gateway. |
Risoluzione completa dei problemi: [Risoluzione dei problemi di WhatsApp](/it/channels/whatsapp#troubleshooting)
## Telegram
### Segnali di errore di Telegram
### Firme di errore di Telegram
| Sintomo | Controllo più rapido | Correzione |
| ------------------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `/start` ma nessun flusso di risposta utilizzabile | `openclaw pairing list telegram` | Approva il pairing o cambia la policy dei DM. |
| Bot online ma il gruppo resta silenzioso | Verifica il requisito di menzione e la modalità privacy del bot | Disattiva la modalità privacy per la visibilità nel gruppo o menziona il bot. |
| Errori di invio con errori di rete | Ispeziona i log per errori nelle chiamate API Telegram | Correggi routing DNS/IPv6/proxy verso `api.telegram.org`. |
| L'avvio segnala `getMe returned 401` | Controlla la fonte del token configurata | Ricopia o rigenera il token BotFather e aggiorna `botToken`, `tokenFile` o `TELEGRAM_BOT_TOKEN` dell'account predefinito. |
| Polling bloccato o riconnessioni lente | `openclaw logs --follow` per diagnostica del polling | Aggiorna; se i riavvii sono falsi positivi, regola `pollingStallThresholdMs`. Blocchi persistenti indicano ancora proxy/DNS/IPv6. |
| `setMyCommands` rifiutato all'avvio | Ispeziona i log per `BOT_COMMANDS_TOO_MUCH` | Riduci i comandi Telegram di plugin/skill/personalizzati o disattiva i menu nativi. |
| Dopo l'upgrade l'allowlist ti blocca | `openclaw security audit` e allowlist nella config | Esegui `openclaw doctor --fix` o sostituisci `@username` con ID mittente numerici. |
| Sintomo | Controllo più rapido | Correzione |
| ------------------------------------ | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `/start` ma nessun flusso di risposta utilizzabile | `openclaw pairing list telegram` | Approva il pairing o cambia la policy DM. |
| Bot online ma il gruppo resta silenzioso | Verifica il requisito di menzione e la modalità privacy del bot | Disattiva la modalità privacy per la visibilità nel gruppo o menziona il bot. |
| Invii non riusciti con errori di rete | Ispeziona i log per errori nelle chiamate API Telegram | Correggi il routing DNS/IPv6/proxy verso `api.telegram.org`. |
| L'avvio segnala `getMe returned 401` | Controlla la fonte del token configurata | Ricopia o rigenera il token BotFather e aggiorna `botToken`, `tokenFile` o `TELEGRAM_BOT_TOKEN` dell'account predefinito. |
| Il polling si blocca o si riconnette lentamente | `openclaw logs --follow` per diagnostica del polling | Aggiorna; se i riavvii sono falsi positivi, regola `pollingStallThresholdMs`. I blocchi persistenti indicano ancora proxy/DNS/IPv6. |
| `setMyCommands` rifiutato all'avvio | Ispeziona i log per `BOT_COMMANDS_TOO_MUCH` | Riduci i comandi Telegram di Plugin/skill/personalizzati o disabilita i menu nativi. |
| Dopo l'aggiornamento l'allowlist ti blocca | `openclaw security audit` e allowlist di configurazione | Esegui `openclaw doctor --fix` o sostituisci `@username` con ID mittente numerici. |
Risoluzione completa dei problemi: [Risoluzione dei problemi di Telegram](/it/channels/telegram#troubleshooting)
## Discord
### Segnali di errore di Discord
### Firme di errore di Discord
| Sintomo | Controllo più rapido | Correzione |
| ----------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bot online ma nessuna risposta nella guild | `openclaw channels status --probe` | Consenti guild/canale e verifica l'intent per il contenuto dei messaggi. |
| Messaggi di gruppo ignorati | Controlla nei log gli scarti dovuti al gating delle menzioni | Menziona il bot o imposta `requireMention: false` per guild/canale. |
| Uso di typing/token ma nessun messaggio Discord | Il log della sessione mostra testo dell'assistente con `didSendViaMessagingTool: false` | Il modello ha risposto privatamente invece di chiamare lo strumento di messaggistica. Usa un modello affidabile per le chiamate strumento, oppure imposta `messages.groupChat.visibleReplies: "automatic"` per pubblicare automaticamente. |
| Risposte DM mancanti | `openclaw pairing list discord` | Approva il pairing DM o modifica la policy dei DM. |
| Sintomo | Controllo più rapido | Correzione |
| ----------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bot online ma nessuna risposta nel guild | `openclaw channels status --probe` | Consenti guild/canale e verifica l'intent del contenuto dei messaggi. |
| Messaggi di gruppo ignorati | Controlla nei log gli scarti dovuti al gating sulle menzioni | Menziona il bot o imposta `requireMention: false` per guild/canale. |
| Uso di typing/token ma nessun messaggio Discord | Il log della sessione mostra testo dell'assistente con `didSendViaMessagingTool: false` | Il modello ha risposto privatamente invece di chiamare lo strumento di messaggistica. Usa un modello affidabile nelle tool call, oppure imposta `messages.groupChat.visibleReplies: "automatic"` per pubblicare automaticamente. |
| Risposte DM mancanti | `openclaw pairing list discord` | Approva il pairing DM o regola la policy DM. |
Risoluzione completa dei problemi: [Risoluzione dei problemi di Discord](/it/channels/discord#troubleshooting)
## Slack
### Segnali di errore di Slack
### Firme di errore di Slack
| Sintomo | Controllo più rapido | Correzione |
| -------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sintomo | Controllo più rapido | Correzione |
| -------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Socket mode connesso ma nessuna risposta | `openclaw channels status --probe` | Verifica app token + bot token e gli scope richiesti; controlla `botTokenStatus` / `appTokenStatus = configured_unavailable` nelle configurazioni basate su SecretRef. |
| DM bloccati | `openclaw pairing list slack` | Approva il pairing o rendi meno restrittiva la policy dei DM. |
| Messaggio di canale ignorato | Controlla `groupPolicy` e allowlist del canale | Consenti il canale o cambia la policy in `open`. |
| DM bloccati | `openclaw pairing list slack` | Approva il pairing o allenta la policy DM. |
| Messaggio di canale ignorato | Controlla `groupPolicy` e allowlist del canale | Consenti il canale o cambia la policy in `open`. |
Risoluzione completa dei problemi: [Risoluzione dei problemi di Slack](/it/channels/slack#troubleshooting)
## iMessage e BlueBubbles
### Segnali di errore di iMessage e BlueBubbles
### Firme di errore di iMessage e BlueBubbles
| Sintomo | Controllo più rapido | Correzione |
| -------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------ |
| Nessun evento in ingresso | Verifica raggiungibilità webhook/server e permessi dell'app | Correggi l'URL del Webhook o lo stato del server BlueBubbles. |
| Puoi inviare ma non ricevere su macOS | Controlla i permessi privacy di macOS per l'automazione di Messages | Concedi di nuovo i permessi TCC e riavvia il processo del canale. |
| Mittente DM bloccato | `openclaw pairing list imessage` o `openclaw pairing list bluebubbles` | Approva il pairing o aggiorna l'allowlist. |
| Sintomo | Controllo più rapido | Correzione |
| -------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------- |
| Nessun evento in ingresso | Verifica la raggiungibilità di webhook/server e i permessi dell'app | Correggi l'URL del Webhook o lo stato del server BlueBubbles. |
| Può inviare ma non riceve su macOS | Controlla i permessi privacy di macOS per l'automazione di Messages | Riconcedi i permessi TCC e riavvia il processo del canale. |
| Mittente DM bloccato | `openclaw pairing list imessage` o `openclaw pairing list bluebubbles` | Approva il pairing o aggiorna l'allowlist. |
Risoluzione completa dei problemi:
@ -105,45 +106,45 @@ Risoluzione completa dei problemi:
## Signal
### Segnali di errore di Signal
### Firme di errore di Signal
| Sintomo | Controllo più rapido | Correzione |
| ------------------------------- | ------------------------------------------ | ------------------------------------------------------ |
| Daemon raggiungibile ma bot silenzioso | `openclaw channels status --probe` | Verifica URL/account del daemon `signal-cli` e modalità di ricezione. |
| DM bloccato | `openclaw pairing list signal` | Approva il mittente o modifica la policy dei DM. |
| Le risposte di gruppo non si attivano | Controlla allowlist del gruppo e pattern di menzione | Aggiungi mittente/gruppo o allenta il gating. |
| Sintomo | Controllo più rapido | Correzione |
| ------------------------------- | ----------------------------------------- | ------------------------------------------------------------ |
| Daemon raggiungibile ma bot silenzioso | `openclaw channels status --probe` | Verifica l'URL/account del daemon `signal-cli` e la modalità di ricezione. |
| DM bloccato | `openclaw pairing list signal` | Approva il mittente o regola la policy DM. |
| Le risposte di gruppo non si attivano | Controlla allowlist del gruppo e pattern di menzione | Aggiungi mittente/gruppo o allenta il gating. |
Risoluzione completa dei problemi: [Risoluzione dei problemi di Signal](/it/channels/signal#troubleshooting)
## QQ Bot
### Segnali di errore di QQ Bot
### Firme di errore di QQ Bot
| Sintomo | Controllo più rapido | Correzione |
| ------------------------------- | ------------------------------------------------- | -------------------------------------------------------------- |
| Il bot risponde "gone to Mars" | Verifica `appId` e `clientSecret` nella config | Imposta le credenziali o riavvia il Gateway. |
| Nessun messaggio in ingresso | `openclaw channels status --probe` | Verifica le credenziali sulla QQ Open Platform. |
| Voce non trascritta | Controlla la config del provider STT | Configura `channels.qqbot.stt` o `tools.media.audio`. |
| Messaggi proattivi non ricevuti | Controlla i requisiti di interazione della piattaforma QQ | QQ può bloccare i messaggi avviati dal bot senza un'interazione recente. |
| Sintomo | Controllo più rapido | Correzione |
| ------------------------------- | --------------------------------------------- | ------------------------------------------------------------------ |
| Il bot risponde "andato su Marte" | Verifica `appId` e `clientSecret` nella configurazione | Imposta le credenziali o riavvia il Gateway. |
| Nessun messaggio in ingresso | `openclaw channels status --probe` | Verifica le credenziali sulla QQ Open Platform. |
| Voce non trascritta | Controlla la configurazione del provider STT | Configura `channels.qqbot.stt` o `tools.media.audio`. |
| Messaggi proattivi non arrivano | Controlla i requisiti di interazione della piattaforma QQ | QQ può bloccare i messaggi avviati dal bot senza interazioni recenti. |
Risoluzione completa dei problemi: [Risoluzione dei problemi di QQ Bot](/it/channels/qqbot#troubleshooting)
## Matrix
### Segnali di errore di Matrix
### Firme di errore di Matrix
| Sintomo | Controllo più rapido | Correzione |
| ----------------------------------- | ------------------------------------------ | -------------------------------------------------------------------------- |
| Accesso effettuato ma ignora i messaggi della stanza | `openclaw channels status --probe` | Controlla `groupPolicy`, allowlist della stanza e gating delle menzioni. |
| I DM non vengono elaborati | `openclaw pairing list matrix` | Approva il mittente o modifica la policy dei DM. |
| Stanze cifrate non funzionano | `openclaw matrix verify status` | Verifica di nuovo il dispositivo, poi controlla `openclaw matrix verify backup status`. |
| Ripristino del backup in sospeso/non funzionante | `openclaw matrix verify backup status` | Esegui `openclaw matrix verify backup restore` o ripeti con una chiave di recovery. |
| Cross-signing/bootstrap sembra errato | `openclaw matrix verify bootstrap` | Ripara secret storage, cross-signing e stato del backup in un solo passaggio. |
| Sintomo | Controllo più rapido | Correzione |
| ----------------------------------- | --------------------------------------- | ------------------------------------------------------------------------ |
| Effettua il login ma ignora i messaggi della stanza | `openclaw channels status --probe` | Controlla `groupPolicy`, allowlist delle stanze e gating sulle menzioni. |
| I DM non vengono elaborati | `openclaw pairing list matrix` | Approva il mittente o regola la policy DM. |
| Le stanze cifrate falliscono | `openclaw matrix verify status` | Riverifica il dispositivo, poi controlla `openclaw matrix verify backup status`. |
| Il ripristino del backup è in sospeso/rotto | `openclaw matrix verify backup status` | Esegui `openclaw matrix verify backup restore` o rilancia con una chiave di recupero. |
| Cross-signing/bootstrap sembra errato | `openclaw matrix verify bootstrap` | Ripara secret storage, cross-signing e stato del backup in un solo passaggio. |
Configurazione completa e setup: [Matrix](/it/channels/matrix)
Configurazione e setup completi: [Matrix](/it/channels/matrix)
## Correlati
- [Pairing](/it/channels/pairing)
- [Instradamento del canale](/it/channels/channel-routing)
- [Instradamento dei canali](/it/channels/channel-routing)
- [Risoluzione dei problemi del Gateway](/it/gateway/troubleshooting)

73
docs/it/cli/doctor.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Hai problemi di connettività/autenticazione e vuoi correzioni guidate
- Hai eseguito l'aggiornamento e vuoi un controllo rapido
- Hai problemi di connettività/autenticazione e desideri correzioni guidate
- Hai aggiornato e vuoi una verifica rapida
summary: Riferimento CLI per `openclaw doctor` (controlli di integrità + riparazioni guidate)
title: Diagnostica
x-i18n:
generated_at: "2026-05-05T01:44:16Z"
generated_at: "2026-05-05T08:25:32Z"
model: gpt-5.5
provider: openai
source_hash: 079d7674ae2a259a0430e30e7577ac532135ad5461c57c4b3a6514a007bc9ea5
source_hash: d6101008d1cb7e08f9902a8a29785710f325966524b003b87b5c628fe906ab78
source_path: cli/doctor.md
workflow: 16
---
@ -17,10 +17,10 @@ x-i18n:
Controlli di integrità + correzioni rapide per il Gateway e i canali.
Correlato:
Correlati:
- Risoluzione dei problemi: [Risoluzione dei problemi](/it/gateway/troubleshooting)
- Audit di sicurezza: [Sicurezza](/it/gateway/security)
- Controllo di sicurezza: [Sicurezza](/it/gateway/security)
## Esempi
@ -36,43 +36,44 @@ openclaw doctor --generate-gateway-token
- `--no-workspace-suggestions`: disabilita i suggerimenti di memoria/ricerca dell'area di lavoro
- `--yes`: accetta i valori predefiniti senza chiedere conferma
- `--repair`: applica le riparazioni consigliate non di servizio senza chiedere conferma; le installazioni e le riscritture del servizio Gateway richiedono comunque conferma interattiva o comandi Gateway espliciti
- `--fix`: alias di `--repair`
- `--repair`: applica le riparazioni consigliate non relative al servizio senza chiedere conferma; le installazioni e le riscritture del servizio Gateway richiedono comunque conferma interattiva o comandi Gateway espliciti
- `--fix`: alias per `--repair`
- `--force`: applica riparazioni aggressive, inclusa la sovrascrittura della configurazione personalizzata del servizio quando necessario
- `--non-interactive`: esegue senza prompt; solo migrazioni sicure e riparazioni non di servizio
- `--non-interactive`: esegui senza prompt; solo migrazioni sicure e riparazioni non relative al servizio
- `--generate-gateway-token`: genera e configura un token del Gateway
- `--deep`: analizza i servizi di sistema alla ricerca di installazioni Gateway aggiuntive
- `--deep`: analizza i servizi di sistema alla ricerca di installazioni Gateway aggiuntive e segnala i recenti passaggi di consegna del riavvio del supervisore Gateway
Note:
- I prompt interattivi (come le correzioni keychain/OAuth) vengono eseguiti solo quando stdin è un TTY e `--non-interactive` **non** è impostato. Le esecuzioni headless (Cron, Telegram, nessun terminale) salteranno i prompt.
- Prestazioni: le esecuzioni non interattive di `doctor` saltano il caricamento anticipato dei plugin, così i controlli di integrità headless restano rapidi. Le sessioni interattive continuano a caricare completamente i plugin quando un controllo richiede il loro contributo.
- `--fix` (alias di `--repair`) scrive un backup in `~/.openclaw/openclaw.json.bak` e rimuove le chiavi di configurazione sconosciute, elencando ogni rimozione.
- `doctor --fix --non-interactive` segnala definizioni del servizio Gateway mancanti o obsolete, ma non le installa né le riscrive fuori dalla modalità di riparazione degli aggiornamenti. Esegui `openclaw gateway install` per un servizio mancante, oppure `openclaw gateway install --force` quando vuoi intenzionalmente sostituire il launcher.
- I controlli di integrità dello stato ora rilevano file di trascrizione orfani nella directory delle sessioni. L'archiviazione come `.deleted.<timestamp>` richiede una conferma interattiva; `--fix`, `--yes` e le esecuzioni headless li lasciano al loro posto.
- Doctor analizza anche `~/.openclaw/cron/jobs.json` (o `cron.store`) alla ricerca di vecchi formati dei job Cron e può riscriverli sul posto prima che lo scheduler debba normalizzarli automaticamente a runtime.
- Su Linux, doctor avvisa quando il crontab dell'utente esegue ancora il vecchio `~/.openclaw/bin/ensure-whatsapp.sh`; quello script non è più mantenuto e può registrare falsi disservizi del Gateway WhatsApp quando Cron non dispone dell'ambiente user-bus di systemd.
- Doctor pulisce lo stato legacy di staging delle dipendenze dei plugin creato da versioni precedenti di OpenClaw. Ripara anche i plugin scaricabili mancanti che sono referenziati dalla configurazione, come `plugins.entries`, canali configurati, impostazioni provider/ricerca configurate o runtime agent configurati. Durante gli aggiornamenti dei pacchetti, doctor salta la riparazione dei plugin del gestore pacchetti finché la sostituzione del pacchetto non è completa; riesegui `openclaw doctor --fix` in seguito se un plugin configurato richiede ancora recupero. Se il download non riesce, doctor segnala l'errore di installazione e conserva la voce del plugin configurato per il tentativo di riparazione successivo.
- Doctor ripara la configurazione obsoleta dei plugin rimuovendo gli id dei plugin mancanti da `plugins.allow`/`plugins.entries`, oltre alla configurazione del canale pendente corrispondente, ai target Heartbeat e agli override del modello del canale quando la discovery dei plugin è integra.
- Doctor mette in quarantena la configurazione non valida dei plugin disabilitando la voce `plugins.entries.<id>` interessata e rimuovendo il relativo payload `config` non valido. L'avvio del Gateway salta già solo quel plugin errato, così gli altri plugin e canali possono continuare a funzionare.
- Imposta `OPENCLAW_SERVICE_REPAIR_POLICY=external` quando un altro supervisor possiede il ciclo di vita del Gateway. Doctor continua a segnalare lo stato di integrità del Gateway/servizio e applica riparazioni non di servizio, ma salta installazione/avvio/riavvio/bootstrap del servizio e la pulizia dei servizi legacy.
- Su Linux, doctor ignora unità systemd inattive aggiuntive simili a Gateway e non riscrive i metadati di comando/entrypoint per un servizio Gateway systemd in esecuzione durante la riparazione. Arresta prima il servizio oppure usa `openclaw gateway install --force` quando vuoi intenzionalmente sostituire il launcher attivo.
- Doctor migra automaticamente la vecchia configurazione Talk piatta (`talk.voiceId`, `talk.modelId` e simili) in `talk.provider` + `talk.providers.<provider>`.
- Le esecuzioni ripetute di `doctor --fix` non segnalano/applicano più la normalizzazione Talk quando l'unica differenza è l'ordine delle chiavi dell'oggetto.
- I prompt interattivi (come le correzioni keychain/OAuth) vengono eseguiti solo quando stdin è un TTY e `--non-interactive` **non** è impostato. Le esecuzioni headless (cron, Telegram, senza terminale) salteranno i prompt.
- Prestazioni: le esecuzioni non interattive di `doctor` saltano il caricamento anticipato dei plugin, così i controlli di integrità headless restano rapidi. Le sessioni interattive caricano comunque completamente i plugin quando un controllo richiede il loro contributo.
- `--fix` (alias per `--repair`) scrive un backup in `~/.openclaw/openclaw.json.bak` ed elimina le chiavi di configurazione sconosciute, elencando ogni rimozione.
- `doctor --fix --non-interactive` segnala definizioni mancanti o obsolete del servizio Gateway ma non le installa né le riscrive al di fuori della modalità di riparazione dell'aggiornamento. Esegui `openclaw gateway install` per un servizio mancante, oppure `openclaw gateway install --force` quando vuoi intenzionalmente sostituire il launcher.
- I controlli di integrità dello stato ora rilevano file di transcript orfani nella directory delle sessioni. L'archiviazione come `.deleted.<timestamp>` richiede una conferma interattiva; `--fix`, `--yes` e le esecuzioni headless li lasciano al loro posto.
- Doctor analizza anche `~/.openclaw/cron/jobs.json` (o `cron.store`) alla ricerca di forme legacy dei processi cron e può riscriverle sul posto prima che lo scheduler debba normalizzarle automaticamente a runtime.
- Su Linux, doctor avvisa quando il crontab dell'utente esegue ancora il legacy `~/.openclaw/bin/ensure-whatsapp.sh`; quello script non è più mantenuto e può registrare falsi outage del Gateway WhatsApp quando cron non dispone dell'ambiente user-bus di systemd.
- Quando WhatsApp è abilitato, doctor controlla se esiste un event loop del Gateway degradato con client locali `openclaw-tui` ancora in esecuzione. `doctor --fix` arresta solo i client TUI locali verificati, così le risposte WhatsApp non vengono accodate dietro cicli di aggiornamento TUI obsoleti.
- Doctor pulisce lo stato legacy di staging delle dipendenze dei plugin creato da versioni precedenti di OpenClaw. Ripara anche i plugin scaricabili mancanti a cui fa riferimento la configurazione, come `plugins.entries`, canali configurati, impostazioni provider/ricerca configurate o runtime agente configurati. Durante gli aggiornamenti del pacchetto, doctor salta la riparazione dei plugin del gestore pacchetti finché la sostituzione del pacchetto non è completa; riesegui `openclaw doctor --fix` in seguito se un plugin configurato necessita ancora di ripristino. Se il download fallisce, doctor segnala l'errore di installazione e preserva la voce del plugin configurata per il prossimo tentativo di riparazione.
- Doctor ripara la configurazione obsoleta dei plugin rimuovendo gli ID dei plugin mancanti da `plugins.allow`/`plugins.entries`, più la configurazione dei canali pendente corrispondente, le destinazioni heartbeat e gli override del modello canale quando il rilevamento dei plugin è integro.
- Doctor mette in quarantena la configurazione plugin non valida disabilitando la voce `plugins.entries.<id>` interessata e rimuovendo il relativo payload `config` non valido. L'avvio del Gateway salta già solo quel plugin difettoso, così gli altri plugin e canali possono continuare a funzionare.
- Imposta `OPENCLAW_SERVICE_REPAIR_POLICY=external` quando un altro supervisore gestisce il ciclo di vita del Gateway. Doctor segnala comunque l'integrità del Gateway/servizio e applica le riparazioni non relative al servizio, ma salta installazione/avvio/riavvio/bootstrap del servizio e la pulizia dei servizi legacy.
- Su Linux, doctor ignora le unità systemd inattive aggiuntive simili al Gateway e non riscrive i metadati di comando/entrypoint per un servizio Gateway systemd in esecuzione durante la riparazione. Arresta prima il servizio oppure usa `openclaw gateway install --force` quando vuoi intenzionalmente sostituire il launcher attivo.
- Doctor migra automaticamente la configurazione flat legacy di Talk (`talk.voiceId`, `talk.modelId` e simili) in `talk.provider` + `talk.providers.<provider>`.
- Le esecuzioni ripetute di `doctor --fix` non segnalano/applicano più la normalizzazione di Talk quando l'unica differenza è l'ordine delle chiavi dell'oggetto.
- Doctor include un controllo di prontezza della ricerca in memoria e può consigliare `openclaw configure --section model` quando mancano le credenziali di embedding.
- Doctor avvisa quando non è configurato alcun proprietario dei comandi. Il proprietario dei comandi è l'account dell'operatore umano autorizzato a eseguire comandi riservati al proprietario e ad approvare azioni pericolose. L'associazione in DM permette solo a qualcuno di parlare con il bot; se hai approvato un mittente prima che esistesse il bootstrap del primo proprietario, imposta esplicitamente `commands.ownerAllowFrom`.
- Doctor avvisa quando sono configurati agent in modalità Codex e asset personali della CLI Codex esistono nella home Codex dell'operatore. Gli avvii del server app Codex locale usano home isolate per agent, quindi usa `openclaw migrate codex --dry-run` per inventariare gli asset che dovrebbero essere promossi deliberatamente.
- Doctor avvisa quando le Skills consentite per l'agent predefinito non sono disponibili nell'ambiente runtime corrente perché mancano binari, variabili d'ambiente, configurazione o requisiti del sistema operativo. `doctor --fix` può disabilitare quelle Skills non disponibili con `skills.entries.<skill>.enabled=false`; installa/configura invece il requisito mancante quando vuoi mantenere attiva la skill.
- Se la modalità sandbox è abilitata ma Docker non è disponibile, doctor segnala un avviso ad alto segnale con rimedio (`install Docker` oppure `openclaw config set agents.defaults.sandbox.mode off`).
- Se sono presenti file di registro sandbox legacy (`~/.openclaw/sandbox/containers.json` o `~/.openclaw/sandbox/browsers.json`), doctor li segnala; `openclaw doctor --fix` migra le voci valide in directory di registro sharded e mette in quarantena i file legacy non validi.
- Se `gateway.auth.token`/`gateway.auth.password` sono gestiti da SecretRef e non disponibili nel percorso di comando corrente, doctor segnala un avviso di sola lettura e non scrive credenziali fallback in testo in chiaro.
- Se l'ispezione di SecretRef del canale fallisce in un percorso di correzione, doctor continua e segnala un avviso invece di uscire anticipatamente.
- Dopo le migrazioni della directory di stato, doctor avvisa quando gli account Telegram o Discord predefiniti abilitati dipendono dal fallback dell'ambiente e `TELEGRAM_BOT_TOKEN` o `DISCORD_BOT_TOKEN` non sono disponibili per il processo doctor.
- La risoluzione automatica degli username `allowFrom` di Telegram (`doctor --fix`) richiede un token Telegram risolvibile nel percorso di comando corrente. Se l'ispezione del token non è disponibile, doctor segnala un avviso e salta la risoluzione automatica per quel passaggio.
- Doctor avvisa quando non è configurato alcun proprietario dei comandi. Il proprietario dei comandi è l'account dell'operatore umano autorizzato a eseguire comandi riservati al proprietario e ad approvare azioni pericolose. L'abbinamento DM permette solo a qualcuno di parlare con il bot; se hai approvato un mittente prima che esistesse il bootstrap del primo proprietario, imposta esplicitamente `commands.ownerAllowFrom`.
- Doctor avvisa quando sono configurati agenti in modalità Codex ed esistono asset personali della CLI Codex nella home Codex dell'operatore. Gli avvii locali del server app Codex usano home isolate per ogni agente, quindi usa `openclaw migrate codex --dry-run` per inventariare gli asset che dovrebbero essere promossi deliberatamente.
- Doctor avvisa quando le skills consentite per l'agente predefinito non sono disponibili nell'ambiente runtime corrente perché mancano binari, variabili di ambiente, configurazione o requisiti del sistema operativo. `doctor --fix` può disabilitare quelle skills non disponibili con `skills.entries.<skill>.enabled=false`; installa/configura invece il requisito mancante quando vuoi mantenere attiva la skill.
- Se la modalità sandbox è abilitata ma Docker non è disponibile, doctor segnala un avviso ad alto segnale con rimedio (`install Docker` o `openclaw config set agents.defaults.sandbox.mode off`).
- Se sono presenti file legacy del registro sandbox (`~/.openclaw/sandbox/containers.json` o `~/.openclaw/sandbox/browsers.json`), doctor li segnala; `openclaw doctor --fix` migra le voci valide in directory di registro partizionate e mette in quarantena i file legacy non validi.
- Se `gateway.auth.token`/`gateway.auth.password` sono gestiti da SecretRef e non disponibili nel percorso del comando corrente, doctor segnala un avviso di sola lettura e non scrive credenziali di fallback in testo normale.
- Se l'ispezione SecretRef del canale fallisce in un percorso di correzione, doctor continua e segnala un avviso invece di uscire in anticipo.
- Dopo le migrazioni della directory di stato, doctor avvisa quando gli account Telegram o Discord predefiniti abilitati dipendono dal fallback env e `TELEGRAM_BOT_TOKEN` o `DISCORD_BOT_TOKEN` non è disponibile per il processo doctor.
- La risoluzione automatica dello username Telegram `allowFrom` (`doctor --fix`) richiede un token Telegram risolvibile nel percorso del comando corrente. Se l'ispezione del token non è disponibile, doctor segnala un avviso e salta la risoluzione automatica per quel passaggio.
## macOS: override dell'ambiente `launchctl`
## macOS: override env di `launchctl`
Se in precedenza hai eseguito `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (o `...PASSWORD`), quel valore sovrascrive il tuo file di configurazione e può causare errori persistenti di “non autorizzato”.
Se in precedenza hai eseguito `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (o `...PASSWORD`), quel valore sovrascrive il file di configurazione e può causare errori persistenti di “non autorizzato”.
```bash
launchctl getenv OPENCLAW_GATEWAY_TOKEN
@ -82,7 +83,7 @@ launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD
```
## Correlato
## Correlati
- [Riferimento CLI](/it/cli)
- [Doctor del Gateway](/it/gateway/doctor)

265
docs/it/cli/gateway.md
View File

@ -1,16 +1,16 @@
---
read_when:
- Esecuzione del Gateway dalla CLI (sviluppo o server)
- Debug dell'autenticazione del Gateway, delle modalità di bind e della connettività
- Rilevamento dei Gateway tramite Bonjour (DNS-SD locale + ad area estesa)
- Risoluzione dei problemi relativi all'autenticazione del Gateway, alle modalità di associazione e alla connettività
- Individuazione dei Gateway tramite Bonjour (DNS-SD locale e su rete geografica)
sidebarTitle: Gateway
summary: OpenClaw Gateway CLI (`openclaw gateway`) — avvia, interroga e rileva Gateway
summary: CLI di OpenClaw Gateway (`openclaw gateway`) — esegui, interroga e scopri i Gateway
title: Gateway
x-i18n:
generated_at: "2026-05-05T01:44:26Z"
generated_at: "2026-05-05T08:25:52Z"
model: gpt-5.5
provider: openai
source_hash: 521558189b150b2faa22f95ec32419ac9e02c5f47c72b9095f40d1432840c038
source_hash: 89f798724971151cdd297fcdbbc1fe79dedc19f57521f2ad2c1fff0f9acf9b24
source_path: cli/gateway.md
workflow: 16
---
@ -18,14 +18,14 @@ x-i18n:
Il Gateway è il server WebSocket di OpenClaw (canali, nodi, sessioni, hook). I sottocomandi in questa pagina si trovano sotto `openclaw gateway …`.
<CardGroup cols={3}>
<Card title="Scoperta Bonjour" href="/it/gateway/bonjour">
Configurazione mDNS locale + DNS-SD wide-area.
<Card title="Bonjour discovery" href="/it/gateway/bonjour">
Configurazione mDNS locale + DNS-SD ad ampia area.
</Card>
<Card title="Panoramica della scoperta" href="/it/gateway/discovery">
<Card title="Discovery overview" href="/it/gateway/discovery">
Come OpenClaw pubblicizza e trova i gateway.
</Card>
<Card title="Configurazione" href="/it/gateway/configuration">
Chiavi di configurazione gateway di primo livello.
<Card title="Configuration" href="/it/gateway/configuration">
Chiavi di configurazione gateway di livello superiore.
</Card>
</CardGroup>
@ -44,13 +44,13 @@ openclaw gateway run
```
<AccordionGroup>
<Accordion title="Comportamento all'avvio">
- Per impostazione predefinita, il Gateway si rifiuta di avviarsi a meno che `gateway.mode=local` non sia impostato in `~/.openclaw/openclaw.json`. Usa `--allow-unconfigured` per esecuzioni ad hoc/di sviluppo.
- `openclaw onboard --mode local` e `openclaw setup` dovrebbero scrivere `gateway.mode=local`. Se il file esiste ma `gateway.mode` manca, consideralo una configurazione rotta o sovrascritta e riparala invece di presupporre implicitamente la modalità locale.
- Se il file esiste e `gateway.mode` manca, il Gateway considera la situazione un danno sospetto alla configurazione e si rifiuta di "indovinare local" per te.
- L'associazione oltre il loopback senza auth è bloccata (protezione di sicurezza).
- `SIGUSR1` attiva un riavvio nel processo quando autorizzato (`commands.restart` è abilitato per impostazione predefinita; imposta `commands.restart: false` per bloccare il riavvio manuale, mentre apply/update di strumenti/configurazione gateway restano consentiti).
- I gestori `SIGINT`/`SIGTERM` arrestano il processo gateway, ma non ripristinano alcuno stato personalizzato del terminale. Se avvolgi la CLI con una TUI o input in modalità raw, ripristina il terminale prima di uscire.
<Accordion title="Startup behavior">
- Per impostazione predefinita, il Gateway rifiuta di avviarsi a meno che `gateway.mode=local` sia impostato in `~/.openclaw/openclaw.json`. Usa `--allow-unconfigured` per esecuzioni ad hoc/di sviluppo.
- `openclaw onboard --mode local` e `openclaw setup` devono scrivere `gateway.mode=local`. Se il file esiste ma `gateway.mode` manca, trattalo come una configurazione rotta o sovrascritta e riparala invece di presumere implicitamente la modalità locale.
- Se il file esiste e `gateway.mode` manca, il Gateway lo considera un danno sospetto alla configurazione e rifiuta di "indovinare local" per te.
- Il binding oltre il loopback senza autenticazione è bloccato (protezione di sicurezza).
- `SIGUSR1` attiva un riavvio in-process quando autorizzato (`commands.restart` è abilitato per impostazione predefinita; imposta `commands.restart: false` per bloccare il riavvio manuale, mentre applicazione/aggiornamento di strumenti/configurazione del gateway restano consentiti).
- I gestori `SIGINT`/`SIGTERM` arrestano il processo gateway, ma non ripristinano alcuno stato personalizzato del terminale. Se avvolgi la CLI con una TUI o input in raw mode, ripristina il terminale prima dell'uscita.
</Accordion>
</AccordionGroup>
@ -58,13 +58,13 @@ openclaw gateway run
### Opzioni
<ParamField path="--port <port>" type="number">
Porta WebSocket (il valore predefinito proviene da configurazione/env; di solito `18789`).
Porta WebSocket (il valore predefinito viene da configurazione/env; di solito `18789`).
</ParamField>
<ParamField path="--bind <loopback|lan|tailnet|auto|custom>" type="string">
Modalità di associazione del listener.
Modalità di binding del listener.
</ParamField>
<ParamField path="--auth <token|password>" type="string">
Override della modalità auth.
Override della modalità di autenticazione.
</ParamField>
<ParamField path="--token <token>" type="string">
Override del token (imposta anche `OPENCLAW_GATEWAY_TOKEN` per il processo).
@ -85,7 +85,7 @@ openclaw gateway run
Consenti l'avvio del gateway senza `gateway.mode=local` nella configurazione. Aggira la protezione di avvio solo per bootstrap ad hoc/di sviluppo; non scrive né ripara il file di configurazione.
</ParamField>
<ParamField path="--dev" type="boolean">
Crea una configurazione + workspace di sviluppo se mancanti (salta BOOTSTRAP.md).
Crea una configurazione + workspace di sviluppo se mancano (salta BOOTSTRAP.md).
</ParamField>
<ParamField path="--reset" type="boolean">
Reimposta configurazione di sviluppo + credenziali + sessioni + workspace (richiede `--dev`).
@ -120,30 +120,30 @@ openclaw gateway restart --safe
openclaw gateway restart --force
```
`openclaw gateway restart --safe` chiede al Gateway in esecuzione di eseguire un preflight del lavoro OpenClaw attivo prima di riavviare. Se operazioni in coda, consegna delle risposte, esecuzioni incorporate o esecuzioni di task sono attive, il Gateway segnala i blocchi, accorpa le richieste duplicate di riavvio sicuro e riavvia una volta che il lavoro attivo si è svuotato. Il semplice `restart` mantiene il comportamento esistente del gestore del servizio per compatibilità. Usa `--force` solo quando vuoi esplicitamente il percorso di override immediato.
`openclaw gateway restart --safe` chiede al Gateway in esecuzione di eseguire un controllo preliminare del lavoro OpenClaw attivo prima del riavvio. Se sono attive operazioni in coda, consegna delle risposte, esecuzioni incorporate o esecuzioni di attività, il Gateway segnala i blocchi, unisce le richieste duplicate di riavvio sicuro e riavvia quando il lavoro attivo si esaurisce. Il semplice `restart` mantiene il comportamento esistente del service manager per compatibilità. Usa `--force` solo quando vuoi esplicitamente il percorso di override immediato.
<Warning>
`--password` inline può essere esposto negli elenchi dei processi locali. Preferisci `--password-file`, env o un `gateway.auth.password` basato su SecretRef.
`--password` inline può essere esposta negli elenchi dei processi locali. Preferisci `--password-file`, env o una `gateway.auth.password` basata su SecretRef.
</Warning>
### Profilazione dell'avvio
- Imposta `OPENCLAW_GATEWAY_STARTUP_TRACE=1` per registrare i tempi delle fasi durante l'avvio del Gateway, inclusi il ritardo `eventLoopMax` per fase e i tempi della tabella di lookup dei Plugin per indice installato, registro manifest, pianificazione dell'avvio e lavoro sulla mappa dei proprietari.
- Imposta `OPENCLAW_DIAGNOSTICS=timeline` con `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>` per scrivere una timeline diagnostica di avvio JSONL best-effort per harness QA esterni. Puoi anche abilitare il flag con `diagnostics.flags: ["timeline"]` nella configurazione; il percorso è comunque fornito tramite env. Aggiungi `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` per includere campioni dell'event loop.
- Esegui `pnpm test:startup:gateway -- --runs 5 --warmup 1` per misurare le prestazioni dell'avvio del Gateway. Il benchmark registra il primo output del processo, `/healthz`, `/readyz`, i tempi della traccia di avvio, il ritardo dell'event loop e i dettagli dei tempi della tabella di lookup dei Plugin.
- Imposta `OPENCLAW_GATEWAY_STARTUP_TRACE=1` per registrare i tempi delle fasi durante l'avvio del Gateway, inclusi il ritardo `eventLoopMax` per fase e i tempi delle tabelle di lookup dei plugin per installed-index, manifest registry, pianificazione dell'avvio e lavoro owner-map.
- Imposta `OPENCLAW_DIAGNOSTICS=timeline` con `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>` per scrivere una timeline diagnostica di avvio JSONL best-effort per harness QA esterni. Puoi anche abilitare il flag con `diagnostics.flags: ["timeline"]` nella configurazione; il percorso è comunque fornito da env. Aggiungi `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` per includere campioni dell'event-loop.
- Esegui `pnpm test:startup:gateway -- --runs 5 --warmup 1` per misurare le prestazioni dell'avvio del Gateway. Il benchmark registra il primo output del processo, `/healthz`, `/readyz`, i tempi della traccia di avvio, il ritardo dell'event-loop e i dettagli dei tempi delle tabelle di lookup dei plugin.
## Interrogare un Gateway in esecuzione
Tutti i comandi di interrogazione usano RPC WebSocket.
Tutti i comandi di query usano WebSocket RPC.
<Tabs>
<Tab title="Modalità di output">
<Tab title="Output modes">
- Predefinito: leggibile da persone (colorato in TTY).
- `--json`: JSON leggibile dalla macchina (senza stile/spinner).
- `--json`: JSON leggibile da macchine (senza stile/spinner).
- `--no-color` (o `NO_COLOR=1`): disabilita ANSI mantenendo il layout per persone.
</Tab>
<Tab title="Opzioni condivise">
<Tab title="Shared options">
- `--url <url>`: URL WebSocket del Gateway.
- `--token <token>`: token del Gateway.
- `--password <password>`: password del Gateway.
@ -154,7 +154,7 @@ Tutti i comandi di interrogazione usano RPC WebSocket.
</Tabs>
<Note>
Quando imposti `--url`, la CLI non ripiega sulle credenziali da configurazione o ambiente. Passa esplicitamente `--token` o `--password`. Le credenziali esplicite mancanti sono un errore.
Quando imposti `--url`, la CLI non ripiega su configurazione o credenziali d'ambiente. Passa `--token` o `--password` esplicitamente. La mancanza di credenziali esplicite è un errore.
</Note>
### `gateway health`
@ -163,7 +163,7 @@ Quando imposti `--url`, la CLI non ripiega sulle credenziali da configurazione o
openclaw gateway health --url ws://127.0.0.1:18789
```
L'endpoint HTTP `/healthz` è una sonda di liveness: restituisce una risposta appena il server può rispondere via HTTP. L'endpoint HTTP `/readyz` è più rigoroso e resta rosso mentre sidecar Plugin di avvio, canali o hook configurati si stanno ancora stabilizzando. Le risposte locali o autenticate di readiness dettagliata includono un blocco diagnostico `eventLoop` con ritardo dell'event loop, utilizzo dell'event loop, rapporto dei core CPU e un flag `degraded`.
L'endpoint HTTP `/healthz` è una sonda di liveness: restituisce una risposta quando il server può rispondere via HTTP. L'endpoint HTTP `/readyz` è più rigoroso e resta rosso mentre sidecar di plugin di avvio, canali o hook configurati si stanno ancora stabilizzando. Le risposte dettagliate di readiness locali o autenticate includono un blocco diagnostico `eventLoop` con ritardo dell'event-loop, utilizzo dell'event-loop, rapporto dei core CPU e un flag `degraded`.
### `gateway usage-cost`
@ -181,7 +181,7 @@ openclaw gateway usage-cost --json
### `gateway stability`
Recupera il recorder diagnostico di stabilità recente da un Gateway in esecuzione.
Recupera il registratore diagnostico di stabilità recente da un Gateway in esecuzione.
```bash
openclaw gateway stability
@ -211,16 +211,16 @@ openclaw gateway stability --json
</ParamField>
<AccordionGroup>
<Accordion title="Privacy e comportamento dei bundle">
- I record mantengono metadati operativi: nomi degli eventi, conteggi, dimensioni in byte, letture di memoria, stato di code/sessioni, nomi di canali/Plugin e riepiloghi di sessione oscurati. Non mantengono testo delle chat, body dei webhook, output degli strumenti, body raw di richieste o risposte, token, cookie, valori segreti, hostname o ID raw delle sessioni. Imposta `diagnostics.enabled: false` per disabilitare completamente il recorder.
- In caso di uscite fatali del Gateway, timeout di spegnimento e fallimenti di avvio al riavvio, OpenClaw scrive lo stesso snapshot diagnostico in `~/.openclaw/logs/stability/openclaw-stability-*.json` quando il recorder ha eventi. Ispeziona il bundle più recente con `openclaw gateway stability --bundle latest`; anche `--limit`, `--type` e `--since-seq` si applicano all'output del bundle.
<Accordion title="Privacy and bundle behavior">
- I record conservano metadati operativi: nomi evento, conteggi, dimensioni in byte, letture di memoria, stato di coda/sessione, nomi di canali/plugin e riepiloghi di sessione redatti. Non conservano testo di chat, corpi webhook, output di strumenti, corpi raw di richieste o risposte, token, cookie, valori segreti, nomi host o id raw di sessione. Imposta `diagnostics.enabled: false` per disabilitare completamente il registratore.
- In caso di uscite fatali del Gateway, timeout di spegnimento e fallimenti di avvio dopo riavvio, OpenClaw scrive lo stesso snapshot diagnostico in `~/.openclaw/logs/stability/openclaw-stability-*.json` quando il registratore ha eventi. Ispeziona il bundle più recente con `openclaw gateway stability --bundle latest`; `--limit`, `--type` e `--since-seq` si applicano anche all'output del bundle.
</Accordion>
</AccordionGroup>
### `gateway diagnostics export`
Scrive uno zip di diagnostica locale progettato per essere allegato ai report di bug. Per il modello di privacy e i contenuti del bundle, vedi [Esportazione diagnostica](/it/gateway/diagnostics).
Scrivi uno zip di diagnostica locale progettato per essere allegato alle segnalazioni di bug. Per il modello di privacy e i contenuti del bundle, consulta [Esportazione diagnostica](/it/gateway/diagnostics).
```bash
openclaw gateway diagnostics export
@ -238,16 +238,16 @@ openclaw gateway diagnostics export --json
Numero massimo di byte di log da ispezionare.
</ParamField>
<ParamField path="--url <url>" type="string">
URL WebSocket del Gateway per lo snapshot di health.
URL WebSocket del Gateway per lo snapshot di salute.
</ParamField>
<ParamField path="--token <token>" type="string">
Token del Gateway per lo snapshot di health.
Token del Gateway per lo snapshot di salute.
</ParamField>
<ParamField path="--password <password>" type="string">
Password del Gateway per lo snapshot di health.
Password del Gateway per lo snapshot di salute.
</ParamField>
<ParamField path="--timeout <ms>" type="number" default="3000">
Timeout dello snapshot di stato/health.
Timeout dello snapshot di stato/salute.
</ParamField>
<ParamField path="--no-stability-bundle" type="boolean">
Salta la ricerca del bundle di stabilità persistito.
@ -256,13 +256,13 @@ openclaw gateway diagnostics export --json
Stampa il percorso scritto, la dimensione e il manifest come JSON.
</ParamField>
L'esportazione contiene un manifest, un riepilogo Markdown, la forma della configurazione, dettagli di configurazione sanificati, riepiloghi dei log sanificati, snapshot di stato/health del Gateway sanificati e il bundle di stabilità più recente quando ne esiste uno.
L'esportazione contiene un manifest, un riepilogo Markdown, forma della configurazione, dettagli di configurazione sanificati, riepiloghi dei log sanificati, snapshot di stato/salute del Gateway sanificati e il bundle di stabilità più recente quando esiste.
È pensata per essere condivisa. Mantiene dettagli operativi utili al debug, come campi sicuri dei log OpenClaw, nomi di sottosistemi, codici di stato, durate, modalità configurate, porte, ID Plugin, ID provider, impostazioni di funzionalità non segrete e messaggi di log operativi oscurati. Omette o oscura testo delle chat, body dei webhook, output degli strumenti, credenziali, cookie, identificatori di account/messaggi, testo di prompt/istruzioni, hostname e valori segreti. Quando un messaggio in stile LogTape sembra testo payload utente/chat/strumento, l'esportazione conserva solo il fatto che un messaggio è stato omesso più il suo conteggio di byte.
È pensata per essere condivisa. Conserva dettagli operativi che aiutano il debug, come campi sicuri dei log OpenClaw, nomi dei sottosistemi, codici di stato, durate, modalità configurate, porte, id plugin, id provider, impostazioni di funzionalità non segrete e messaggi di log operativi redatti. Omette o redige testo di chat, corpi webhook, output di strumenti, credenziali, cookie, identificatori account/messaggio, testo di prompt/istruzioni, nomi host e valori segreti. Quando un messaggio in stile LogTape sembra testo di payload utente/chat/strumento, l'esportazione conserva solo il fatto che un messaggio è stato omesso più il suo conteggio di byte.
### `gateway status`
`gateway status` mostra il servizio Gateway (launchd/systemd/schtasks) più una sonda opzionale della capacità di connettività/auth.
`gateway status` mostra il servizio Gateway (launchd/systemd/schtasks) più una sonda opzionale di capacità di connettività/autenticazione.
```bash
openclaw gateway status
@ -271,63 +271,64 @@ openclaw gateway status --require-rpc
```
<ParamField path="--url <url>" type="string">
Aggiunge un target di probe esplicito. Il remoto configurato + localhost vengono comunque sottoposti a probe.
Aggiunge un target esplicito per la sonda. Il remoto configurato e localhost vengono comunque sondati.
</ParamField>
<ParamField path="--token <token>" type="string">
Autenticazione con token per il probe.
Autenticazione tramite token per la sonda.
</ParamField>
<ParamField path="--password <password>" type="string">
Autenticazione con password per il probe.
Autenticazione tramite password per la sonda.
</ParamField>
<ParamField path="--timeout <ms>" type="number" default="10000">
Timeout del probe.
Timeout della sonda.
</ParamField>
<ParamField path="--no-probe" type="boolean">
Salta il probe di connettività (vista solo servizio).
Salta la sonda di connettivita (vista solo del servizio).
</ParamField>
<ParamField path="--deep" type="boolean">
Scansiona anche i servizi a livello di sistema.
Analizza anche i servizi a livello di sistema.
</ParamField>
<ParamField path="--require-rpc" type="boolean">
Promuove il probe di connettività predefinito a un probe di lettura ed esce con codice diverso da zero quando quel probe di lettura fallisce. Non può essere combinato con `--no-probe`.
Promuove la sonda di connettivita predefinita a una sonda di lettura ed esce con codice diverso da zero quando tale sonda di lettura fallisce. Non puo essere combinato con `--no-probe`.
</ParamField>
<AccordionGroup>
<Accordion title="Semantica dello stato">
- `gateway status` resta disponibile per la diagnostica anche quando la configurazione CLI locale è mancante o non valida.
- `gateway status` predefinito verifica lo stato del servizio, la connessione WebSocket e la capacità di autenticazione visibile al momento dell'handshake. Non verifica le operazioni di lettura/scrittura/amministrazione.
- I probe diagnostici non modificano l'autenticazione dei dispositivi al primo uso: riutilizzano un token dispositivo già presente nella cache quando esiste, ma non creano una nuova identità dispositivo CLI o un record di associazione dispositivo di sola lettura solo per controllare lo stato.
- `gateway status` risolve, quando possibile, i SecretRefs di autenticazione configurati per l'autenticazione del probe.
- Se un SecretRef di autenticazione richiesto non viene risolto in questo percorso del comando, `gateway status --json` segnala `rpc.authWarning` quando connettività/autenticazione del probe fallisce; passa `--token`/`--password` esplicitamente oppure risolvi prima l'origine del segreto.
- Se il probe riesce, gli avvisi auth-ref non risolti vengono soppressi per evitare falsi positivi.
- Usa `--require-rpc` negli script e nell'automazione quando un servizio in ascolto non basta e servono anche chiamate RPC con scope di lettura funzionanti.
- `--deep` aggiunge una scansione best-effort per installazioni launchd/systemd/schtasks aggiuntive. Quando vengono rilevati più servizi simili a gateway, l'output per utenti mostra suggerimenti di pulizia e avvisa che la maggior parte delle configurazioni dovrebbe eseguire un solo gateway per macchina.
- L'output per utenti include il percorso risolto del log su file più lo snapshot dei percorsi/validità della configurazione CLI rispetto al servizio, per aiutare a diagnosticare deriva di profilo o state-dir.
<Accordion title="Status semantics">
- `gateway status` resta disponibile per la diagnostica anche quando la configurazione della CLI locale manca o non e valida.
- `gateway status` predefinito verifica lo stato del servizio, la connessione WebSocket e la capacita di autenticazione visibile al momento dell'handshake. Non verifica le operazioni di lettura/scrittura/amministrazione.
- Le sonde diagnostiche non modificano l'autenticazione del dispositivo al primo utilizzo: riutilizzano un token dispositivo memorizzato nella cache quando esiste, ma non creano una nuova identita dispositivo della CLI ne un record di associazione dispositivo in sola lettura solo per controllare lo stato.
- `gateway status` risolve i SecretRef di autenticazione configurati per l'autenticazione della sonda quando possibile.
- Se un SecretRef di autenticazione richiesto non viene risolto in questo percorso di comando, `gateway status --json` riporta `rpc.authWarning` quando connettivita/autenticazione della sonda fallisce; passa esplicitamente `--token`/`--password` oppure risolvi prima l'origine del segreto.
- Se la sonda riesce, gli avvisi di riferimento di autenticazione non risolto vengono soppressi per evitare falsi positivi.
- Usa `--require-rpc` in script e automazione quando un servizio in ascolto non basta e ti serve che anche le chiamate RPC con ambito di lettura siano integre.
- `--deep` aggiunge una scansione best-effort per installazioni aggiuntive launchd/systemd/schtasks. Quando vengono rilevati piu servizi simili al Gateway, l'output umano stampa suggerimenti di pulizia e avvisa che la maggior parte delle configurazioni dovrebbe eseguire un solo Gateway per macchina.
- `--deep` segnala anche un recente passaggio di consegne del riavvio del supervisore Gateway quando il processo del servizio e terminato correttamente per un riavvio del supervisore esterno.
- L'output umano include il percorso risolto del file di log piu l'istantanea dei percorsi/validita della configurazione CLI rispetto al servizio per aiutare a diagnosticare divergenze di profilo o directory di stato.
</Accordion>
<Accordion title="Controlli di deriva dell'autenticazione Linux systemd">
- Nelle installazioni Linux systemd, i controlli di deriva dell'autenticazione del servizio leggono sia i valori `Environment=` sia `EnvironmentFile=` dall'unità (inclusi `%h`, percorsi tra virgolette, più file e file opzionali `-`).
- I controlli di deriva risolvono i SecretRefs `gateway.auth.token` usando l'env runtime unito (prima l'env del comando del servizio, poi il fallback all'env del processo).
- Se l'autenticazione con token non è effettivamente attiva (`gateway.auth.mode` esplicito di `password`/`none`/`trusted-proxy`, oppure modalità non impostata in cui la password può prevalere e nessun candidato token può prevalere), i controlli di token-drift saltano la risoluzione del token di configurazione.
<Accordion title="Linux systemd auth-drift checks">
- Nelle installazioni Linux systemd, i controlli di deriva dell'autenticazione del servizio leggono sia i valori `Environment=` sia `EnvironmentFile=` dall'unita (inclusi `%h`, percorsi tra virgolette, file multipli e file opzionali `-`).
- I controlli di deriva risolvono i SecretRef `gateway.auth.token` usando l'ambiente di runtime unito (prima l'ambiente del comando del servizio, poi il fallback all'ambiente del processo).
- Se l'autenticazione tramite token non e effettivamente attiva (`gateway.auth.mode` esplicito di `password`/`none`/`trusted-proxy`, oppure modalita non impostata in cui la password puo prevalere e nessun candidato token puo prevalere), i controlli di deriva del token saltano la risoluzione del token di configurazione.
</Accordion>
</AccordionGroup>
### `gateway probe`
`gateway probe` è il comando "debug di tutto". Esegue sempre il probe di:
`gateway probe` e il comando "debug di tutto". Sonda sempre:
- il tuo Gateway remoto configurato (se impostato), e
- localhost (loopback) **anche se è configurato un remoto**.
- il tuo gateway remoto configurato (se impostato), e
- localhost (loopback) **anche se e configurato un remoto**.
Se passi `--url`, quel target esplicito viene aggiunto prima di entrambi. L'output per utenti etichetta i target come:
Se passi `--url`, quel target esplicito viene aggiunto prima di entrambi. L'output umano etichetta i target come:
- `URL (explicit)`
- `Remote (configured)` o `Remote (configured, inactive)`
- `Local loopback`
<Note>
Se più Gateway sono raggiungibili, li stampa tutti. Più Gateway sono supportati quando usi profili/porte isolati (ad esempio un bot di recupero), ma la maggior parte delle installazioni esegue comunque un solo Gateway.
Se sono raggiungibili piu gateway, li stampa tutti. Piu gateway sono supportati quando usi profili/porte isolati (ad esempio, un bot di soccorso), ma la maggior parte delle installazioni esegue comunque un solo gateway.
</Note>
```bash
@ -336,52 +337,52 @@ openclaw gateway probe --json
```
<AccordionGroup>
<Accordion title="Interpretazione">
<Accordion title="Interpretation">
- `Reachable: yes` significa che almeno un target ha accettato una connessione WebSocket.
- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` segnala ciò che il probe ha potuto verificare sull'autenticazione. È separato dalla raggiungibilità.
- `Read probe: ok` significa che sono riuscite anche le chiamate RPC di dettaglio con scope di lettura (`health`/`status`/`system-presence`/`config.get`).
- `Read probe: limited - missing scope: operator.read` significa che la connessione è riuscita ma l'RPC con scope di lettura è limitato. Questo viene segnalato come raggiungibilità **degradata**, non come fallimento completo.
- `Read probe: failed` dopo `Connect: ok` significa che il Gateway ha accettato la connessione WebSocket, ma la diagnostica di lettura successiva è andata in timeout o non è riuscita. Anche questa è raggiungibilità **degradata**, non un Gateway non raggiungibile.
- Come `gateway status`, il probe riutilizza l'autenticazione dispositivo già presente nella cache ma non crea identità dispositivo al primo uso o stato di associazione.
- Il codice di uscita è diverso da zero solo quando nessun target sottoposto a probe è raggiungibile.
- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` riporta cio che la sonda ha potuto verificare sull'autenticazione. E separato dalla raggiungibilita.
- `Read probe: ok` significa che anche le chiamate RPC di dettaglio con ambito di lettura (`health`/`status`/`system-presence`/`config.get`) sono riuscite.
- `Read probe: limited - missing scope: operator.read` significa che la connessione e riuscita ma l'RPC con ambito di lettura e limitato. Questo viene riportato come raggiungibilita **degradata**, non come errore completo.
- `Read probe: failed` dopo `Connect: ok` significa che il Gateway ha accettato la connessione WebSocket, ma la diagnostica di lettura successiva e scaduta o non e riuscita. Anche questa e raggiungibilita **degradata**, non un Gateway irraggiungibile.
- Come `gateway status`, la sonda riutilizza l'autenticazione dispositivo memorizzata nella cache esistente ma non crea identita dispositivo o stato di associazione al primo utilizzo.
- Il codice di uscita e diverso da zero solo quando nessun target sondato e raggiungibile.
</Accordion>
<Accordion title="Output JSON">
<Accordion title="JSON output">
Livello superiore:
- `ok`: almeno un target è raggiungibile.
- `degraded`: almeno un target ha accettato una connessione ma non ha completato la diagnostica RPC di dettaglio completa.
- `capability`: migliore capacità vista tra i target raggiungibili (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope` o `unknown`).
- `primaryTargetId`: miglior target da trattare come vincitore attivo in quest'ordine: URL esplicito, tunnel SSH, remoto configurato, poi local loopback.
- `ok`: almeno un target e raggiungibile.
- `degraded`: almeno un target ha accettato una connessione ma non ha completato la diagnostica RPC dettagliata completa.
- `capability`: migliore capacita vista tra i target raggiungibili (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope` o `unknown`).
- `primaryTargetId`: miglior target da trattare come vincitore attivo in questo ordine: URL esplicito, tunnel SSH, remoto configurato, quindi local loopback.
- `warnings[]`: record di avviso best-effort con `code`, `message` e `targetIds` opzionali.
- `network`: suggerimenti URL local loopback/tailnet derivati dalla configurazione corrente e dalla rete host.
- `discovery.timeoutMs` e `discovery.count`: il budget di discovery effettivo/conteggio risultati usato per questo passaggio di probe.
- `network`: suggerimenti URL local loopback/tailnet derivati dalla configurazione corrente e dalla rete dell'host.
- `discovery.timeoutMs` e `discovery.count`: budget di scoperta effettivo/conteggio dei risultati usato per questo passaggio della sonda.
Per target (`targets[].connect`):
- `ok`: raggiungibilità dopo connessione + classificazione degradata.
- `rpcOk`: successo RPC di dettaglio completo.
- `scopeLimited`: RPC di dettaglio fallita a causa di scope operatore mancante.
- `ok`: raggiungibilita dopo connessione + classificazione degradata.
- `rpcOk`: successo RPC dettagliato completo.
- `scopeLimited`: RPC dettagliato fallito a causa dell'assenza dell'ambito operatore.
Per target (`targets[].auth`):
- `role`: ruolo di autenticazione segnalato in `hello-ok` quando disponibile.
- `scopes`: scope concessi segnalati in `hello-ok` quando disponibili.
- `capability`: classificazione della capacità di autenticazione esposta per quel target.
- `role`: ruolo di autenticazione riportato in `hello-ok` quando disponibile.
- `scopes`: ambiti concessi riportati in `hello-ok` quando disponibili.
- `capability`: classificazione della capacita di autenticazione esposta per quel target.
</Accordion>
<Accordion title="Codici di avviso comuni">
- `ssh_tunnel_failed`: configurazione del tunnel SSH non riuscita; il comando è ricaduto sui probe diretti.
- `multiple_gateways`: più di un target era raggiungibile; è insolito a meno che tu non esegua intenzionalmente profili isolati, come un bot di recupero.
- `auth_secretref_unresolved`: non è stato possibile risolvere un SecretRef di autenticazione configurato per un target fallito.
- `probe_scope_limited`: la connessione WebSocket è riuscita, ma il probe di lettura è stato limitato dalla mancanza di `operator.read`.
<Accordion title="Common warning codes">
- `ssh_tunnel_failed`: configurazione del tunnel SSH fallita; il comando e tornato alle sonde dirette.
- `multiple_gateways`: piu di un target era raggiungibile; e insolito a meno che tu non esegua intenzionalmente profili isolati, come un bot di soccorso.
- `auth_secretref_unresolved`: un SecretRef di autenticazione configurato non ha potuto essere risolto per un target fallito.
- `probe_scope_limited`: connessione WebSocket riuscita, ma la sonda di lettura e stata limitata dall'assenza di `operator.read`.
</Accordion>
</AccordionGroup>
#### Remoto tramite SSH (parità app Mac)
#### Remoto via SSH (parita app Mac)
La modalità "Remoto tramite SSH" dell'app macOS usa un port-forward locale così il Gateway remoto (che può essere associato solo al loopback) diventa raggiungibile su `ws://127.0.0.1:<port>`.
La modalita "Remote over SSH" dell'app macOS usa un port-forward locale affinche il gateway remoto (che potrebbe essere associato solo a loopback) diventi raggiungibile su `ws://127.0.0.1:<port>`.
Equivalente CLI:
@ -390,13 +391,13 @@ openclaw gateway probe --ssh user@gateway-host
```
<ParamField path="--ssh <target>" type="string">
`user@host` o `user@host:port` (la porta predefinita è `22`).
`user@host` o `user@host:port` (la porta predefinita e `22`).
</ParamField>
<ParamField path="--ssh-identity <path>" type="string">
File di identità.
File di identita.
</ParamField>
<ParamField path="--ssh-auto" type="boolean">
Sceglie il primo host Gateway rilevato come target SSH dall'endpoint di discovery risolto (`local.` più il dominio wide-area configurato, se presente). I suggerimenti solo TXT vengono ignorati.
Sceglie il primo host gateway scoperto come target SSH dall'endpoint di scoperta risolto (`local.` piu il dominio geografico configurato, se presente). I suggerimenti solo TXT vengono ignorati.
</ParamField>
Configurazione (opzionale, usata come valori predefiniti):
@ -414,7 +415,7 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
```
<ParamField path="--params <json>" type="string" default="{}">
Stringa oggetto JSON per params.
Stringa oggetto JSON per i parametri.
</ParamField>
<ParamField path="--url <url>" type="string">
URL WebSocket del Gateway.
@ -429,10 +430,10 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
Budget di timeout.
</ParamField>
<ParamField path="--expect-final" type="boolean">
Principalmente per RPC in stile agent che trasmettono eventi intermedi prima di un payload finale.
Principalmente per RPC in stile agente che trasmettono eventi intermedi prima di un payload finale.
</ParamField>
<ParamField path="--json" type="boolean">
Output JSON leggibile da macchina.
Output JSON leggibile dalla macchina.
</ParamField>
<Note>
@ -452,7 +453,7 @@ openclaw gateway uninstall
### Installare con un wrapper
Usa `--wrapper` quando il servizio gestito deve avviarsi tramite un altro eseguibile, ad esempio uno
shim di un gestore di segreti o un helper run-as. Il wrapper riceve i normali argomenti del Gateway ed è
shim di gestione dei segreti o un helper run-as. Il wrapper riceve i normali argomenti del Gateway ed e
responsabile di eseguire infine `openclaw` o Node con quegli argomenti.
```bash
@ -467,17 +468,17 @@ openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force
openclaw gateway restart
```
Puoi anche impostare il wrapper tramite l'ambiente. `gateway install` verifica che il percorso sia
un file eseguibile, scrive il wrapper in `ProgramArguments` del servizio e mantiene
`OPENCLAW_WRAPPER` nell'ambiente del servizio per reinstallazioni forzate, aggiornamenti e riparazioni doctor
successivi.
Puoi impostare il wrapper anche tramite l'ambiente. `gateway install` verifica che il percorso sia
un file eseguibile, scrive il wrapper in `ProgramArguments` del servizio e persiste
`OPENCLAW_WRAPPER` nell'ambiente del servizio per reinstallazioni forzate, aggiornamenti e riparazioni
doctor successivi.
```bash
OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force
openclaw doctor
```
Per rimuovere un wrapper mantenuto, svuota `OPENCLAW_WRAPPER` durante la reinstallazione:
Per rimuovere un wrapper persistito, svuota `OPENCLAW_WRAPPER` durante la reinstallazione:
```bash
OPENCLAW_WRAPPER= openclaw gateway install --force
@ -485,47 +486,47 @@ openclaw gateway restart
```
<AccordionGroup>
<Accordion title="Opzioni dei comandi">
<Accordion title="Command options">
- `gateway status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
- `gateway install`: `--port`, `--runtime <node|bun>`, `--token`, `--wrapper <path>`, `--force`, `--json`
- `gateway restart`: `--safe`, `--force`, `--wait <duration>`, `--json`
- `gateway uninstall|start|stop`: `--json`
</Accordion>
<Accordion title="Comportamento del ciclo di vita">
<Accordion title="Lifecycle behavior">
- Usa `gateway restart` per riavviare un servizio gestito. Non concatenare `gateway stop` e `gateway start` come sostituto del riavvio; su macOS, `gateway stop` disabilita intenzionalmente il LaunchAgent prima di arrestarlo.
- `gateway restart --safe` chiede al Gateway in esecuzione di verificare preventivamente il lavoro OpenClaw attivo e rinviare il riavvio finché la consegna delle risposte, le esecuzioni integrate e le esecuzioni delle attività non si svuotano. `--safe` non può essere combinato con `--force` o `--wait`.
- `gateway restart --wait 30s` sovrascrive il budget di drenaggio riavvio configurato per quel riavvio. I numeri senza unità sono millisecondi; sono accettate unità come `s`, `m` e `h`. `--wait 0` attende indefinitamente.
- `gateway restart --force` salta il drenaggio del lavoro attivo e riavvia immediatamente. Usalo quando un operatore ha già ispezionato i blocchi attività elencati e vuole ripristinare subito il gateway.
- I comandi del ciclo di vita accettano `--json` per lo scripting.
- `gateway restart --safe` chiede al Gateway in esecuzione di eseguire il preflight del lavoro OpenClaw attivo e rimandare il riavvio fino allo svuotamento della consegna delle risposte, delle esecuzioni incorporate e delle esecuzioni dei task. `--safe` non puo essere combinato con `--force` o `--wait`.
- `gateway restart --wait 30s` sostituisce il budget configurato di svuotamento del riavvio per quel riavvio. I numeri senza unita sono millisecondi; sono accettate unita come `s`, `m` e `h`. `--wait 0` attende indefinitamente.
- `gateway restart --force` salta lo svuotamento del lavoro attivo e riavvia immediatamente. Usalo quando un operatore ha gia ispezionato i blocchi di task elencati e vuole ripristinare subito il gateway.
- I comandi di ciclo di vita accettano `--json` per gli script.
</Accordion>
<Accordion title="Auth e SecretRefs al momento dell'installazione">
- Quando l'autenticazione tramite token richiede un token e `gateway.auth.token` è gestito da SecretRef, `gateway install` verifica che il SecretRef sia risolvibile ma non salva il token risolto nei metadati dell'ambiente del servizio.
- Se l'autenticazione tramite token richiede un token e il SecretRef del token configurato non è risolto, l'installazione fallisce in modalità fail-closed invece di salvare testo in chiaro di fallback.
- Per l'autenticazione tramite password su `gateway run`, preferisci `OPENCLAW_GATEWAY_PASSWORD`, `--password-file` o un `gateway.auth.password` basato su SecretRef rispetto a `--password` inline.
- In modalità di autenticazione dedotta, `OPENCLAW_GATEWAY_PASSWORD` disponibile solo nella shell non allenta i requisiti del token di installazione; usa una configurazione persistente (`gateway.auth.password` o config `env`) quando installi un servizio gestito.
<Accordion title="Autenticazione e SecretRefs al momento dell'installazione">
- Quando l'autenticazione tramite token richiede un token e `gateway.auth.token` è gestito da SecretRef, `gateway install` convalida che il SecretRef sia risolvibile, ma non rende persistente il token risolto nei metadati dell'ambiente del servizio.
- Se l'autenticazione tramite token richiede un token e il SecretRef del token configurato non è risolto, l'installazione si blocca in modo sicuro invece di rendere persistente testo semplice di fallback.
- Per l'autenticazione tramite password su `gateway run`, preferisci `OPENCLAW_GATEWAY_PASSWORD`, `--password-file` o `gateway.auth.password` supportato da SecretRef rispetto a `--password` inline.
- Nella modalità di autenticazione dedotta, `OPENCLAW_GATEWAY_PASSWORD` solo shell non allenta i requisiti del token di installazione; usa una configurazione durevole (`gateway.auth.password` o `env` della configurazione) quando installi un servizio gestito.
- Se sono configurati sia `gateway.auth.token` sia `gateway.auth.password` e `gateway.auth.mode` non è impostato, l'installazione viene bloccata finché la modalità non viene impostata esplicitamente.
</Accordion>
</AccordionGroup>
## Scopri i Gateway (Bonjour)
## Individuare i gateway (Bonjour)
`gateway discover` cerca beacon Gateway (`_openclaw-gw._tcp`).
`gateway discover` esegue la scansione dei beacon Gateway (`_openclaw-gw._tcp`).
- DNS-SD multicast: `local.`
- DNS-SD unicast (Wide-Area Bonjour): scegli un dominio (esempio: `openclaw.internal.`) e configura split DNS + un server DNS; consulta [Bonjour](/it/gateway/bonjour).
- DNS-SD unicast (Bonjour Wide-Area): scegli un dominio (esempio: `openclaw.internal.`) e configura split DNS + un server DNS; vedi [Bonjour](/it/gateway/bonjour).
Solo i Gateway con discovery Bonjour abilitata (predefinito) pubblicizzano il beacon.
Solo i gateway con individuazione Bonjour abilitata (impostazione predefinita) pubblicizzano il beacon.
I record di discovery Wide-Area includono (TXT):
I record di individuazione Wide-Area includono (TXT):
- `role` (suggerimento sul ruolo del Gateway)
- `role` (suggerimento sul ruolo del gateway)
- `transport` (suggerimento sul trasporto, ad es. `gateway`)
- `gatewayPort` (porta WebSocket, di solito `18789`)
- `sshPort` (opzionale; i client usano come target SSH predefiniti `22` quando è assente)
- `tailnetDns` (hostname MagicDNS, quando disponibile)
- `sshPort` (facoltativo; i client usano per impostazione predefinita `22` come destinazione SSH quando è assente)
- `tailnetDns` (nome host MagicDNS, quando disponibile)
- `gatewayTls` / `gatewayTlsSha256` (TLS abilitato + fingerprint del certificato)
- `cliPath` (suggerimento di installazione remota scritto nella zona wide-area)
@ -539,7 +540,7 @@ openclaw gateway discover
Timeout per comando (browse/resolve).
</ParamField>
<ParamField path="--json" type="boolean">
Output leggibile da macchina (disattiva anche stile/spinner).
Output leggibile dalla macchina (disabilita anche stile/spinner).
</ParamField>
Esempi:
@ -550,9 +551,9 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl'
```
<Note>
- La CLI esamina `local.` più il dominio wide-area configurato quando ne è abilitato uno.
- `wsUrl` nell'output JSON è derivato dall'endpoint del servizio risolto, non da suggerimenti solo TXT come `lanHost` o `tailnetDns`.
- Su mDNS `local.`, `sshPort` e `cliPath` vengono trasmessi solo quando `discovery.mdns.mode` è `full`. DNS-SD wide-area scrive comunque `cliPath`; anche lì `sshPort` resta opzionale.
- La CLI esegue la scansione di `local.` più il dominio wide-area configurato quando ne è abilitato uno.
- `wsUrl` nell'output JSON deriva dall'endpoint del servizio risolto, non da suggerimenti solo TXT come `lanHost` o `tailnetDns`.
- Su mDNS `local.`, `sshPort` e `cliPath` vengono trasmessi solo quando `discovery.mdns.mode` è `full`. DNS-SD wide-area scrive comunque `cliPath`; anche lì `sshPort` resta facoltativo.
</Note>

68
docs/it/cli/hooks.md
View File

@ -1,21 +1,21 @@
---
read_when:
- Vuoi gestire gli hook degli agenti
- Vuoi controllare la disponibilità degli hook o abilitare gli hook dell'area di lavoro
summary: Riferimento CLI per `openclaw hooks` (agganci degli agenti)
title: Ganci
- Vuoi verificare la disponibilità degli hook o abilitare gli hook dell'area di lavoro
summary: Riferimento CLI per `openclaw hooks` (hook degli agenti)
title: Agganci
x-i18n:
generated_at: "2026-05-02T20:42:25Z"
generated_at: "2026-05-05T08:25:40Z"
model: gpt-5.5
provider: openai
source_hash: 3b02c176b4a310adba3fa1fde3758f6c8a19d454aeec58e919458b3f1a66c87d
source_hash: 8e860d4a20a09526e804fa1aff8c983a75396fcd1e6e24f742252fdf1812f6b7
source_path: cli/hooks.md
workflow: 16
---
# `openclaw hooks`
Gestisci gli hook degli agenti (automazioni guidate da eventi per comandi come `/new`, `/reset` e l'avvio del Gateway).
Gestisci gli hook degli agenti (automazioni guidate da eventi per comandi come `/new`, `/reset` e l’avvio del Gateway).
Eseguire `openclaw hooks` senza sottocomando equivale a `openclaw hooks list`.
@ -31,7 +31,7 @@ openclaw hooks list
```
Elenca tutti gli hook rilevati dalle directory workspace, gestite, extra e incluse.
L'avvio del Gateway non carica i gestori di hook interni finché non è configurato almeno un hook interno.
L’avvio del Gateway non carica i gestori interni degli hook finché non è configurato almeno un hook interno.
**Opzioni:**
@ -65,7 +65,7 @@ Mostra i requisiti mancanti per gli hook non idonei.
openclaw hooks list --json
```
Restituisce JSON strutturato per l'uso programmatico.
Restituisce JSON strutturato per l’uso programmatico.
## Ottenere informazioni sugli hook
@ -73,11 +73,11 @@ Restituisce JSON strutturato per l'uso programmatico.
openclaw hooks info <name>
```
Mostra informazioni dettagliate su uno specifico hook.
Mostra informazioni dettagliate su un hook specifico.
**Argomenti:**
- `<name>`: Nome dell'hook o chiave dell'hook (ad esempio `session-memory`)
- `<name>`: Nome dell’hook o chiave dell’hook (ad es. `session-memory`)
**Opzioni:**
@ -107,7 +107,7 @@ Requirements:
Config: ✓ workspace.dir
```
## Verificare l'idoneità degli hook
## Verificare l’idoneità degli hook
```bash
openclaw hooks check
@ -135,13 +135,13 @@ Not ready: 0
openclaw hooks enable <name>
```
Abilita uno specifico hook aggiungendolo alla tua configurazione (`~/.openclaw/openclaw.json` per impostazione predefinita).
Abilita un hook specifico aggiungendolo alla tua configurazione (`~/.openclaw/openclaw.json` per impostazione predefinita).
**Nota:** Gli hook del workspace sono disabilitati per impostazione predefinita finché non vengono abilitati qui o nella configurazione. Gli hook gestiti dai Plugin mostrano `plugin:<id>` in `openclaw hooks list` e non possono essere abilitati/disabilitati qui. Abilita/disabilita invece il Plugin.
**Nota:** Gli hook del workspace sono disabilitati per impostazione predefinita finché non vengono abilitati qui o nella configurazione. Gli hook gestiti dai plugin mostrano `plugin:<id>` in `openclaw hooks list` e non possono essere abilitati/disabilitati qui. Abilita/disabilita invece il plugin.
**Argomenti:**
- `<name>`: Nome dell'hook (ad esempio `session-memory`)
- `<name>`: Nome dell’hook (ad es. `session-memory`)
**Esempio:**
@ -157,15 +157,15 @@ openclaw hooks enable session-memory
**Cosa fa:**
- Verifica se l'hook esiste ed è idoneo
- Verifica se l’hook esiste ed è idoneo
- Aggiorna `hooks.internal.entries.<name>.enabled = true` nella tua configurazione
- Salva la configurazione su disco
Se l'hook proviene da `<workspace>/hooks/`, questo passaggio di opt-in è obbligatorio prima che il Gateway lo carichi.
Se l’hook proviene da `<workspace>/hooks/`, questo passaggio di consenso esplicito è necessario prima che il Gateway lo carichi.
**Dopo l'abilitazione:**
**Dopo l’abilitazione:**
- Riavvia il gateway in modo che gli hook vengano ricaricati (riavvio dell'app nella barra dei menu su macOS, oppure riavvia il processo gateway in sviluppo).
- Riavvia il gateway in modo che gli hook vengano ricaricati (riavvio dell’app nella barra dei menu su macOS, oppure riavvia il tuo processo gateway in sviluppo).
## Disabilitare un hook
@ -173,11 +173,11 @@ Se l'hook proviene da `<workspace>/hooks/`, questo passaggio di opt-in è obblig
openclaw hooks disable <name>
```
Disabilita uno specifico hook aggiornando la tua configurazione.
Disabilita un hook specifico aggiornando la tua configurazione.
**Argomenti:**
- `<name>`: Nome dell'hook (ad esempio `command-logger`)
- `<name>`: Nome dell’hook (ad es. `command-logger`)
**Esempio:**
@ -198,7 +198,7 @@ openclaw hooks disable command-logger
## Note
- `openclaw hooks list --json`, `info --json` e `check --json` scrivono JSON strutturato direttamente su stdout.
- Gli hook gestiti dai Plugin non possono essere abilitati o disabilitati qui; abilita o disabilita invece il Plugin proprietario.
- Gli hook gestiti dai plugin non possono essere abilitati o disabilitati qui; abilita o disabilita invece il plugin proprietario.
## Installare pacchetti di hook
@ -209,24 +209,24 @@ openclaw plugins install <package> --pin # pin version
openclaw plugins install <path> # local path
```
Installa pacchetti di hook tramite l'installer unificato dei Plugin.
Installa pacchetti di hook tramite il programma di installazione unificato dei plugin.
`openclaw hooks install` funziona ancora come alias di compatibilità, ma stampa un avviso di deprecazione e inoltra a `openclaw plugins install`.
Le specifiche npm sono **solo registry** (nome del pacchetto + **versione esatta** opzionale o **dist-tag**). Le specifiche Git/URL/file e gli intervalli semver vengono rifiutati. Le installazioni delle dipendenze vengono eseguite a livello di progetto con `--ignore-scripts` per sicurezza, anche quando la tua shell ha impostazioni globali di installazione npm.
Le specifiche npm sono **solo registro** (nome del pacchetto + **versione esatta** facoltativa o **dist-tag**). Le specifiche Git/URL/file e gli intervalli semver vengono rifiutati. Le installazioni delle dipendenze vengono eseguite a livello locale del progetto con `--ignore-scripts` per sicurezza, anche quando la shell ha impostazioni globali di installazione npm.
Le specifiche semplici e `@latest` restano sul canale stabile. Se npm risolve una di queste a una prerelease, OpenClaw si ferma e ti chiede di aderire esplicitamente con un tag prerelease come `@beta`/`@rc` o una versione prerelease esatta.
Le specifiche nude e `@latest` restano sul canale stabile. Se npm risolve una di esse a una prerelease, OpenClaw si ferma e chiede di aderire esplicitamente con un tag prerelease come `@beta`/`@rc` o una versione prerelease esatta.
**Cosa fa:**
- Copia il pacchetto di hook in `~/.openclaw/hooks/<id>`
- Abilita gli hook installati in `hooks.internal.entries.*`
- Registra l'installazione sotto `hooks.internal.installs`
- Registra l’installazione in `hooks.internal.installs`
**Opzioni:**
- `-l, --link`: Collega una directory locale invece di copiarla (la aggiunge a `hooks.internal.load.extraDirs`)
- `--pin`: Registra le installazioni npm come `name@version` risolto esatto in `hooks.internal.installs`
- `--pin`: Registra le installazioni npm come `name@version` risolti esatti in `hooks.internal.installs`
**Archivi supportati:** `.zip`, `.tgz`, `.tar.gz`, `.tar`
@ -246,7 +246,7 @@ openclaw plugins install @openclaw/my-hook-pack
openclaw plugins install -l ./my-hook-pack
```
I pacchetti di hook collegati vengono trattati come hook gestiti da una directory configurata dall'operatore, non come hook del workspace.
I pacchetti di hook collegati vengono trattati come hook gestiti da una directory configurata dall’operatore, non come hook del workspace.
## Aggiornare pacchetti di hook
@ -255,7 +255,7 @@ openclaw plugins update <id>
openclaw plugins update --all
```
Aggiorna i pacchetti di hook basati su npm tracciati tramite l'updater unificato dei Plugin.
Aggiorna i pacchetti di hook basati su npm tracciati tramite il programma di aggiornamento unificato dei plugin.
`openclaw hooks update` funziona ancora come alias di compatibilità, ma stampa un avviso di deprecazione e inoltra a `openclaw plugins update`.
@ -264,13 +264,13 @@ Aggiorna i pacchetti di hook basati su npm tracciati tramite l'updater unificato
- `--all`: Aggiorna tutti i pacchetti di hook tracciati
- `--dry-run`: Mostra cosa cambierebbe senza scrivere
Quando esiste un hash di integrità salvato e l'hash dell'artefatto recuperato cambia, OpenClaw stampa un avviso e chiede conferma prima di procedere. Usa `--yes` globale per bypassare le richieste di conferma nelle esecuzioni CI/non interattive.
Quando esiste un hash di integrità memorizzato e l’hash dell’artefatto recuperato cambia, OpenClaw stampa un avviso e chiede conferma prima di procedere. Usa `--yes` globale per bypassare i prompt nelle esecuzioni CI/non interattive.
## Hook inclusi
### session-memory
Salva il contesto della sessione in memoria quando esegui `/new` o `/reset`.
Salva il contesto della sessione in memoria quando emetti `/new` o `/reset`.
**Abilita:**
@ -278,13 +278,13 @@ Salva il contesto della sessione in memoria quando esegui `/new` o `/reset`.
openclaw hooks enable session-memory
```
**Output:** `~/.openclaw/workspace/memory/YYYY-MM-DD-slug.md`
**Output:** `~/.openclaw/workspace/memory/YYYY-MM-DD-HHMM.md` per impostazione predefinita. Imposta `hooks.internal.entries.session-memory.llmSlug: true` per slug di nomi file generati dal modello.
**Vedi:** [documentazione di session-memory](/it/automation/hooks#session-memory)
### bootstrap-extra-files
Inietta file bootstrap aggiuntivi (ad esempio `AGENTS.md` / `TOOLS.md` locali a un monorepo) durante `agent:bootstrap`.
Inietta file di bootstrap aggiuntivi (ad esempio `AGENTS.md` / `TOOLS.md` locali al monorepo) durante `agent:bootstrap`.
**Abilita:**
@ -306,7 +306,7 @@ openclaw hooks enable command-logger
**Output:** `~/.openclaw/logs/commands.log`
**Visualizzare i log:**
**Visualizza log:**
```bash
# Recent commands
@ -323,7 +323,7 @@ grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .
### boot-md
Esegue `BOOT.md` all'avvio del gateway (dopo l'avvio dei canali).
Esegue `BOOT.md` all’avvio del gateway (dopo l’avvio dei canali).
**Eventi**: `gateway:startup`

57
docs/it/cli/sessions.md
View File

@ -1,13 +1,13 @@
---
read_when:
- Vuoi elencare le sessioni salvate e visualizzare l'attività recente
summary: Riferimento CLI per `openclaw sessions` (elenco delle sessioni memorizzate + utilizzo)
- Vuoi elencare le sessioni memorizzate e visualizzare l'attività recente
summary: Riferimento CLI per `openclaw sessions` (elenca le sessioni memorizzate + utilizzo)
title: Sessioni
x-i18n:
generated_at: "2026-05-05T01:44:12Z"
generated_at: "2026-05-05T08:25:32Z"
model: gpt-5.5
provider: openai
source_hash: 6eb484ab1fa7686cf42dd00e640c4ae8616c4ea1c29873ea72694d72b9c680e7
source_hash: a204189952bc82788eb724c0a6b6db93c7d6795ad69bb6d498e8575236c3272e
source_path: cli/sessions.md
workflow: 16
---
@ -16,9 +16,9 @@ x-i18n:
Elenca le sessioni di conversazione archiviate.
Gli elenchi di sessioni non sono controlli di disponibilità di canali/provider. Mostrano le righe di conversazione persistenti dagli store delle sessioni. Un canale Discord, Slack, Telegram o altro canale inattivo può riconnettersi correttamente senza creare una nuova riga di sessione finché non viene elaborato un messaggio. Usa `openclaw channels status --probe`, `openclaw status --deep` o `openclaw health --verbose` quando ti serve la connettività live del canale.
Gli elenchi delle sessioni non sono controlli di disponibilità del canale/provider. Mostrano righe di conversazione persistite dagli archivi delle sessioni. Un Discord, Slack, Telegram o altro canale inattivo può riconnettersi correttamente senza creare una nuova riga di sessione finché non viene elaborato un messaggio. Usa `openclaw channels status --probe`, `openclaw status --deep` o `openclaw health --verbose` quando hai bisogno della connettività live del canale.
Le risposte di `openclaw sessions` e Gateway `sessions.list` sono limitate per impostazione predefinita, così gli store grandi e longevi non possono monopolizzare il processo CLI o l’event loop del Gateway. La CLI restituisce per impostazione predefinita le 100 sessioni più recenti; passa `--limit <n>` per una finestra più piccola/grande o `--limit all` quando ti serve intenzionalmente lo store completo. Le risposte JSON includono `totalCount`, `limitApplied` e `hasMore` quando i chiamanti devono mostrare che esistono altre righe.
Le risposte di `openclaw sessions` e Gateway `sessions.list` sono limitate per impostazione predefinita, così archivi grandi e di lunga durata non possono monopolizzare il processo CLI o il ciclo degli eventi del Gateway. La CLI restituisce per impostazione predefinita le 100 sessioni più recenti; passa `--limit <n>` per una finestra più piccola/grande oppure `--limit all` quando hai intenzionalmente bisogno dell'intero archivio. Le risposte JSON includono `totalCount`, `limitApplied` e `hasMore` quando i chiamanti devono mostrare che esistono altre righe.
```bash
openclaw sessions
@ -30,25 +30,25 @@ openclaw sessions --verbose
openclaw sessions --json
```
Selezione dell’ambito:
Selezione dell'ambito:
- predefinito: store dell’agente predefinito configurato
- `--verbose`: logging dettagliato
- `--agent <id>`: uno store dell’agente configurato
- `--all-agents`: aggrega tutti gli store degli agenti configurati
- `--store <path>`: percorso esplicito dello store (non può essere combinato con `--agent` o `--all-agents`)
- `--limit <n|all>`: numero massimo di righe da emettere (predefinito `100`; `all` ripristina l’output completo)
- predefinito: archivio dell'agente predefinito configurato
- `--verbose`: log dettagliati
- `--agent <id>`: un archivio di agente configurato
- `--all-agents`: aggrega tutti gli archivi degli agenti configurati
- `--store <path>`: percorso esplicito dell'archivio (non può essere combinato con `--agent` o `--all-agents`)
- `--limit <n|all>`: numero massimo di righe da produrre (predefinito `100`; `all` ripristina l'output completo)
Esporta un bundle di traiettoria per una sessione archiviata:
Esporta un pacchetto di traiettoria per una sessione archiviata:
```bash
openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace .
openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json
```
Questo è il percorso di comando usato dal comando slash `/export-trajectory` dopo che il proprietario approva la richiesta di esecuzione. La directory di output viene sempre risolta dentro `.openclaw/trajectory-exports/` nello spazio di lavoro selezionato.
Questo è il percorso di comando usato dal comando slash `/export-trajectory` dopo che il proprietario approva la richiesta di esecuzione. La directory di output viene sempre risolta dentro `.openclaw/trajectory-exports/` nell'area di lavoro selezionata.
`openclaw sessions --all-agents` legge gli store degli agenti configurati. La scoperta delle sessioni Gateway e ACP è più ampia: include anche gli store presenti solo su disco trovati sotto la radice predefinita `agents/` o una radice `session.store` con modello. Gli store scoperti devono risolversi in file `sessions.json` regolari dentro la radice dell’agente; i symlink e i percorsi esterni alla radice vengono ignorati.
`openclaw sessions --all-agents` legge gli archivi degli agenti configurati. Il rilevamento delle sessioni Gateway e ACP è più ampio: include anche archivi presenti solo su disco trovati sotto la radice predefinita `agents/` o una radice `session.store` basata su template. Questi archivi rilevati devono risolversi in file `sessions.json` regolari dentro la radice dell'agente; i symlink e i percorsi fuori dalla radice vengono ignorati.
Esempi JSON:
@ -74,9 +74,9 @@ Esempi JSON:
}
```
## Manutenzione della pulizia
## Manutenzione di pulizia
Esegui la manutenzione ora (invece di attendere il prossimo ciclo di scrittura):
Esegui subito la manutenzione (invece di attendere il prossimo ciclo di scrittura):
```bash
openclaw sessions cleanup --dry-run
@ -89,19 +89,20 @@ openclaw sessions cleanup --json
`openclaw sessions cleanup` usa le impostazioni `session.maintenance` dalla configurazione:
- Nota sull’ambito: `openclaw sessions cleanup` mantiene store delle sessioni, trascrizioni e sidecar di traiettoria. Non elimina i log delle esecuzioni Cron (`cron/runs/<jobId>.jsonl`), che sono gestiti da `cron.runLog.maxBytes` e `cron.runLog.keepLines` in [Configurazione Cron](/it/automation/cron-jobs#configuration) e spiegati in [Manutenzione Cron](/it/automation/cron-jobs#maintenance).
- Nota sull'ambito: `openclaw sessions cleanup` mantiene archivi delle sessioni, trascrizioni e sidecar delle traiettorie. Non elimina i log delle esecuzioni cron (`cron/runs/<jobId>.jsonl`), che sono gestiti da `cron.runLog.maxBytes` e `cron.runLog.keepLines` in [Configurazione Cron](/it/automation/cron-jobs#configuration) e spiegati in [Manutenzione Cron](/it/automation/cron-jobs#maintenance).
- La pulizia elimina anche trascrizioni primarie non referenziate, checkpoint di Compaction e sidecar delle traiettorie più vecchi di `session.maintenance.pruneAfter`; i file ancora referenziati da `sessions.json` vengono preservati.
- `--dry-run`: visualizza in anteprima quante voci verrebbero eliminate/limitate senza scrivere.
- `--dry-run`: mostra in anteprima quante voci verrebbero eliminate/limitate senza scrivere.
- In modalità testo, dry-run stampa una tabella di azioni per sessione (`Action`, `Key`, `Age`, `Model`, `Flags`) così puoi vedere cosa verrebbe mantenuto rispetto a cosa verrebbe rimosso.
- `--enforce`: applica la manutenzione anche quando `session.maintenance.mode` è `warn`.
- `--fix-missing`: rimuove le voci i cui file di trascrizione mancano, anche se normalmente non sarebbero ancora escluse per età/conteggio.
- `--active-key <key>`: protegge una chiave attiva specifica dall’espulsione per budget su disco. Anche i puntatori durevoli a conversazioni esterne, come le sessioni di gruppo e le sessioni di chat con ambito thread, vengono mantenuti dalla manutenzione per età/conteggio/budget su disco.
- `--agent <id>`: esegue la pulizia per uno store dell’agente configurato.
- `--all-agents`: esegue la pulizia per tutti gli store degli agenti configurati.
- `--store <path>`: esegue l’operazione su uno specifico file `sessions.json`.
- `--json`: stampa un riepilogo JSON. Con `--all-agents`, l’output include un riepilogo per ogni store.
- `--fix-missing`: rimuove le voci i cui file di trascrizione mancano, anche se normalmente non uscirebbero ancora per età/conteggio.
- `--active-key <key>`: protegge una chiave attiva specifica dallo sfratto per budget del disco. Anche i puntatori di conversazione esterni durevoli, come le sessioni di gruppo e le sessioni chat con ambito thread, vengono mantenuti dalla manutenzione per età/conteggio/budget del disco.
- `--agent <id>`: esegue la pulizia per un archivio di agente configurato.
- `--all-agents`: esegue la pulizia per tutti gli archivi degli agenti configurati.
- `--store <path>`: esegue l'operazione su un file `sessions.json` specifico.
- `--json`: stampa un riepilogo JSON. Con `--all-agents`, l'output include un riepilogo per ogni archivio.
Quando un Gateway è raggiungibile, la pulizia non dry-run degli store degli agenti configurati viene inviata tramite il Gateway, così condivide lo stesso writer dello store delle sessioni del traffico runtime. Usa `--store <path>` per la riparazione offline esplicita di un file store.
Quando un Gateway è raggiungibile, la pulizia non dry-run per gli archivi degli agenti configurati viene inviata tramite il Gateway, così condivide lo stesso writer dell'archivio delle sessioni del traffico runtime. Usa `--store <path>` per la riparazione offline esplicita di un file di archivio.
`openclaw sessions cleanup --all-agents --dry-run --json`:
@ -133,7 +134,7 @@ Quando un Gateway è raggiungibile, la pulizia non dry-run degli store degli age
Correlati:
- Configurazione delle sessioni: [Riferimento di configurazione](/it/gateway/config-agents#session)
- Configurazione della sessione: [Riferimento configurazione](/it/gateway/config-agents#session)
## Correlati

523
docs/it/concepts/mantis.md
View File

@ -1,81 +1,77 @@
---
read_when:
- Creazione o esecuzione della QA visiva live per i bug di OpenClaw
- Aggiunta della verifica prima e dopo per una richiesta di pull
- Aggiunta di scenari per Discord, Slack, WhatsApp o altri trasporti in tempo reale
- Risoluzione dei problemi delle esecuzioni QA che richiedono schermate, automazione del browser o accesso VNC
summary: Mantis è il sistema di verifica visiva integrale per riprodurre i bug di OpenClaw sui trasporti attivi, acquisire prove prima e dopo e allegare artefatti alle PR.
- Creazione o esecuzione della garanzia qualità visiva in tempo reale per i bug di OpenClaw
- Aggiunta della verifica prima e dopo per una pull request
- Aggiunta di scenari di trasporto in tempo reale per Discord, Slack, WhatsApp o altri
- Risoluzione dei problemi delle esecuzioni QA che richiedono screenshot, automazione del browser o accesso VNC
summary: Mantis è il sistema visivo di verifica end-to-end per riprodurre bug di OpenClaw su trasporti live, acquisire evidenze prima e dopo e allegare artefatti alle PR.
title: Mantide
x-i18n:
generated_at: "2026-05-05T06:16:29Z"
generated_at: "2026-05-05T08:26:13Z"
model: gpt-5.5
provider: openai
source_hash: 26a9671135e38bf82d3627364f691f8d91cc8649ffc2e5fa782ebef474a44fa1
source_hash: 6b287e2832e3e49de6b3cb65aeb1d381a36fc30ce9c94dc5b6b4d7e928c2706c
source_path: concepts/mantis.md
workflow: 16
---
Mantis è il sistema di verifica end-to-end di OpenClaw per bug che richiedono un
runtime reale, un trasporto reale e prove visibili. Esegue uno scenario contro un
ref noto come non funzionante, acquisisce prove, esegue lo stesso scenario contro
un ref candidato e pubblica il confronto come artefatti che un manutentore può
ispezionare da una PR o da un comando locale.
runtime reale, un trasporto reale e prove visibili. Esegue uno scenario su un ref
notoriamente difettoso, acquisisce prove, esegue lo stesso scenario su un ref
candidato e pubblica il confronto come artefatti che un maintainer può ispezionare
da una PR o da un comando locale.
Mantis inizia con Discord perché Discord ci offre una prima lane ad alto valore:
autenticazione reale del bot, canali guild reali, reazioni, thread, comandi
nativi e una UI browser in cui gli esseri umani possono confermare visivamente
ciò che il trasporto ha mostrato.
Mantis parte da Discord perché Discord ci offre una prima corsia ad alto valore:
autenticazione bot reale, canali di guild reali, reazioni, thread, comandi nativi e una
UI del browser in cui gli esseri umani possono confermare visivamente ciò che il
trasporto ha mostrato.
## Obiettivi
- Riprodurre un bug da una issue GitHub o da una PR con la stessa forma di
trasporto vista dagli utenti.
- Acquisire un artefatto **prima** sul ref di baseline prima di applicare la
correzione.
- Acquisire un artefatto **dopo** sul ref candidato dopo aver applicato la
correzione.
- Usare un oracolo deterministico quando possibile, come una lettura di reazione
tramite Discord REST o un controllo della trascrizione del canale.
- Riprodurre un bug da una issue o PR di GitHub con la stessa forma di trasporto
che vedono gli utenti.
- Acquisire un artefatto **prima** sul ref di baseline prima di applicare la correzione.
- Acquisire un artefatto **dopo** sul ref candidato dopo aver applicato la correzione.
- Usare un oracolo deterministico ogni volta che è possibile, come una lettura di
una reazione tramite REST di Discord o un controllo della trascrizione del canale.
- Acquisire screenshot quando il bug ha una superficie UI visibile.
- Eseguire localmente da una CLI controllata da agent e da remoto da GitHub.
- Preservare abbastanza stato macchina per il recupero tramite VNC quando login,
automazione browser o autenticazione del provider si bloccano.
- Pubblicare uno stato conciso su un canale Discord dell'operatore quando
l'esecuzione è bloccata, richiede aiuto manuale tramite VNC o termina.
- Conservare abbastanza stato macchina per il recupero tramite VNC quando accesso,
automazione del browser o autenticazione del provider si bloccano.
- Pubblicare uno stato conciso su un canale Discord per operatori quando l'esecuzione
è bloccata, richiede assistenza VNC manuale o termina.
## Non Obiettivi
## Non obiettivi
- Mantis non sostituisce gli unit test. Un'esecuzione Mantis dovrebbe di solito
diventare un test di regressione più piccolo dopo che la correzione è stata
compresa.
- Mantis non sostituisce gli unit test. Un'esecuzione Mantis dovrebbe in genere
diventare un test di regressione più piccolo dopo che la correzione è stata compresa.
- Mantis non è il normale gate CI veloce. È più lento, usa credenziali live ed è
riservato a bug in cui l'ambiente live conta.
- Mantis non dovrebbe richiedere un essere umano per il funzionamento normale.
Il VNC manuale è un percorso di recupero, non il percorso principale.
- Mantis non memorizza segreti grezzi in artefatti, log, screenshot, report
Markdown o commenti PR.
riservato ai bug in cui l'ambiente live è importante.
- Mantis non dovrebbe richiedere un essere umano per il funzionamento normale. Il VNC
manuale è un percorso di recupero, non il percorso previsto.
- Mantis non archivia segreti grezzi in artefatti, log, screenshot, report Markdown
o commenti PR.
## Proprietà
Mantis vive nello stack QA di OpenClaw.
- OpenClaw possiede il runtime degli scenari, gli adattatori di trasporto, lo
schema delle prove e la CLI locale sotto `pnpm openclaw qa mantis`.
- QA Lab possiede i componenti dell'harness di trasporto live, gli helper di
cattura browser e gli autori di artefatti.
- Crabbox possiede macchine Linux pre-riscaldate quando serve una VM remota.
- GitHub Actions possiede l'entrypoint del workflow remoto e la conservazione
- OpenClaw possiede il runtime degli scenari, gli adattatori di trasporto, lo schema
delle prove e la CLI locale sotto `pnpm openclaw qa mantis`.
- QA Lab possiede le parti dell'harness di trasporto live, gli helper di acquisizione
del browser e gli scrittori di artefatti.
- Crabbox possiede le macchine Linux riscaldate quando serve una VM remota.
- GitHub Actions possiede il punto di ingresso del workflow remoto e la conservazione
degli artefatti.
- ClawSweeper possiede il routing dei commenti GitHub: parsing dei comandi dei
manutentori, dispatch del workflow e pubblicazione del commento PR finale.
- Gli agent OpenClaw guidano Mantis tramite Codex quando uno scenario richiede
maintainer, dispatch del workflow e pubblicazione del commento PR finale.
- Gli agent OpenClaw pilotano Mantis tramite Codex quando uno scenario richiede
configurazione agentica, debug o segnalazione di stato bloccato.
Questo confine mantiene la conoscenza del trasporto in OpenClaw, la
pianificazione delle macchine in Crabbox e il collante del workflow dei
manutentori in ClawSweeper.
Questo confine mantiene la conoscenza del trasporto in OpenClaw, la pianificazione
delle macchine in Crabbox e il collante del workflow dei maintainer in ClawSweeper.
## Forma Del Comando
## Forma del comando
Il primo comando locale verifica bot Discord, guild, canale, invio messaggio,
invio reazione e percorso degli artefatti:
@ -96,11 +92,11 @@ pnpm openclaw qa mantis run \
--output-dir .artifacts/qa-e2e/mantis/local-discord-status-reactions
```
Il runner crea worktree baseline e candidato detached sotto la directory di
output, installa le dipendenze, compila ogni ref, esegue lo scenario con
`--allow-failures`, quindi scrive `baseline/`, `candidate/`, `comparison.json` e
`mantis-report.md`. Per il primo scenario Discord, una verifica riuscita
significa che lo stato baseline è `fail` e lo stato candidato è `pass`.
Il runner crea worktree baseline e candidato staccati sotto la directory di output,
installa le dipendenze, compila ogni ref, esegue lo scenario con `--allow-failures`,
quindi scrive `baseline/`, `candidate/`, `comparison.json` e `mantis-report.md`.
Per il primo scenario Discord, una verifica riuscita significa che lo stato baseline
è `fail` e lo stato candidato è `pass`.
La prima primitiva VM/browser è lo smoke desktop:
@ -109,21 +105,21 @@ pnpm openclaw qa mantis desktop-browser-smoke \
--output-dir .artifacts/qa-e2e/mantis/desktop-browser
```
Noleggia o riusa una macchina desktop Crabbox, avvia un browser visibile dentro
la sessione VNC, acquisisce il desktop, recupera gli artefatti nella directory di
output locale e scrive il comando di riconnessione nel report. Il comando usa per
impostazione predefinita il provider Hetzner perché è il primo provider con
copertura desktop/VNC funzionante nella lane Mantis. Sovrascrivilo con
Prende in lease o riusa una macchina desktop Crabbox, avvia un browser visibile
dentro la sessione VNC, acquisisce il desktop, recupera gli artefatti nella
directory di output locale e scrive il comando di riconnessione nel report. Il
comando usa come predefinito il provider Hetzner perché è il primo provider con
copertura desktop/VNC funzionante nella corsia Mantis. Sovrascrivilo con
`--provider`, `--crabbox-bin` o `OPENCLAW_MANTIS_CRABBOX_PROVIDER` quando esegui
contro un'altra flotta Crabbox.
Flag utili per lo smoke desktop:
- `--lease-id <cbx_...>` o `OPENCLAW_MANTIS_CRABBOX_LEASE_ID` riusa un desktop pre-riscaldato.
- `--lease-id <cbx_...>` o `OPENCLAW_MANTIS_CRABBOX_LEASE_ID` riusa un desktop riscaldato.
- `--browser-url <url>` cambia la pagina aperta nel browser visibile.
- `--html-file <path>` renderizza un artefatto HTML locale al repo nel browser visibile. Mantis lo usa per acquisire la timeline generata delle reazioni di stato Discord tramite un vero desktop Crabbox.
- `--keep-lease` o `OPENCLAW_MANTIS_KEEP_VM=1` mantiene aperto per ispezione VNC un lease appena creato che passa. Le esecuzioni fallite mantengono il lease per impostazione predefinita quando ne è stato creato uno, così un operatore può riconnettersi.
- `--class`, `--idle-timeout` e `--ttl` regolano dimensione della macchina e durata del lease.
- `--html-file <path>` renderizza un artefatto HTML locale al repo nel browser visibile. Mantis lo usa per acquisire la timeline generata delle reazioni di stato Discord tramite un desktop Crabbox reale.
- `--keep-lease` o `OPENCLAW_MANTIS_KEEP_VM=1` mantiene aperto un lease appena creato e riuscito per l'ispezione VNC. Le esecuzioni non riuscite mantengono il lease per impostazione predefinita quando ne è stato creato uno, così un operatore può riconnettersi.
- `--class`, `--idle-timeout` e `--ttl` regolano dimensione macchina e durata del lease.
La prima primitiva completa di trasporto desktop è lo smoke desktop Slack:
@ -135,20 +131,19 @@ pnpm openclaw qa mantis slack-desktop-smoke \
--keep-lease
```
Noleggia o riusa una macchina desktop Crabbox, sincronizza il checkout corrente
nella VM, esegue `pnpm openclaw qa slack` dentro quella VM, apre Slack Web nel
browser VNC, acquisisce il desktop visibile e copia sia gli artefatti Slack QA
Prende in lease o riusa una macchina desktop Crabbox, sincronizza il checkout
corrente nella VM, esegue `pnpm openclaw qa slack` dentro quella VM, apre Slack Web
nel browser VNC, acquisisce il desktop visibile e copia sia gli artefatti QA Slack
sia lo screenshot VNC nella directory di output locale. Questa è la prima forma
Mantis in cui il Gateway OpenClaw SUT e il browser vivono entrambi nella stessa
VM desktop Linux.
Con `--gateway-setup`, il comando prepara una home OpenClaw persistente e
monouso in `$HOME/.openclaw-mantis/slack-openclaw`, applica patch alla
configurazione Slack Socket Mode per il canale selezionato, avvia
`openclaw gateway run` sulla porta `38973` e mantiene Chrome in esecuzione nella
sessione VNC. Questa è la modalità "lasciami un desktop Linux con Slack e un claw
in esecuzione"; la lane Slack QA bot-to-bot rimane l'impostazione predefinita
quando `--gateway-setup` è omesso.
Con `--gateway-setup`, il comando prepara una home OpenClaw usa e getta persistente
in `$HOME/.openclaw-mantis/slack-openclaw`, applica patch alla configurazione Slack
Socket Mode per il canale selezionato, avvia `openclaw gateway run` sulla porta
`38973` e mantiene Chrome in esecuzione nella sessione VNC. Questa è la modalità
"lasciami un desktop Linux con Slack e un claw in esecuzione"; la corsia QA Slack
bot-to-bot resta quella predefinita quando `--gateway-setup` è omesso.
Input richiesti per `--credential-source env`:
@ -156,84 +151,151 @@ Input richiesti per `--credential-source env`:
- `OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN`
- `OPENCLAW_QA_SLACK_SUT_BOT_TOKEN`
- `OPENCLAW_QA_SLACK_SUT_APP_TOKEN`
- `OPENCLAW_LIVE_OPENAI_KEY` per la lane del modello remoto. Se localmente è
impostato solo `OPENAI_API_KEY`, Mantis lo mappa a `OPENCLAW_LIVE_OPENAI_KEY`
prima di invocare Crabbox, così il forwarding env `OPENCLAW_*` di Crabbox può
portarlo nella VM.
- `OPENCLAW_LIVE_OPENAI_KEY` per la corsia modello remota. Se localmente è impostato solo
`OPENAI_API_KEY`, Mantis lo mappa a `OPENCLAW_LIVE_OPENAI_KEY`
prima di invocare Crabbox, così l'inoltro delle variabili d'ambiente `OPENCLAW_*`
di Crabbox può portarlo nella VM.
Flag utili per il desktop Slack:
Flag utili per Slack desktop:
- `--lease-id <cbx_...>` riesegue contro una macchina in cui un operatore ha già effettuato l'accesso a Slack Web tramite VNC.
- `--gateway-setup` avvia un Gateway OpenClaw Slack persistente nella VM invece di eseguire solo la lane QA bot-to-bot.
- `--slack-url <url>` apre un URL Slack Web specifico. Senza questo flag, Mantis deriva `https://app.slack.com/client/<team>/<channel>` da Slack `auth.test` quando il token bot SUT è disponibile.
- `--gateway-setup` avvia un Gateway Slack OpenClaw persistente nella VM invece di eseguire solo la corsia QA bot-to-bot.
- `--slack-url <url>` apre un URL Slack Web specifico. Senza questo, Mantis deriva `https://app.slack.com/client/<team>/<channel>` da Slack `auth.test` quando il token del bot SUT è disponibile.
- `--slack-channel-id <id>` controlla l'allowlist dei canali Slack usata dalla configurazione del Gateway.
- `OPENCLAW_MANTIS_SLACK_BROWSER_PROFILE_DIR` controlla il profilo Chrome persistente dentro la VM. Il valore predefinito è `$HOME/.config/openclaw-mantis/slack-chrome-profile`, quindi un login manuale a Slack Web sopravvive alle riesecuzioni sullo stesso lease.
- `--credential-source convex --credential-role ci` usa il pool di credenziali condiviso invece dei token env Slack diretti.
- `--provider-mode`, `--model`, `--alt-model` e `--fast` vengono passati alla lane live Slack.
- `OPENCLAW_MANTIS_SLACK_BROWSER_PROFILE_DIR` controlla il profilo Chrome persistente dentro la VM. Il valore predefinito è `$HOME/.config/openclaw-mantis/slack-chrome-profile`, quindi un accesso manuale a Slack Web sopravvive alle riesecuzioni sullo stesso lease.
- `--credential-source convex --credential-role ci` usa il pool di credenziali condiviso invece dei token Slack env diretti.
- `--provider-mode`, `--model`, `--alt-model` e `--fast` vengono passati alla corsia live Slack.
Il workflow smoke GitHub è `Mantis Discord Smoke`. Il workflow GitHub prima e
dopo per il primo scenario reale è `Mantis Discord Status Reactions`. Accetta:
Il workflow smoke GitHub è `Mantis Discord Smoke`. Il workflow GitHub prima e dopo
per il primo scenario reale è `Mantis Discord Status Reactions`. Accetta:
- `baseline_ref`: il ref che ci si aspetta riproduca il comportamento solo in coda.
- `candidate_ref`: il ref che ci si aspetta mostri `queued -> thinking -> done`.
- `baseline_ref`: il ref da cui ci si aspetta di riprodurre il comportamento solo queued.
- `candidate_ref`: il ref da cui ci si aspetta di mostrare `queued -> thinking -> done`.
Esegue il checkout del ref dell'harness del workflow, compila worktree baseline e
candidato separati, esegue `discord-status-reactions-tool-only` contro ciascun
worktree e carica `baseline/`, `candidate/`, `comparison.json` e
`mantis-report.md` come artefatti Actions. Renderizza anche l'HTML della timeline
di ogni lane in un browser desktop Crabbox e pubblica quegli screenshot VNC
accanto ai PNG deterministici della timeline nel commento PR. Lo stesso commento
PR collega alle registrazioni MP4 desktop acquisite durante il render del browser
VNC, mentre gli screenshot restano inline per una revisione rapida. Il workflow
compila la CLI Crabbox da `openclaw/crabbox` main così può usare i flag
desktop/browser lease correnti prima che venga tagliata la prossima release del
binario Crabbox.
candidato separati, esegue `discord-status-reactions-tool-only` contro ogni worktree
e carica `baseline/`, `candidate/`, `comparison.json` e `mantis-report.md` come
artefatti Actions. Renderizza anche l'HTML della timeline di ogni corsia in un
browser desktop Crabbox e pubblica quegli screenshot VNC accanto ai PNG deterministici
delle timeline nel commento PR. Lo stesso commento PR incorpora anteprime GIF leggere
con movimento ridotto generate da `crabbox media preview`, collega i clip MP4
corrispondenti con movimento ridotto e mantiene i file MP4 desktop completi per
un'ispezione approfondita. Gli screenshot restano inline per una revisione rapida.
Il workflow compila la CLI Crabbox da
`openclaw/crabbox` main così può usare i flag correnti di lease desktop/browser
prima del prossimo rilascio del binario Crabbox.
Puoi anche attivare l'esecuzione delle reazioni di stato direttamente da un
commento PR:
`Mantis Scenario` è il punto di ingresso manuale generico. Prende uno `scenario_id`,
un `candidate_ref`, un `baseline_ref` facoltativo e un `pr_number` facoltativo,
quindi avvia il workflow posseduto dallo scenario. Il wrapper è intenzionalmente
sottile: i workflow degli scenari possiedono ancora configurazione del trasporto,
credenziali, classe VM, oracolo atteso e manifest degli artefatti.
`Mantis Slack Desktop Smoke` è il primo workflow VM Slack. Esegue il checkout del
ref candidato attendibile in un worktree separato, prende in lease un desktop Linux
Crabbox, esegue `pnpm openclaw qa mantis slack-desktop-smoke --gateway-setup` contro
quel candidato, apre Slack Web nel browser VNC, registra il desktop, genera
un'anteprima con movimento ridotto con `crabbox media preview`, carica l'intera
directory degli artefatti e, facoltativamente, pubblica il commento con prove inline
sulla PR di destinazione. Usa questa corsia quando vuoi "un desktop Linux con Slack
e un claw in esecuzione" invece di sola trascrizione Slack bot-to-bot.
Ogni scenario che pubblica su PR scrive `mantis-evidence.json` accanto al proprio
report. Questo schema è il passaggio di consegne tra il codice dello scenario e i
commenti GitHub:
```json
{
"schemaVersion": 1,
"id": "discord-status-reactions",
"title": "Mantis Discord Status Reactions QA",
"summary": "Human-readable top summary for the PR comment.",
"scenario": "discord-status-reactions-tool-only",
"comparison": {
"baseline": { "sha": "...", "status": "fail", "expected": "queued-only" },
"candidate": { "sha": "...", "status": "pass", "expected": "queued -> thinking -> done" },
"pass": true
},
"artifacts": [
{
"kind": "timeline",
"lane": "baseline",
"label": "Baseline queued-only",
"path": "baseline/timeline.png",
"targetPath": "baseline.png",
"alt": "Baseline Discord timeline",
"width": 420
}
]
}
```
I valori `path` degli artefatti sono relativi alla directory del manifest. I valori
`targetPath` sono percorsi relativi sotto la directory di pubblicazione del branch
`qa-artifacts`. Il publisher rifiuta il path traversal e salta le voci marcate
`"required": false` quando anteprime o video facoltativi non sono disponibili.
Tipi di artefatto supportati:
- `timeline`: screenshot deterministico dello scenario, di solito prima/dopo.
- `desktopScreenshot`: screenshot del desktop VNC/browser.
- `motionPreview`: GIF animata inline generata dalla registrazione del desktop.
- `motionClip`: MP4 con movimento ridotto che rimuove introduzione e coda statiche.
- `fullVideo`: registrazione MP4 completa per un'ispezione approfondita.
- `metadata`: sidecar JSON/log.
- `report`: report Markdown.
Il publisher riutilizzabile è `scripts/mantis/publish-pr-evidence.mjs`. I workflow
lo chiamano con manifest, PR di destinazione, root di destinazione `qa-artifacts`,
marker del commento, URL dell'artefatto Actions, URL dell'esecuzione e origine
della richiesta. Copia gli artefatti dichiarati nel branch `qa-artifacts`, costruisce
un commento PR con il riepilogo in primo piano con immagini/anteprime inline e
video collegati, quindi aggiorna il commento marker esistente o ne crea uno.
Puoi anche attivare direttamente l'esecuzione status-reactions da un commento PR:
```text
@Mantis discord status reactions
```
Il trigger da commento è intenzionalmente ristretto. Viene eseguito solo su
commenti di pull request da utenti con accesso write, maintain o admin, e
riconosce solo richieste di reazioni di stato Discord. Per impostazione
predefinita usa il ref baseline noto come non funzionante e lo SHA head della PR
corrente come candidato. I manutentori possono sovrascrivere entrambi i ref:
Il trigger da commento è intenzionalmente stretto. Viene eseguito solo su commenti
di pull request da utenti con accesso write, maintain o admin e riconosce solo le
richieste di reazioni di stato Discord. Per impostazione predefinita usa il ref
baseline notoriamente difettoso e lo SHA head della PR corrente come candidato. I
maintainer possono sovrascrivere uno dei due ref:
```text
@Mantis discord status reactions baseline=origin/main candidate=HEAD
```
Esempi di comandi ClawSweeper:
Esempi di comando ClawSweeper:
```text
@clawsweeper mantis discord discord-status-reactions-tool-only
@clawsweeper verify e2e discord
```
Il primo comando è esplicito e focalizzato sullo scenario. Il secondo potrà in
seguito mappare una PR o una issue agli scenari Mantis consigliati da label, file
modificati e risultati della review ClawSweeper.
Il primo comando è esplicito e focalizzato sullo scenario. Il secondo può in seguito mappare una PR
o un problema a scenari Mantis consigliati da etichette, file modificati e
risultati della revisione di ClawSweeper.
## Ciclo Di Esecuzione
## Ciclo di esecuzione
1. Acquisire le credenziali.
2. Allocare o riusare una VM.
3. Preparare il profilo desktop/browser quando lo scenario richiede prove UI.
4. Preparare un checkout pulito per il ref baseline.
5. Installare le dipendenze e compilare solo ciò che serve allo scenario.
6. Avviare un Gateway OpenClaw figlio con una directory di stato isolata.
7. Configurare trasporto live, provider, modello e profilo browser.
8. Eseguire lo scenario e acquisire prove baseline.
9. Arrestare il Gateway e preservare i log.
2. Allocare o riutilizzare una VM.
3. Preparare il profilo desktop/browser quando lo scenario richiede evidenza UI.
4. Preparare un checkout pulito per il ref di baseline.
5. Installare le dipendenze e compilare solo ciò che lo scenario richiede.
6. Avviare un OpenClaw Gateway figlio con una directory di stato isolata.
7. Configurare il trasporto live, il provider, il modello e il profilo browser.
8. Eseguire lo scenario e acquisire l'evidenza di baseline.
9. Arrestare il Gateway e conservare i log.
10. Preparare il ref candidato nella stessa VM.
11. Eseguire lo stesso scenario e acquisire prove candidate.
12. Confrontare i risultati dell'oracolo e le prove visive.
13. Scrivere Markdown, JSON, log, screenshot e artefatti trace opzionali.
14. Caricare artefatti GitHub Actions.
15. Pubblicare un messaggio di stato PR o Discord conciso.
11. Eseguire lo stesso scenario e acquisire l'evidenza del candidato.
12. Confrontare i risultati dell'oracolo e l'evidenza visiva.
13. Scrivere Markdown, JSON, log, screenshot e artefatti di trace opzionali.
14. Caricare gli artefatti di GitHub Actions.
15. Pubblicare un messaggio di stato conciso sulla PR o su Discord.
Lo scenario dovrebbe poter fallire in due modi diversi:
@ -241,22 +303,20 @@ Lo scenario dovrebbe poter fallire in due modi diversi:
- **Errore dell'harness**: configurazione dell'ambiente, credenziali, API Discord, browser o
provider sono falliti prima che l'oracolo del bug fosse significativo.
Il report finale deve separare questi casi, così i manutentori non confondono un
ambiente flaky con il comportamento del prodotto.
Il report finale deve separare questi casi in modo che i maintainer non confondano un ambiente instabile
con il comportamento del prodotto.
## MVP Discord
Il primo scenario dovrebbe prendere di mira le reazioni di stato Discord nei
canali guild in cui la modalità di consegna della risposta sorgente è
`message_tool_only`.
Il primo scenario dovrebbe prendere di mira le reazioni di stato Discord nei canali di server in cui
la modalità di consegna della risposta sorgente è `message_tool_only`.
Perché è un buon seme Mantis:
- È visibile in Discord come reazioni sul messaggio che ha attivato l'azione.
- Ha un forte oracolo REST tramite lo stato delle reazioni ai messaggi Discord.
- Esercita un vero Gateway OpenClaw, autenticazione bot Discord, dispatch dei
messaggi, modalità di consegna della risposta sorgente, stato delle reazioni
di stato e ciclo di vita del turno del modello.
- È visibile in Discord come reazioni sul messaggio di attivazione.
- Ha un oracolo REST forte tramite lo stato delle reazioni del messaggio Discord.
- Esercita un vero OpenClaw Gateway, autenticazione del bot Discord, dispatch dei messaggi,
modalità di consegna della risposta sorgente, stato delle reazioni di stato e ciclo di vita del turno del modello.
- È abbastanza ristretto da mantenere onesta la prima implementazione.
Forma prevista dello scenario:
@ -290,12 +350,12 @@ evidence:
screenshotMessageRow: true
```
Le prove baseline dovrebbero mostrare la reazione di acknowledgement queued ma
nessuna transizione di ciclo di vita in modalità solo tool. Le prove candidate
dovrebbero mostrare le reazioni di stato del ciclo di vita in esecuzione quando
`messages.statusReactions.enabled` è esplicitamente true.
L'evidenza di baseline dovrebbe mostrare la reazione di riconoscimento in coda ma nessuna
transizione del ciclo di vita in modalità solo strumento. L'evidenza del candidato dovrebbe mostrare le reazioni di stato
del ciclo di vita in esecuzione quando `messages.statusReactions.enabled` è esplicitamente
true.
La prima slice eseguibile è lo scenario QA live Discord opt-in:
La prima porzione eseguibile è lo scenario QA live Discord opt-in:
```bash
pnpm openclaw qa discord \
@ -307,9 +367,9 @@ pnpm openclaw qa discord \
--output-dir .artifacts/qa-e2e/mantis/discord-status-reactions-candidate
```
Configura il SUT con gestione delle guild sempre attiva, `visibleReplies:
Configura il SUT con gestione dei server sempre attiva, `visibleReplies:
"message_tool"`, `ackReaction: "👀"` e reazioni di stato esplicite. L'oracolo
interroga il messaggio di attivazione Discord reale e si aspetta la sequenza osservata
interroga il vero messaggio Discord di attivazione e si aspetta la sequenza osservata
`👀 -> 🤔 -> 👍`. Gli artefatti includono `discord-qa-reaction-timelines.json`,
`discord-status-reactions-tool-only-timeline.html` e
`discord-status-reactions-tool-only-timeline.png`.
@ -321,18 +381,18 @@ zero:
- `pnpm openclaw qa discord` esegue già una corsia Discord live con bot driver e
SUT.
- Il runner del trasporto live scrive già report e artefatti dei messaggi osservati
in `.artifacts/qa-e2e/`.
- I lease delle credenziali Convex forniscono già accesso esclusivo alle credenziali
di trasporto live condivise.
- Il servizio di controllo del browser supporta già screenshot, snapshot,
- Il runner di trasporto live scrive già report e artefatti dei messaggi osservati
sotto `.artifacts/qa-e2e/`.
- I lease delle credenziali Convex forniscono già accesso esclusivo alle credenziali di trasporto live
condivise.
- Il servizio di controllo browser supporta già screenshot, snapshot,
profili gestiti headless e profili CDP remoti.
- QA Lab dispone già di un'interfaccia debugger e di un bus per test modellati sui trasporti.
- QA Lab dispone già di una UI di debug e di un bus per test con forma di trasporto.
La prima implementazione di Mantis può essere un runner sottile prima/dopo sopra questi
La prima implementazione di Mantis può essere un runner prima/dopo sottile sopra questi
componenti, più un livello di evidenza visiva.
## Modello Di Evidenza
## Modello di evidenza
Ogni esecuzione scrive una directory di artefatti stabile:
@ -355,76 +415,76 @@ Ogni esecuzione scrive una directory di artefatti stabile:
```
`mantis-summary.json` dovrebbe essere la fonte di verità leggibile dalla macchina. Il
report Markdown è destinato ai commenti sulle PR e alla revisione umana.
report Markdown è per commenti PR e revisione umana.
Il riepilogo deve includere:
- ref e SHA testati
- trasporto e id dello scenario
- provider della macchina e id della macchina o id del lease
- trasporto e id scenario
- provider macchina e id macchina o id lease
- fonte delle credenziali senza valori segreti
- risultato baseline
- risultato candidate
- risultato candidato
- se il bug è stato riprodotto sulla baseline
- se il candidate lo ha corretto
- se il candidato lo ha corretto
- percorsi degli artefatti
- problemi di configurazione o pulizia sanificati
Gli screenshot sono evidenze, non segreti. Richiedono comunque disciplina di redazione:
possono comparire nomi di canali privati, nomi utente o contenuti dei messaggi. Per PR pubbliche,
preferire link agli artefatti GitHub Actions rispetto a immagini inline finché la strategia di redazione
non sarà più solida.
Gli screenshot sono evidenza, non segreti. Richiedono comunque disciplina di redazione:
possono comparire nomi di canali privati, nomi utente o contenuto dei messaggi. Per PR pubbliche,
preferire link agli artefatti di GitHub Actions rispetto a immagini inline finché la storia di redazione
non è più solida.
## Browser E VNC
## Browser e VNC
La corsia del browser ha due modalità:
La corsia browser ha due modalità:
- **Automazione headless**: predefinita per la CI. Chrome viene eseguito con CDP abilitato, e
Playwright o il controllo browser di OpenClaw acquisisce screenshot.
- **Soccorso VNC**: abilitato sulla stessa VM quando accesso, MFA, anti-automazione di Discord
o debugging visivo richiedono una persona.
- **Automazione headless**: predefinita per CI. Chrome viene eseguito con CDP abilitato, e
Playwright o il controllo browser di OpenClaw acquisiscono screenshot.
- **Recupero VNC**: abilitato sulla stessa VM quando login, MFA, anti-automazione Discord
o debug visivo richiedono una persona.
Il profilo browser dell'osservatore Discord dovrebbe essere abbastanza persistente da evitare
l'accesso a ogni esecuzione, ma isolato dallo stato del browser personale. Un profilo
Il profilo browser osservatore Discord dovrebbe essere abbastanza persistente da evitare
il login a ogni esecuzione, ma isolato dallo stato del browser personale. Un profilo
appartiene al pool di macchine Mantis, non al laptop di uno sviluppatore.
Quando Mantis si blocca, pubblica un messaggio di stato Discord con:
- id dell'esecuzione
- id dello scenario
- provider della macchina
- id esecuzione
- id scenario
- provider macchina
- directory degli artefatti
- istruzioni di connessione VNC o noVNC se disponibili
- breve testo del blocco
Il primo deployment privato può pubblicare questi messaggi nel canale operator esistente
e spostarli successivamente in un canale Mantis dedicato.
Il primo deployment privato può pubblicare questi messaggi nel canale operatore
esistente e spostarsi in seguito a un canale Mantis dedicato.
## Macchine
Mantis dovrebbe preferire AWS tramite Crabbox per la prima implementazione remota.
Crabbox ci fornisce macchine preriscaldate, tracciamento dei lease, idratazione, log, risultati e
Crabbox ci offre macchine preriscaldate, tracciamento dei lease, idratazione, log, risultati e
pulizia. Se la capacità AWS è troppo lenta o non disponibile, aggiungere un provider Hetzner
dietro la stessa interfaccia macchina.
Requisiti minimi della VM:
- Linux con un'installazione di Chrome o Chromium adatta a desktop
- accesso CDP per automazione del browser
- VNC o noVNC per il soccorso
- Linux con un'installazione di Chrome o Chromium capace di desktop
- accesso CDP per l'automazione browser
- VNC o noVNC per il recupero
- Node 22 e pnpm
- checkout OpenClaw e cache delle dipendenze
- cache del browser Chromium di Playwright quando si usa Playwright
- CPU e memoria sufficienti per un OpenClaw Gateway, un browser e un'esecuzione modello
- cache browser Playwright Chromium quando si usa Playwright
- CPU e memoria sufficienti per un OpenClaw Gateway, un browser e un'esecuzione del modello
- accesso in uscita a Discord, GitHub, provider di modelli e broker delle credenziali
La VM non dovrebbe conservare segreti grezzi a lunga durata al di fuori degli store di credenziali o
La VM non dovrebbe conservare segreti raw di lunga durata fuori dagli store di credenziali o
profili browser previsti.
## Segreti
I segreti vivono nei segreti dell'organizzazione o del repository GitHub per le esecuzioni remote, e in
un file segreto locale controllato dall'operator per le esecuzioni locali.
un file di segreti locale controllato dall'operatore per le esecuzioni locali.
Nomi di segreti consigliati:
@ -434,17 +494,17 @@ Nomi di segreti consigliati:
- `OPENCLAW_QA_DISCORD_GUILD_ID`
- `OPENCLAW_QA_DISCORD_CHANNEL_ID`
- `OPENCLAW_QA_DISCORD_NOTIFY_CHANNEL_ID`
- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` per caricamenti di artefatti GitHub pubblici
- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` per caricamenti pubblici di artefatti GitHub
- `OPENCLAW_QA_CONVEX_SITE_URL`
- `OPENCLAW_QA_CONVEX_SECRET_CI`
- `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR`
- `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR_TOKEN`
A lungo termine, il pool di credenziali Convex dovrebbe rimanere la fonte normale per le credenziali di
trasporto live. I segreti GitHub inizializzano il broker e le corsie di fallback.
Il workflow Discord status-reactions mappa i segreti Mantis Crabbox di nuovo alle
variabili d'ambiente `CRABBOX_COORDINATOR` e `CRABBOX_COORDINATOR_TOKEN`
attese dalla CLI Crabbox. I nomi dei segreti GitHub `CRABBOX_*` semplici restano
A lungo termine, il pool di credenziali Convex dovrebbe restare la fonte normale per le credenziali di
trasporto live. I segreti GitHub eseguono il bootstrap del broker e delle corsie di fallback.
Il workflow Discord status-reactions mappa i segreti Mantis Crabbox di nuovo alle variabili d'ambiente
`CRABBOX_COORDINATOR` e `CRABBOX_COORDINATOR_TOKEN`
attese dalla CLI Crabbox. I nomi semplici dei segreti GitHub `CRABBOX_*` restano
accettati come fallback di compatibilità.
Il runner Mantis non deve mai stampare:
@ -454,31 +514,32 @@ Il runner Mantis non deve mai stampare:
- cookie del browser
- contenuti dei profili di autenticazione
- password VNC
- payload di credenziali grezzi
- payload raw delle credenziali
Anche i caricamenti di artefatti pubblici dovrebbero redigere i metadati target Discord come bot,
guild, canali e id dei messaggi. Il workflow smoke GitHub abilita
Anche i caricamenti di artefatti pubblici dovrebbero oscurare i metadati dei target Discord come bot,
server, canale e id messaggio. Il workflow smoke GitHub abilita
`OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` per questo motivo.
Se un token viene incollato accidentalmente in una issue, PR, chat o log, ruotarlo
dopo che il nuovo segreto è stato salvato.
Se un token viene accidentalmente incollato in un issue, PR, chat o log, ruotarlo
dopo che il nuovo segreto è stato memorizzato.
## Artefatti GitHub E Commenti PR
## Artefatti GitHub e commenti PR
I workflow Mantis dovrebbero caricare il bundle completo di evidenze come artefatto Actions
a breve durata. Quando il workflow viene eseguito per una segnalazione di bug o una PR di correzione,
dovrebbe anche pubblicare gli screenshot PNG redatti nel branch `qa-artifacts` e aggiornare o creare
un commento su quel bug o PR di correzione con screenshot inline prima/dopo. Non pubblicare
la prova principale solo su una PR generica di automazione QA. Log grezzi, messaggi osservati
I workflow Mantis dovrebbero caricare il bundle completo di evidenza come artefatto Actions
a breve durata. Quando il workflow viene eseguito per una segnalazione di bug o una PR di fix, dovrebbe anche
pubblicare gli screenshot PNG redatti nel branch `qa-artifacts` e aggiornare o creare un
commento su quel bug o quella PR di fix con screenshot prima/dopo inline. Non pubblicare
la prova primaria solo su una PR generica di automazione QA. Log raw, messaggi osservati
e altre evidenze voluminose restano nell'artefatto Actions.
I workflow di produzione dovrebbero pubblicare quei commenti con la GitHub App Mantis, non
con `github-actions[bot]`. Salvare l'id dell'app e la chiave privata come segreti GitHub Actions
`MANTIS_GITHUB_APP_ID` e `MANTIS_GITHUB_APP_PRIVATE_KEY`. Il workflow usa un marker nascosto
come chiave di upsert, aggiorna quel commento quando il token può modificarlo e crea un nuovo
commento di proprietà Mantis quando un marker precedente di proprietà del bot non può essere modificato.
con `github-actions[bot]`. Memorizzare l'app id e la chiave privata come segreti
GitHub Actions `MANTIS_GITHUB_APP_ID` e `MANTIS_GITHUB_APP_PRIVATE_KEY`.
Il workflow usa un marker nascosto come chiave di upsert, aggiorna quel
commento quando il token può modificarlo e crea un nuovo commento di proprietà Mantis quando
un marker più vecchio di proprietà del bot non può essere modificato.
Il commento sulla PR dovrebbe essere breve e visivo:
Il commento PR dovrebbe essere breve e visivo:
```md
Mantis Discord Status Reactions QA
@ -499,72 +560,72 @@ candidate showed the expected queued -> thinking -> done sequence.
```
Quando l'esecuzione fallisce perché l'harness è fallito, il commento deve dirlo invece
di implicare che il candidate sia fallito.
di lasciare intendere che il candidato sia fallito.
## Note Di Deployment Privato
## Note sul deployment privato
Un deployment privato potrebbe già avere un'applicazione Discord Mantis. Riutilizzare quella
applicazione invece di creare un'altra app quando ha i permessi bot corretti
Un deployment privato potrebbe già avere un'applicazione Discord Mantis. Riutilizzare tale
applicazione invece di creare un'altra app quando ha le autorizzazioni bot corrette
e può essere ruotata in sicurezza.
Impostare il canale iniziale di notifica operator tramite segreti o configurazione di deployment.
Può puntare prima a un canale maintainer o operations esistente,
poi spostarsi in un canale Mantis dedicato quando ne esisterà uno.
Impostare il canale iniziale di notifica operatore tramite segreti o configurazione di
deployment. Può puntare prima a un canale maintainer o operations esistente,
poi spostarsi a un canale Mantis dedicato quando ne esiste uno.
Non inserire guild id, channel id, token bot, cookie del browser o password VNC
in questo documento. Salvarli nei segreti GitHub, nel broker delle credenziali o nello
store segreto locale dell'operator.
Non inserire id server, id canale, token bot, cookie browser o password VNC
in questo documento. Memorizzarli nei segreti GitHub, nel broker delle credenziali o nello
store segreti locale dell'operatore.
## Aggiungere Uno Scenario
## Aggiunta di uno scenario
Uno scenario Mantis dovrebbe dichiarare:
- id e titolo
- trasporto
- credenziali richieste
- policy dei ref baseline
- policy dei ref candidate
- patch della configurazione OpenClaw
- policy del ref di baseline
- policy del ref candidato
- patch di configurazione OpenClaw
- passaggi di configurazione
- stimolo
- oracolo baseline atteso
- oracolo candidate atteso
- oracolo candidato atteso
- target di acquisizione visiva
- budget di timeout
- passaggi di pulizia
Gli scenari dovrebbero preferire oracoli piccoli e tipizzati:
- stato delle reazioni Discord per bug di reazioni
- stato delle reazioni Discord per bug di reazione
- riferimenti ai messaggi Discord per bug di threading
- thread ts Slack e stato dell'API delle reazioni per bug Slack
- id e intestazioni dei messaggi email per bug email
- screenshot del browser quando l'interfaccia utente è l'unico osservabile affidabile
- ts del thread Slack e stato API delle reazioni per bug Slack
- id messaggio e header email per bug email
- screenshot browser quando la UI è l'unico osservabile affidabile
I controlli visivi dovrebbero essere additivi. Se un'API della piattaforma può dimostrare il bug, usare
l'API come oracolo pass/fail e mantenere gli screenshot per la fiducia umana.
I controlli visivi dovrebbero essere additivi. Se un'API della piattaforma può provare il bug, usare l'
API come oracolo pass/fail e mantenere gli screenshot per la fiducia umana.
## Espansione Dei Provider
## Espansione dei provider
Dopo Discord, lo stesso runner può aggiungere:
- Slack: reazioni, thread, menzioni dell'app, modali, caricamenti di file.
- Email: autenticazione Gmail e threading dei messaggi usando `gog` dove i connettori non sono
- E-mail: autenticazione Gmail e threading dei messaggi tramite `gog` dove i connettori non sono
sufficienti.
- WhatsApp: accesso QR, re-identificazione, consegna dei messaggi, media, reazioni.
- WhatsApp: accesso tramite QR, ri-identificazione, consegna dei messaggi, media, reazioni.
- Telegram: gating delle menzioni nei gruppi, comandi, reazioni dove disponibili.
- Matrix: stanze cifrate, relazioni di thread o risposta, ripresa dopo riavvio.
- Matrix: stanze crittografate, relazioni di thread o risposta, ripresa dopo il riavvio.
Ogni trasporto dovrebbe avere uno scenario smoke economico e uno o più scenari per classi di bug.
Gli scenari visivi costosi dovrebbero rimanere opt-in.
Ogni trasporto dovrebbe avere uno scenario smoke economico e uno o più scenari
per classe di bug. Gli scenari visivi costosi dovrebbero restare opt-in.
## Domande Aperte
- Quale bot Discord dovrebbe essere il driver e quale il SUT quando viene riutilizzato il
bot Mantis esistente?
- Quale bot Discord dovrebbe essere il driver e quale dovrebbe essere il SUT quando viene
riutilizzato il bot Mantis esistente?
- L'accesso del browser osservatore dovrebbe usare un account Discord umano, un account di test
o solo evidenza REST leggibile dai bot per la prima fase?
o solo prove REST leggibili dal bot per la prima fase?
- Per quanto tempo GitHub dovrebbe conservare gli artefatti Mantis per le PR?
- Quando ClawSweeper dovrebbe raccomandare automaticamente Mantis invece di attendere un
comando maintainer?
- Gli screenshot dovrebbero essere redatti o ritagliati prima del caricamento per PR pubbliche?
- Quando ClawSweeper dovrebbe consigliare automaticamente Mantis invece di attendere un
comando da un responsabile della manutenzione?
- Gli screenshot dovrebbero essere oscurati o ritagliati prima del caricamento per le PR pubbliche?

367
docs/it/gateway/doctor.md
View File

@ -1,20 +1,20 @@
---
read_when:
- Aggiungere o modificare le migrazioni di doctor
- Introduzione di modifiche di configurazione incompatibili
- Aggiunta o modifica delle migrazioni di doctor
- Introduzione di modifiche incompatibili alla configurazione
sidebarTitle: Doctor
summary: 'Comando doctor: controlli di integrità, migrazioni della configurazione e passaggi di riparazione'
title: Diagnostica
x-i18n:
generated_at: "2026-05-05T01:46:13Z"
generated_at: "2026-05-05T08:25:44Z"
model: gpt-5.5
provider: openai
source_hash: 3e374f91d00d4b43a3852de6f746b044471e80af936d464a789061a31cadd09d
source_hash: 360f9f7a349e4633ff61d526f1eb5b668b595b4f35c5e0fd2a314715a0599c4c
source_path: gateway/doctor.md
workflow: 16
---
`openclaw doctor` è lo strumento di riparazione + migrazione per OpenClaw. Corregge configurazione/stato obsoleti, controlla l'integrità e fornisce passaggi di riparazione attuabili.
`openclaw doctor` è lo strumento di riparazione + migrazione per OpenClaw. Corregge configurazioni/stato obsoleti, verifica l’integrità e fornisce passaggi di riparazione pratici.
## Avvio rapido
@ -22,7 +22,7 @@ x-i18n:
openclaw doctor
```
### Modalità headless e di automazione
### Modalità senza interfaccia e di automazione
<Tabs>
<Tab title="--yes">
@ -30,7 +30,7 @@ openclaw doctor
openclaw doctor --yes
```
Accetta i valori predefiniti senza chiedere conferma (inclusi i passaggi di riavvio/servizio/riparazione sandbox quando applicabili).
Accetta i valori predefiniti senza richiedere conferma (inclusi i passaggi di riparazione per riavvio/servizio/sandbox quando applicabili).
</Tab>
<Tab title="--repair">
@ -38,7 +38,7 @@ openclaw doctor
openclaw doctor --repair
```
Applica le riparazioni consigliate senza chiedere conferma (riparazioni + riavvii dove sicuro).
Applica le riparazioni consigliate senza richiedere conferma (riparazioni + riavvii quando sicuri).
</Tab>
<Tab title="--repair --force">
@ -46,7 +46,7 @@ openclaw doctor
openclaw doctor --repair --force
```
Applica anche le riparazioni aggressive (sovrascrive le configurazioni supervisor personalizzate).
Applica anche riparazioni aggressive (sovrascrive le configurazioni supervisor personalizzate).
</Tab>
<Tab title="--non-interactive">
@ -54,7 +54,7 @@ openclaw doctor
openclaw doctor --non-interactive
```
Esegue senza prompt e applica solo migrazioni sicure (normalizzazione della configurazione + spostamenti dello stato su disco). Salta azioni di riavvio/servizio/sandbox che richiedono conferma umana. Le migrazioni dello stato legacy vengono eseguite automaticamente quando rilevate.
Esegue senza prompt e applica solo migrazioni sicure (normalizzazione della configurazione + spostamenti dello stato su disco). Salta le azioni di riavvio/servizio/sandbox che richiedono conferma umana. Le migrazioni dello stato legacy vengono eseguite automaticamente quando rilevate.
</Tab>
<Tab title="--deep">
@ -62,12 +62,12 @@ openclaw doctor
openclaw doctor --deep
```
Scansiona i servizi di sistema alla ricerca di installazioni Gateway aggiuntive (launchd/systemd/schtasks).
Scansiona i servizi di sistema per installazioni Gateway aggiuntive (launchd/systemd/schtasks).
</Tab>
</Tabs>
Se vuoi esaminare le modifiche prima della scrittura, apri prima il file di configurazione:
Se vuoi esaminare le modifiche prima di scriverle, apri prima il file di configurazione:
```bash
cat ~/.openclaw/openclaw.json
@ -76,63 +76,64 @@ cat ~/.openclaw/openclaw.json
## Cosa fa (riepilogo)
<AccordionGroup>
<Accordion title="Integrità, interfaccia utente e aggiornamenti">
<Accordion title="Integrità, UI e aggiornamenti">
- Aggiornamento pre-flight opzionale per installazioni git (solo interattivo).
- Controllo della freschezza del protocollo dell'interfaccia utente (ricompila la Control UI quando lo schema del protocollo è più recente).
- Controllo di integrità + prompt di riavvio.
- Riepilogo dello stato Skills (idonee/mancanti/bloccate) e stato plugin.
- Verifica di aggiornamento del protocollo UI (ricompila Control UI quando lo schema del protocollo è più recente).
- Verifica di integrità + prompt di riavvio.
- Riepilogo dello stato Skills (idonee/mancanti/bloccate) e stato dei plugin.
</Accordion>
<Accordion title="Configurazione e migrazioni">
- Normalizzazione della configurazione per valori legacy.
- Migrazione della configurazione Talk dai campi flat legacy `talk.*` a `talk.provider` + `talk.providers.<provider>`.
- Controlli di migrazione del browser per configurazioni legacy dell'estensione Chrome e preparazione Chrome MCP.
- Verifiche di migrazione del browser per configurazioni legacy dell’estensione Chrome e preparazione Chrome MCP.
- Avvisi sugli override del provider OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
- Avvisi di shadowing OAuth Codex (`models.providers.openai-codex`).
- Controllo dei prerequisiti TLS OAuth per i profili OAuth OpenAI Codex.
- Avvisi allowlist plugin/strumenti quando `plugins.allow` è restrittivo ma la policy degli strumenti richiede ancora wildcard o strumenti di proprietà dei plugin.
- Verifica dei prerequisiti OAuth TLS per i profili OAuth OpenAI Codex.
- Avvisi sulla allowlist di plugin/strumenti quando `plugins.allow` è restrittivo ma la policy degli strumenti richiede ancora wildcard o strumenti di proprietà del plugin.
- Migrazione dello stato legacy su disco (sessioni/directory agente/auth WhatsApp).
- Migrazione delle chiavi del contratto del manifest plugin legacy (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
- Migrazione dello store Cron legacy (`jobId`, `schedule.cron`, campi delivery/payload di primo livello, payload `provider`, job fallback Webhook semplici `notify: true`).
- Migrazione delle chiavi legacy del contratto manifest del plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
- Migrazione dello store Cron legacy (`jobId`, `schedule.cron`, campi delivery/payload di primo livello, payload `provider`, semplici job Webhook fallback `notify: true`).
- Migrazione della runtime-policy agente legacy a `agents.defaults.agentRuntime` e `agents.list[].agentRuntime`.
- Pulizia della configurazione plugin obsoleta quando i plugin sono abilitati; quando `plugins.enabled=false`, i riferimenti plugin obsoleti vengono trattati come configurazione di contenimento inerte e vengono preservati.
- Pulizia della configurazione di plugin obsoleta quando i plugin sono abilitati; quando `plugins.enabled=false`, i riferimenti a plugin obsoleti sono trattati come configurazione di contenimento inerte e preservati.
</Accordion>
<Accordion title="Stato e integrità">
- Ispezione dei file di lock delle sessioni e pulizia dei lock obsoleti.
- Riparazione delle trascrizioni di sessione per rami prompt-rewrite duplicati creati dalle build 2026.4.24 interessate.
- Rilevamento delle tombstone di restart-recovery per subagent bloccati, con supporto `--fix` per cancellare flag di recovery interrotti obsoleti in modo che l'avvio non continui a trattare il figlio come interrotto dal riavvio.
- Controlli di integrità dello stato e permessi (sessioni, trascrizioni, directory di stato).
- Controlli dei permessi del file di configurazione (chmod 600) durante l'esecuzione locale.
- Integrità auth del modello: controlla la scadenza OAuth, può aggiornare token in scadenza e segnala stati cooldown/disabilitati dei profili auth.
- Riparazione delle trascrizioni delle sessioni per rami duplicati di riscrittura prompt creati dalle build 2026.4.24 interessate.
- Rilevamento delle tombstone di restart-recovery dei sottoagenti bloccati, con supporto `--fix` per cancellare flag di recovery interrotta obsoleti così che l’avvio non continui a trattare il figlio come restart-aborted.
- Verifiche di integrità dello stato e dei permessi (sessioni, trascrizioni, directory di stato).
- Verifiche dei permessi del file di configurazione (chmod 600) durante l’esecuzione locale.
- Integrità auth modello: verifica la scadenza OAuth, può aggiornare token in scadenza e segnala stati cooldown/disabilitati degli auth-profile.
- Rilevamento di directory workspace aggiuntive (`~/openclaw`).
</Accordion>
<Accordion title="Gateway, servizi e supervisor">
- Riparazione dell'immagine sandbox quando il sandboxing è abilitato.
- Riparazione dell’immagine sandbox quando il sandboxing è abilitato.
- Migrazione dei servizi legacy e rilevamento di Gateway aggiuntivi.
- Migrazione dello stato legacy del canale Matrix (in modalità `--fix` / `--repair`).
- Controlli runtime Gateway (servizio installato ma non in esecuzione; label launchd in cache).
- Verifiche runtime del Gateway (servizio installato ma non in esecuzione; etichetta launchd in cache).
- Avvisi sullo stato dei canali (sondati dal Gateway in esecuzione).
- Verifiche di reattività WhatsApp per integrità degradata dell’event loop del Gateway con client TUI locali ancora in esecuzione; `--fix` arresta solo i client TUI locali verificati.
- Audit della configurazione supervisor (launchd/systemd/schtasks) con riparazione opzionale.
- Pulizia dell'ambiente proxy incorporato per servizi Gateway che hanno acquisito valori shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` durante installazione o aggiornamento.
- Controlli delle best practice runtime Gateway (Node vs Bun, percorsi dei version manager).
- Diagnostica delle collisioni della porta Gateway (predefinita `18789`).
- Pulizia dell’ambiente del proxy incorporato per servizi Gateway che hanno catturato valori shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` durante installazione o aggiornamento.
- Verifiche delle best practice runtime del Gateway (Node vs Bun, percorsi dei version-manager).
- Diagnostica delle collisioni sulla porta Gateway (predefinita `18789`).
</Accordion>
<Accordion title="Auth, sicurezza e pairing">
- Avvisi di sicurezza per policy DM aperte.
- Controlli auth Gateway per la modalità token locale (offre la generazione del token quando non esiste alcuna origine token; non sovrascrive configurazioni token SecretRef).
- Rilevamento di problemi di pairing dispositivo (richieste di pairing iniziale in sospeso, upgrade ruolo/ambito in sospeso, drift obsoleto della cache token-dispositivo locale e drift auth dei record associati).
- Verifiche auth Gateway per la modalità token locale (offre la generazione del token quando non esiste alcuna sorgente token; non sovrascrive le configurazioni token SecretRef).
- Rilevamento problemi di pairing del dispositivo (richieste di primo pairing in sospeso, aggiornamenti ruolo/ambito in sospeso, drift della cache locale device-token obsoleta e drift auth dei record associati).
</Accordion>
<Accordion title="Workspace e shell">
- Controllo systemd linger su Linux.
- Controllo delle dimensioni del file di bootstrap del workspace (avvisi di troncamento/vicino al limite per file di contesto).
- Controllo di preparazione Skills per l'agente predefinito; segnala skill consentite con binari, env, configurazione o requisiti OS mancanti, e `--fix` può disabilitare skill non disponibili in `skills.entries`.
- Controllo dello stato del completamento shell e installazione/upgrade automatico.
- Controllo di preparazione del provider di embedding per la ricerca in memoria (modello locale, chiave API remota o binario QMD).
- Controlli delle installazioni da sorgente (mancata corrispondenza workspace pnpm, asset UI mancanti, binario tsx mancante).
- Verifica systemd linger su Linux.
- Verifica dimensione del file di bootstrap del workspace (avvisi di troncamento/quasi limite per file di contesto).
- Verifica di preparazione Skills per l’agente predefinito; segnala skill consentite con binari, env, configurazione o requisiti OS mancanti, e `--fix` può disabilitare skill non disponibili in `skills.entries`.
- Verifica dello stato di completamento shell e installazione/upgrade automatici.
- Verifica di preparazione del provider embedding per la ricerca in memoria (modello locale, chiave API remota o binario QMD).
- Verifiche delle installazioni da sorgente (mismatch workspace pnpm, asset UI mancanti, binario tsx mancante).
- Scrive configurazione aggiornata + metadati wizard.
</Accordion>
@ -140,49 +141,49 @@ cat ~/.openclaw/openclaw.json
## Backfill e reset della UI Dreams
La scena Dreams della Control UI include le azioni **Backfill**, **Reset** e **Clear Grounded** per il flusso di lavoro grounded dreaming. Queste azioni usano metodi RPC in stile Gateway doctor, ma **non** fanno parte della riparazione/migrazione CLI di `openclaw doctor`.
La scena Dreams della Control UI include azioni **Backfill**, **Reset** e **Clear Grounded** per il workflow di grounded dreaming. Queste azioni usano metodi RPC in stile doctor del gateway, ma **non** fanno parte della riparazione/migrazione CLI di `openclaw doctor`.
Cosa fanno:
- **Backfill** scansiona i file storici `memory/YYYY-MM-DD.md` nel workspace attivo, esegue il passaggio del diario REM grounded e scrive voci di backfill reversibili in `DREAMS.md`.
- **Reset** rimuove da `DREAMS.md` solo quelle voci di diario di backfill marcate.
- **Clear Grounded** rimuove solo voci temporanee staged grounded-only che provengono dal replay storico e non hanno ancora accumulato richiamo live o supporto giornaliero.
- **Reset** rimuove solo quelle voci di diario di backfill marcate da `DREAMS.md`.
- **Clear Grounded** rimuove solo voci short-term staged solo grounded che provengono da replay storico e non hanno ancora accumulato richiamo live o supporto giornaliero.
Cosa **non** fanno da sole:
- non modificano `MEMORY.md`
- non eseguono migrazioni doctor complete
- non inseriscono automaticamente candidati grounded nello store di promozione live a breve termine a meno che tu non esegua prima esplicitamente il percorso CLI staged
- non inseriscono automaticamente candidati grounded nello store di promozione short-term live a meno che tu non esegua prima esplicitamente il percorso CLI staged
Se vuoi che il replay storico grounded influenzi la normale lane di promozione profonda, usa invece il flusso CLI:
Se vuoi che il replay storico grounded influenzi la normale corsia di promozione profonda, usa invece il flusso CLI:
```bash
openclaw memory rem-backfill --path ./memory --stage-short-term
```
Questo inserisce candidati durevoli grounded nello store Dreaming a breve termine mantenendo `DREAMS.md` come superficie di revisione.
Questo inserisce candidati durevoli grounded nello store di dreaming short-term mantenendo `DREAMS.md` come superficie di revisione.
## Comportamento dettagliato e motivazione
<AccordionGroup>
<Accordion title="0. Aggiornamento opzionale (installazioni git)">
Se questa è una checkout git e doctor è in esecuzione in modo interattivo, offre di aggiornare (fetch/rebase/build) prima di eseguire doctor.
Se questo è un checkout git e doctor è in esecuzione in modo interattivo, offre di aggiornare (fetch/rebase/build) prima di eseguire doctor.
</Accordion>
<Accordion title="1. Normalizzazione della configurazione">
Se la configurazione contiene forme di valori legacy (per esempio `messages.ackReaction` senza override specifico del canale), doctor le normalizza nello schema corrente.
Se la configurazione contiene forme di valori legacy (per esempio `messages.ackReaction` senza un override specifico per canale), doctor le normalizza nello schema corrente.
Questo include i campi flat legacy di Talk. La configurazione Talk pubblica corrente è `talk.provider` + `talk.providers.<provider>`. Doctor riscrive le vecchie forme `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` nella mappa provider.
Questo include i campi flat Talk legacy. La configurazione Talk pubblica corrente è `talk.provider` + `talk.providers.<provider>`. Doctor riscrive le vecchie forme `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` nella mappa dei provider.
Doctor avvisa anche quando `plugins.allow` non è vuoto e la policy degli strumenti usa
wildcard o voci di strumenti di proprietà dei plugin. `tools.allow: ["*"]` corrisponde solo agli strumenti
dei plugin che vengono effettivamente caricati; non aggira l'allowlist esclusiva dei plugin.
Doctor scrive `plugins.bundledDiscovery: "compat"` per le configurazioni allowlist
legacy migrate per preservare il comportamento esistente dei provider bundled, e
poi punta all'impostazione più restrittiva `"allowlist"`.
voci wildcard o strumenti di proprietà del plugin. `tools.allow: ["*"]` corrisponde solo agli strumenti
provenienti da plugin che vengono effettivamente caricati; non aggira la allowlist esclusiva dei plugin.
Doctor scrive `plugins.bundledDiscovery: "compat"` per configurazioni allowlist legacy migrate
per preservare il comportamento esistente dei provider bundled, quindi
rimanda all’impostazione più rigorosa `"allowlist"`.
</Accordion>
<Accordion title="2. Migrazioni delle chiavi di configurazione legacy">
Quando la configurazione contiene chiavi deprecate, gli altri comandi rifiutano di eseguirsi e chiedono di eseguire `openclaw doctor`.
Quando la configurazione contiene chiavi deprecate, altri comandi si rifiutano di eseguire e chiedono di eseguire `openclaw doctor`.
Doctor:
@ -190,7 +191,7 @@ Questo inserisce candidati durevoli grounded nello store Dreaming a breve termin
- Mostrerà la migrazione applicata.
- Riscriverà `~/.openclaw/openclaw.json` con lo schema aggiornato.
Anche il Gateway esegue automaticamente le migrazioni doctor all'avvio quando rileva un formato di configurazione legacy, quindi le configurazioni obsolete vengono riparate senza intervento manuale. Le migrazioni dello store dei job Cron sono gestite da `openclaw doctor --fix`.
Anche il Gateway esegue automaticamente le migrazioni doctor all’avvio quando rileva un formato di configurazione legacy, quindi le configurazioni obsolete vengono riparate senza intervento manuale. Le migrazioni dello store dei job Cron sono gestite da `openclaw doctor --fix`.
Migrazioni correnti:
@ -199,11 +200,11 @@ Questo inserisce candidati durevoli grounded nello store Dreaming a breve termin
- `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit`
- `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns`
- `channels.telegram.requireMention` → `channels.telegram.groups."*".requireMention`
- configurazioni di canali configurati prive di criterio di risposta visibile → `messages.groupChat.visibleReplies: "message_tool"`
- configurazioni di canali configurati senza policy di risposta visibile → `messages.groupChat.visibleReplies: "message_tool"`
- `routing.queue` → `messages.queue`
- `routing.bindings` → `bindings` di livello superiore
- `routing.bindings` → `bindings` di primo livello
- `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`
- legacy `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.<provider>`
- `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` legacy → `talk.provider` + `talk.providers.<provider>`
- `routing.agentToAgent` → `tools.agentToAgent`
- `routing.transcribeAudio` → `tools.media.audio.models`
- `messages.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.<provider>`
@ -217,290 +218,290 @@ Questo inserisce candidati durevoli grounded nello store Dreaming a breve termin
- `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider`
- `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*`
- `bindings[].match.accountID` → `bindings[].match.accountId`
- Per i canali con `accounts` denominati ma con valori di canale di livello superiore per account singolo ancora presenti, sposta quei valori con ambito account nell'account promosso scelto per quel canale (`accounts.default` per la maggior parte dei canali; Matrix può conservare un target denominato/predefinito corrispondente esistente)
- Per i canali con `accounts` denominati ma valori di canale di primo livello per account singolo ancora presenti, sposta quei valori con ambito account nell'account promosso scelto per quel canale (`accounts.default` per la maggior parte dei canali; Matrix può preservare una destinazione denominata/predefinita corrispondente già esistente)
- `identity` → `agents.list[].identity`
- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
- rimuovi `agents.defaults.llm`; usa `models.providers.<id>.timeoutSeconds` per i timeout lenti di provider/modelli
- rimuovi `agents.defaults.llm`; usa `models.providers.<id>.timeoutSeconds` per i timeout di provider/modelli lenti
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
- rimuovi `browser.relayBindHost` (impostazione legacy del relay dell'estensione)
- legacy `models.providers.*.api: "openai"` → `"openai-completions"` (l'avvio del Gateway salta anche i provider il cui `api` è impostato su un valore enum futuro o sconosciuto invece di fallire in modo chiuso)
- `models.providers.*.api: "openai"` legacy → `"openai-completions"` (l'avvio del Gateway salta anche i provider il cui `api` è impostato su un valore enum futuro o sconosciuto invece di fallire in modo chiuso)
Gli avvisi di doctor includono anche indicazioni sull'account predefinito per i canali multi-account:
- Se sono configurate due o più voci `channels.<channel>.accounts` senza `channels.<channel>.defaultAccount` o `accounts.default`, doctor avvisa che il routing di fallback può scegliere un account inatteso.
- Se due o più voci `channels.<channel>.accounts` sono configurate senza `channels.<channel>.defaultAccount` o `accounts.default`, doctor avvisa che il routing di fallback può scegliere un account inatteso.
- Se `channels.<channel>.defaultAccount` è impostato su un ID account sconosciuto, doctor avvisa ed elenca gli ID account configurati.
</Accordion>
<Accordion title="2b. Override del provider OpenCode">
Se hai aggiunto manualmente `models.providers.opencode`, `opencode-zen` o `opencode-go`, questo sovrascrive il catalogo OpenCode integrato da `@mariozechner/pi-ai`. Questo può forzare i modelli sull'API sbagliata o azzerare i costi. Doctor avvisa così puoi rimuovere l'override e ripristinare il routing API per modello + i costi.
<Accordion title="2b. Override dei provider OpenCode">
Se hai aggiunto manualmente `models.providers.opencode`, `opencode-zen` o `opencode-go`, questo sostituisce il catalogo OpenCode integrato da `@mariozechner/pi-ai`. Ciò può forzare i modelli sull'API sbagliata o azzerare i costi. Doctor avvisa così puoi rimuovere l'override e ripristinare routing API e costi per modello.
</Accordion>
<Accordion title="2c. Migrazione del browser e preparazione a Chrome MCP">
Se la configurazione del browser punta ancora al percorso dell'estensione Chrome rimossa, doctor la normalizza al modello attuale di attach Chrome MCP locale all'host:
<Accordion title="2c. Migrazione del browser e prerequisiti per Chrome MCP">
Se la configurazione del browser punta ancora al percorso dell'estensione Chrome rimossa, doctor la normalizza al modello attuale di collegamento Chrome MCP host-local:
- `browser.profiles.*.driver: "extension"` diventa `"existing-session"`
- `browser.relayBindHost` viene rimosso
Doctor controlla anche il percorso Chrome MCP locale all'host quando usi `defaultProfile: "user"` o un profilo `existing-session` configurato:
Doctor verifica anche il percorso Chrome MCP host-local quando usi `defaultProfile: "user"` o un profilo `existing-session` configurato:
- verifica se Google Chrome è installato sullo stesso host per i profili di connessione automatica predefiniti
- controlla se Google Chrome è installato sullo stesso host per i profili di connessione automatica predefiniti
- controlla la versione di Chrome rilevata e avvisa quando è inferiore a Chrome 144
- ti ricorda di abilitare il debugging remoto nella pagina di ispezione del browser (per esempio `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` o `edge://inspect/#remote-debugging`)
- ricorda di abilitare il debug remoto nella pagina di ispezione del browser (ad esempio `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` o `edge://inspect/#remote-debugging`)
Doctor non può abilitare l'impostazione lato Chrome per te. Chrome MCP locale all'host richiede comunque:
Doctor non può abilitare l'impostazione lato Chrome per te. Chrome MCP host-local richiede comunque:
- un browser basato su Chromium 144+ sull'host del gateway/nodo
- un browser basato su Chromium 144+ sull'host gateway/node
- il browser in esecuzione localmente
- debugging remoto abilitato in quel browser
- approvazione del primo prompt di consenso all'attach nel browser
- debug remoto abilitato in quel browser
- approvazione del primo prompt di consenso al collegamento nel browser
La preparazione qui riguarda solo i prerequisiti dell'attach locale. Existing-session mantiene i limiti attuali delle route Chrome MCP; route avanzate come `responsebody`, esportazione PDF, intercettazione dei download e azioni batch richiedono ancora un browser gestito o un profilo CDP raw.
La prontezza qui riguarda solo i prerequisiti di collegamento locale. Existing-session mantiene gli attuali limiti di route di Chrome MCP; route avanzate come `responsebody`, esportazione PDF, intercettazione dei download e azioni batch richiedono ancora un browser gestito o un profilo CDP grezzo.
Questo controllo **non** si applica a Docker, sandbox, remote-browser o altri flussi headless. Questi continuano a usare CDP raw.
Questo controllo **non** si applica a Docker, sandbox, remote-browser o altri flussi headless. Questi continuano a usare CDP grezzo.
</Accordion>
<Accordion title="2d. Prerequisiti TLS OAuth">
Quando è configurato un profilo OAuth OpenAI Codex, doctor interroga l'endpoint di autorizzazione OpenAI per verificare che lo stack TLS locale Node/OpenSSL possa validare la catena di certificati. Se il probe fallisce con un errore di certificato (per esempio `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, certificato scaduto o certificato autofirmato), doctor stampa indicazioni di correzione specifiche per piattaforma. Su macOS con un Node Homebrew, la correzione è di solito `brew postinstall ca-certificates`. Con `--deep`, il probe viene eseguito anche se il gateway è integro.
<Accordion title="2d. Prerequisiti TLS di OAuth">
Quando è configurato un profilo OAuth OpenAI Codex, doctor interroga l'endpoint di autorizzazione OpenAI per verificare che lo stack TLS locale Node/OpenSSL possa convalidare la catena di certificati. Se il probe fallisce con un errore di certificato (ad esempio `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, certificato scaduto o certificato autofirmato), doctor stampa indicazioni di correzione specifiche per piattaforma. Su macOS con Node installato tramite Homebrew, la correzione è di solito `brew postinstall ca-certificates`. Con `--deep`, il probe viene eseguito anche se il gateway è integro.
</Accordion>
<Accordion title="2e. Override del provider OAuth Codex">
Se in precedenza hai aggiunto impostazioni legacy di trasporto OpenAI sotto `models.providers.openai-codex`, possono oscurare il percorso integrato del provider OAuth Codex che le versioni più recenti usano automaticamente. Doctor avvisa quando vede quelle vecchie impostazioni di trasporto insieme a OAuth Codex, così puoi rimuovere o riscrivere l'override di trasporto obsoleto e recuperare il routing/fallback integrato. Proxy personalizzati e override solo di header sono ancora supportati e non attivano questo avviso.
<Accordion title="2e. Override dei provider Codex OAuth">
Se in precedenza hai aggiunto impostazioni di trasporto OpenAI legacy sotto `models.providers.openai-codex`, queste possono oscurare il percorso del provider Codex OAuth integrato che le versioni più recenti usano automaticamente. Doctor avvisa quando vede quelle vecchie impostazioni di trasporto insieme a Codex OAuth, così puoi rimuovere o riscrivere l'override di trasporto obsoleto e recuperare il comportamento integrato di routing/fallback. Proxy personalizzati e override solo di header sono ancora supportati e non attivano questo avviso.
</Accordion>
<Accordion title="2f. Avvisi sulle route del Plugin Codex">
Quando il Plugin Codex in bundle è abilitato, doctor controlla anche se i riferimenti al modello primario `openai-codex/*` si risolvono ancora tramite il runner PI predefinito. Questa combinazione è valida quando vuoi l'autenticazione OAuth/abbonamento Codex tramite PI, ma è facile confonderla con l'harness nativo del server applicativo Codex. Doctor avvisa e indica la forma esplicita del server applicativo: `openai/*` più `agentRuntime.id: "codex"` o `OPENCLAW_AGENT_RUNTIME=codex`.
Quando il Plugin Codex incluso è abilitato, doctor controlla anche se i riferimenti al modello primario `openai-codex/*` si risolvono ancora tramite il runner PI predefinito. Questa combinazione è valida quando vuoi autenticazione OAuth/abbonamento Codex tramite PI, ma è facile confonderla con l'harness nativo app-server di Codex. Doctor avvisa e indica la forma esplicita app-server: `openai/*` più `agentRuntime.id: "codex"` o `OPENCLAW_AGENT_RUNTIME=codex`.
Doctor non ripara automaticamente questo caso perché entrambe le route sono valide:
Doctor non ripara automaticamente questa situazione perché entrambe le route sono valide:
- `openai-codex/*` + PI significa "usa l'autenticazione OAuth/abbonamento Codex tramite il normale runner OpenClaw."
- `openai/*` + `agentRuntime.id: "codex"` significa "esegui il turn incorporato tramite il server applicativo nativo Codex."
- `/codex ...` significa "controlla o associa una conversazione Codex nativa dalla chat."
- `/acp ...` o `runtime: "acp"` significa "usa l'adattatore ACP/acpx esterno."
- `openai-codex/*` + PI significa "usa l'autenticazione OAuth/abbonamento Codex tramite il runner OpenClaw normale."
- `openai/*` + `agentRuntime.id: "codex"` significa "esegui il turno incorporato tramite app-server nativo di Codex."
- `/codex ...` significa "controlla o collega una conversazione Codex nativa dalla chat."
- `/acp ...` o `runtime: "acp"` significa "usa l'adapter ACP/acpx esterno."
Se appare l'avviso, scegli la route che intendevi usare e modifica manualmente la configurazione. Mantieni l'avviso invariato quando PI Codex OAuth è intenzionale.
Se compare l'avviso, scegli la route prevista e modifica manualmente la configurazione. Mantieni l'avviso invariato quando Codex OAuth tramite PI è intenzionale.
</Accordion>
<Accordion title="2g. Pulizia delle route di sessione">
Doctor scansiona anche lo store delle sessioni attive alla ricerca di stato di route obsoleto creato automaticamente dopo che sposti il modello o runtime predefinito/di fallback configurato lontano da una route posseduta da un Plugin, come Codex.
Doctor analizza anche lo store delle sessioni attive alla ricerca di stato di route obsoleto creato automaticamente dopo che hai spostato il modello o runtime predefinito/fallback configurato da una route posseduta da un Plugin, come Codex, a un'altra route.
`openclaw doctor --fix` può cancellare lo stato obsoleto creato automaticamente, come pin di modello `modelOverrideSource: "auto"`, metadati del modello di runtime, ID harness fissati, associazioni di sessione CLI e override automatici del profilo di autenticazione quando la route proprietaria non è più configurata. Le scelte esplicite dell'utente o legacy del modello di sessione vengono segnalate per revisione manuale e lasciate intatte; cambiale con `/model ...`, `/new` oppure reimposta la sessione quando quella route non è più prevista.
`openclaw doctor --fix` può cancellare stato obsoleto creato automaticamente, come pin di modello `modelOverrideSource: "auto"`, metadati del modello runtime, ID harness fissati, binding di sessione CLI e override automatici di auth-profile quando la route proprietaria non è più configurata. Le scelte esplicite dell'utente o dei modelli di sessione legacy vengono segnalate per revisione manuale e lasciate intatte; cambiale con `/model ...`, `/new` oppure reimposta la sessione quando quella route non è più prevista.
</Accordion>
<Accordion title="3. Migrazioni dello stato legacy (layout su disco)">
Doctor può migrare i layout più vecchi su disco nella struttura attuale:
Doctor può migrare layout su disco più vecchi nella struttura attuale:
- Store sessioni + trascrizioni:
- Store delle sessioni + transcript:
- da `~/.openclaw/sessions/` a `~/.openclaw/agents/<agentId>/sessions/`
- Directory agente:
- da `~/.openclaw/agent/` a `~/.openclaw/agents/<agentId>/agent/`
- Stato auth WhatsApp (Baileys):
- da legacy `~/.openclaw/credentials/*.json` (eccetto `oauth.json`)
- Stato di autenticazione WhatsApp (Baileys):
- da `~/.openclaw/credentials/*.json` legacy (eccetto `oauth.json`)
- a `~/.openclaw/credentials/whatsapp/<accountId>/...` (ID account predefinito: `default`)
Queste migrazioni sono best-effort e idempotenti; doctor emetterà avvisi quando lascia cartelle legacy come backup. Anche il Gateway/CLI migra automaticamente all'avvio le sessioni legacy + la directory agente, così cronologia/auth/modelli finiscono nel percorso per agente senza un'esecuzione manuale di doctor. L'auth WhatsApp viene migrata intenzionalmente solo tramite `openclaw doctor`. La normalizzazione del provider/mappa provider di Talk ora confronta per uguaglianza strutturale, quindi le differenze solo nell'ordine delle chiavi non attivano più modifiche no-op ripetute di `doctor --fix`.
Queste migrazioni sono best-effort e idempotenti; doctor emetterà avvisi quando lascia cartelle legacy come backup. Anche Gateway/CLI migra automaticamente lo store delle sessioni legacy + la directory agente all'avvio, così cronologia/auth/modelli finiscono nel percorso per agente senza un'esecuzione manuale di doctor. L'autenticazione WhatsApp viene intenzionalmente migrata solo tramite `openclaw doctor`. La normalizzazione del provider/mappa-provider di Talk ora confronta per uguaglianza strutturale, quindi le differenze dovute solo all'ordine delle chiavi non attivano più modifiche no-op ripetute di `doctor --fix`.
</Accordion>
<Accordion title="3a. Migrazioni dei manifest Plugin legacy">
Doctor scansiona tutti i manifest dei Plugin installati alla ricerca di chiavi di capability di livello superiore deprecate (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Quando le trova, offre di spostarle nell'oggetto `contracts` e riscrivere il file manifest sul posto. Questa migrazione è idempotente; se la chiave `contracts` contiene già gli stessi valori, la chiave legacy viene rimossa senza duplicare i dati.
Doctor analizza tutti i manifest dei Plugin installati alla ricerca di chiavi di capacità di primo livello deprecate (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Quando le trova, propone di spostarle nell'oggetto `contracts` e riscrivere il file manifest in-place. Questa migrazione è idempotente; se la chiave `contracts` ha già gli stessi valori, la chiave legacy viene rimossa senza duplicare i dati.
</Accordion>
<Accordion title="3b. Migrazioni dello store Cron legacy">
Doctor controlla anche lo store dei job cron (`~/.openclaw/cron/jobs.json` per impostazione predefinita, oppure `cron.store` quando sovrascritto) per vecchie forme di job che lo scheduler accetta ancora per compatibilità.
Doctor controlla anche lo store dei job cron (`~/.openclaw/cron/jobs.json` per impostazione predefinita, o `cron.store` quando sovrascritto) alla ricerca di vecchie forme di job che lo scheduler accetta ancora per compatibilità.
Le pulizie Cron attuali includono:
- `jobId` → `id`
- `schedule.cron` → `schedule.expr`
- campi payload di livello superiore (`message`, `model`, `thinking`, ...) → `payload`
- campi delivery di livello superiore (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
- campi payload di primo livello (`message`, `model`, `thinking`, ...) → `payload`
- campi delivery di primo livello (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
- alias di delivery `provider` del payload → `delivery.channel` esplicito
- semplici job legacy di fallback Webhook `notify: true` → `delivery.mode="webhook"` esplicito con `delivery.to=cron.webhook`
- semplici job legacy di fallback webhook `notify: true` → `delivery.mode="webhook"` esplicito con `delivery.to=cron.webhook`
Doctor migra automaticamente i job `notify: true` solo quando può farlo senza cambiare comportamento. Se un job combina il fallback notify legacy con una modalità di delivery non webhook esistente, doctor avvisa e lascia quel job per la revisione manuale.
Doctor esegue la migrazione automatica dei job `notify: true` solo quando può farlo senza cambiare comportamento. Se un job combina il fallback notify legacy con una modalità di delivery non-webhook esistente, doctor avvisa e lascia quel job alla revisione manuale.
Su Linux, doctor avvisa anche quando il crontab dell'utente invoca ancora il vecchio `~/.openclaw/bin/ensure-whatsapp.sh`. Quello script locale all'host non è mantenuto dall'OpenClaw attuale e può scrivere falsi messaggi `Gateway inactive` in `~/.openclaw/logs/whatsapp-health.log` quando cron non riesce a raggiungere il bus utente systemd. Rimuovi la voce crontab obsoleta con `crontab -e`; usa `openclaw channels status --probe`, `openclaw doctor` e `openclaw gateway status` per i controlli di integrità attuali.
Su Linux, doctor avvisa anche quando la crontab dell'utente invoca ancora il vecchio `~/.openclaw/bin/ensure-whatsapp.sh`. Quello script locale dell'host non è mantenuto dall'attuale OpenClaw e può scrivere falsi messaggi `Gateway inactive` in `~/.openclaw/logs/whatsapp-health.log` quando cron non riesce a raggiungere il bus utente di systemd. Rimuovi la voce crontab obsoleta con `crontab -e`; usa `openclaw channels status --probe`, `openclaw doctor` e `openclaw gateway status` per i controlli di integrità attuali.
</Accordion>
<Accordion title="3c. Pulizia dei blocchi di sessione">
Doctor analizza ogni directory di sessione degli agenti alla ricerca di file di write-lock obsoleti — file rimasti dopo l'uscita anomala di una sessione. Per ogni file di lock trovato segnala: percorso, PID, se il PID è ancora attivo, età del lock e se è considerato obsoleto (PID morto o più vecchio di 30 minuti). In modalità `--fix` / `--repair` rimuove automaticamente i file di lock obsoleti; altrimenti stampa una nota e indica di rieseguire con `--fix`.
Doctor analizza ogni directory di sessione agente alla ricerca di file di blocco in scrittura obsoleti: file rimasti dopo l'uscita anomala di una sessione. Per ogni file di blocco trovato segnala: il percorso, il PID, se il PID è ancora attivo, l'età del blocco e se è considerato obsoleto (PID morto o più vecchio di 30 minuti). In modalità `--fix` / `--repair` rimuove automaticamente i file di blocco obsoleti; altrimenti stampa una nota e ti indica di rieseguirlo con `--fix`.
</Accordion>
<Accordion title="3d. Riparazione del ramo della trascrizione di sessione">
Doctor analizza i file JSONL delle sessioni degli agenti alla ricerca della forma di ramo duplicata creata dal bug di riscrittura della trascrizione dei prompt del 2026.4.24: un turno utente abbandonato con contesto runtime interno di OpenClaw più un elemento sibling attivo contenente lo stesso prompt utente visibile. In modalità `--fix` / `--repair`, doctor esegue il backup di ogni file interessato accanto all'originale e riscrive la trascrizione sul ramo attivo, così la cronologia del Gateway e i lettori di memoria non vedono più turni duplicati.
<Accordion title="3d. Riparazione dei rami delle trascrizioni di sessione">
Doctor analizza i file JSONL delle sessioni agente alla ricerca della forma di ramo duplicata creata dal bug di riscrittura delle trascrizioni dei prompt del 2026.4.24: un turno utente abbandonato con contesto di runtime interno di OpenClaw più un fratello attivo contenente lo stesso prompt utente visibile. In modalità `--fix` / `--repair`, doctor esegue il backup di ogni file interessato accanto all'originale e riscrive la trascrizione sul ramo attivo, così la cronologia del Gateway e i lettori di memoria non vedono più turni duplicati.
</Accordion>
<Accordion title="4. Controlli di integrità dello stato (persistenza della sessione, routing e sicurezza)">
<Accordion title="4. Controlli di integrità dello stato (persistenza della sessione, instradamento e sicurezza)">
La directory di stato è il tronco encefalico operativo. Se scompare, perdi sessioni, credenziali, log e configurazione (a meno che tu non abbia backup altrove).
Doctor controlla:
- **Directory di stato mancante**: avvisa della perdita catastrofica dello stato, chiede di ricreare la directory e ricorda che non può recuperare i dati mancanti.
- **Directory di stato mancante**: avvisa di una perdita di stato catastrofica, propone di ricreare la directory e ricorda che non può recuperare i dati mancanti.
- **Permessi della directory di stato**: verifica la scrivibilità; offre di riparare i permessi (ed emette un suggerimento `chown` quando rileva una mancata corrispondenza di proprietario/gruppo).
- **Directory di stato sincronizzata con cloud su macOS**: avvisa quando lo stato si risolve sotto iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) o `~/Library/CloudStorage/...` perché i percorsi basati su sincronizzazione possono causare I/O più lento e race di lock/sincronizzazione.
- **Directory di stato Linux su SD o eMMC**: avvisa quando lo stato si risolve in una sorgente di mount `mmcblk*`, perché l'I/O casuale basato su SD o eMMC può essere più lento e usurarsi più rapidamente durante le scritture di sessioni e credenziali.
- **Directory di sessione mancanti**: `sessions/` e la directory dell'archivio sessioni sono necessarie per persistere la cronologia ed evitare crash `ENOENT`.
- **Mancata corrispondenza della trascrizione**: avvisa quando le voci di sessione recenti hanno file di trascrizione mancanti.
- **Sessione principale "JSONL a 1 riga"**: segnala quando la trascrizione principale ha una sola riga (la cronologia non si sta accumulando).
- **Directory di stato sincronizzata con il cloud su macOS**: avvisa quando lo stato viene risolto sotto iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) o `~/Library/CloudStorage/...` perché i percorsi basati su sincronizzazione possono causare I/O più lento e race di blocco/sincronizzazione.
- **Directory di stato Linux su SD o eMMC**: avvisa quando lo stato viene risolto a una sorgente di mount `mmcblk*`, perché l'I/O casuale basato su SD o eMMC può essere più lento e usurarsi più rapidamente con le scritture di sessioni e credenziali.
- **Directory di sessione mancanti**: `sessions/` e la directory di archiviazione delle sessioni sono necessarie per persistere la cronologia ed evitare crash `ENOENT`.
- **Mancata corrispondenza della trascrizione**: avvisa quando voci di sessione recenti hanno file di trascrizione mancanti.
- **Sessione principale "JSONL a 1 riga"**: segnala quando la trascrizione principale ha una sola riga (la cronologia non si accumula).
- **Più directory di stato**: avvisa quando esistono più cartelle `~/.openclaw` in diverse directory home o quando `OPENCLAW_STATE_DIR` punta altrove (la cronologia può dividersi tra installazioni).
- **Promemoria modalità remota**: se `gateway.mode=remote`, doctor ricorda di eseguirlo sull'host remoto (lo stato risiede lì).
- **Permessi del file di configurazione**: avvisa se `~/.openclaw/openclaw.json` è leggibile dal gruppo/mondo e offre di restringerlo a `600`.
- **Promemoria modalità remota**: se `gateway.mode=remote`, doctor ti ricorda di eseguirlo sull'host remoto (lo stato si trova lì).
- **Permessi del file di configurazione**: avvisa se `~/.openclaw/openclaw.json` è leggibile dal gruppo o da tutti e offre di restringerlo a `600`.
</Accordion>
<Accordion title="5. Integrità dell'autenticazione dei modelli (scadenza OAuth)">
Doctor ispeziona i profili OAuth nell'archivio di autenticazione, avvisa quando i token stanno per scadere o sono scaduti e può aggiornarli quando è sicuro. Se il profilo OAuth/token Anthropic è obsoleto, suggerisce una chiave API Anthropic o il percorso del setup-token Anthropic. Le richieste di aggiornamento compaiono solo quando l'esecuzione è interattiva (TTY); `--non-interactive` salta i tentativi di aggiornamento.
<Accordion title="5. Integrità autenticazione modello (scadenza OAuth)">
Doctor ispeziona i profili OAuth nell'archivio auth, avvisa quando i token stanno per scadere o sono scaduti e può aggiornarli quando è sicuro. Se il profilo OAuth/token di Anthropic è obsoleto, suggerisce una chiave API Anthropic o il percorso setup-token di Anthropic. Le richieste di aggiornamento compaiono solo durante l'esecuzione interattiva (TTY); `--non-interactive` salta i tentativi di aggiornamento.
Quando un aggiornamento OAuth fallisce in modo permanente (per esempio `refresh_token_reused`, `invalid_grant` o un provider che richiede di accedere di nuovo), doctor segnala che è necessaria una nuova autenticazione e stampa il comando esatto `openclaw models auth login --provider ...` da eseguire.
Quando un aggiornamento OAuth fallisce in modo permanente (per esempio `refresh_token_reused`, `invalid_grant` o un provider che ti chiede di accedere di nuovo), doctor segnala che è necessaria una nuova autenticazione e stampa il comando esatto `openclaw models auth login --provider ...` da eseguire.
Doctor segnala anche i profili di autenticazione temporaneamente inutilizzabili a causa di:
Doctor segnala anche i profili auth temporaneamente inutilizzabili a causa di:
- brevi cooldown (limiti di frequenza/timeout/errori di autenticazione)
- brevi cooldown (limiti di frequenza/timeout/errori di auth)
- disabilitazioni più lunghe (errori di fatturazione/credito)
</Accordion>
<Accordion title="6. Convalida del modello degli hook">
Se `hooks.gmail.model` è impostato, doctor convalida il riferimento al modello rispetto al catalogo e all'allowlist e avvisa quando non può essere risolto o non è consentito.
<Accordion title="6. Validazione del modello degli hook">
Se `hooks.gmail.model` è impostato, doctor valida il riferimento del modello rispetto al catalogo e all'allowlist e avvisa quando non verrà risolto o non è consentito.
</Accordion>
<Accordion title="7. Riparazione dell'immagine sandbox">
Quando il sandboxing è abilitato, doctor controlla le immagini Docker e offre di creare o passare ai nomi legacy se l'immagine corrente manca.
Quando il sandboxing è abilitato, doctor controlla le immagini Docker e offre di crearle o di passare ai nomi legacy se l'immagine corrente manca.
</Accordion>
<Accordion title="7b. Pulizia dell'installazione dei Plugin">
Doctor rimuove lo stato legacy di staging delle dipendenze dei Plugin generato da OpenClaw in modalità `openclaw doctor --fix` / `openclaw doctor --repair`. Questo copre radici di dipendenze generate obsolete, vecchie directory di fase di installazione, residui locali al pacchetto provenienti dal precedente codice di riparazione delle dipendenze dei Plugin in bundle e copie npm gestite orfane o recuperate dei Plugin `@openclaw/*` in bundle che possono oscurare il manifest in bundle corrente.
Doctor rimuove lo stato legacy di staging delle dipendenze dei plugin generato da OpenClaw in modalità `openclaw doctor --fix` / `openclaw doctor --repair`. Questo copre root di dipendenze generate obsolete, vecchie directory di install-stage, residui locali ai pacchetti da codice precedente di riparazione delle dipendenze dei plugin inclusi, e copie npm gestite orfane o recuperate dei plugin `@openclaw/*` inclusi che possono oscurare il manifesto incluso attuale.
Doctor può anche reinstallare i Plugin scaricabili mancanti quando la configurazione li referenzia ma il registro locale dei Plugin non riesce a trovarli. Gli esempi includono `plugins.entries` materiali, impostazioni configurate di canale/provider/ricerca e runtime agenti configurati. Durante gli aggiornamenti dei pacchetti, doctor evita di eseguire la riparazione dei Plugin tramite package manager mentre il pacchetto core viene sostituito; esegui di nuovo `openclaw doctor --fix` dopo l'aggiornamento se un Plugin configurato ha ancora bisogno di recupero. L'avvio del Gateway e il ricaricamento della configurazione non eseguono package manager; le installazioni dei Plugin restano operazioni esplicite di doctor/install/update.
Doctor può anche reinstallare plugin scaricabili mancanti quando la configurazione li referenzia ma il registro plugin locale non riesce a trovarli. Gli esempi includono `plugins.entries` materiali, impostazioni di canale/provider/ricerca configurate e runtime agente configurati. Durante gli aggiornamenti di pacchetto, doctor evita di eseguire la riparazione dei plugin tramite package manager mentre il pacchetto core viene sostituito; esegui di nuovo `openclaw doctor --fix` dopo l'aggiornamento se un plugin configurato necessita ancora di recupero. L'avvio del Gateway e il ricaricamento della configurazione non eseguono package manager; le installazioni dei plugin restano lavoro esplicito di doctor/install/update.
</Accordion>
<Accordion title="8. Migrazioni dei servizi Gateway e suggerimenti di pulizia">
Doctor rileva i servizi Gateway legacy (launchd/systemd/schtasks) e offre di rimuoverli e installare il servizio OpenClaw usando la porta Gateway corrente. Può anche cercare servizi aggiuntivi simili al Gateway e stampare suggerimenti di pulizia. I servizi Gateway OpenClaw con nome profilo sono considerati di prima classe e non vengono segnalati come "extra".
Doctor rileva i servizi gateway legacy (launchd/systemd/schtasks) e offre di rimuoverli e installare il servizio OpenClaw usando la porta gateway corrente. Può anche cercare servizi aggiuntivi simili al gateway e stampare suggerimenti di pulizia. I servizi gateway OpenClaw con nome profilo sono considerati di prima classe e non vengono segnalati come "extra".
Su Linux, se il servizio Gateway a livello utente manca ma esiste un servizio Gateway OpenClaw a livello di sistema, doctor non installa automaticamente un secondo servizio a livello utente. Ispeziona con `openclaw gateway status --deep` o `openclaw doctor --deep`, poi rimuovi il duplicato o imposta `OPENCLAW_SERVICE_REPAIR_POLICY=external` quando un supervisore di sistema gestisce il ciclo di vita del Gateway.
Su Linux, se il servizio gateway a livello utente manca ma esiste un servizio gateway OpenClaw a livello di sistema, doctor non installa automaticamente un secondo servizio a livello utente. Ispeziona con `openclaw gateway status --deep` o `openclaw doctor --deep`, poi rimuovi il duplicato oppure imposta `OPENCLAW_SERVICE_REPAIR_POLICY=external` quando un supervisore di sistema possiede il ciclo di vita del gateway.
</Accordion>
<Accordion title="8b. Migrazione Startup Matrix">
Quando un account canale Matrix ha una migrazione di stato legacy in sospeso o utilizzabile, doctor (in modalità `--fix` / `--repair`) crea uno snapshot pre-migrazione e poi esegue i passaggi di migrazione best-effort: migrazione dello stato Matrix legacy e preparazione dello stato cifrato legacy. Entrambi i passaggi non sono fatali; gli errori vengono registrati e l'avvio continua. In modalità di sola lettura (`openclaw doctor` senza `--fix`) questo controllo viene saltato del tutto.
Quando un account canale Matrix ha una migrazione di stato legacy in sospeso o azionabile, doctor (in modalità `--fix` / `--repair`) crea uno snapshot pre-migrazione e poi esegue i passaggi di migrazione best-effort: migrazione dello stato Matrix legacy e preparazione dello stato cifrato legacy. Entrambi i passaggi non sono fatali; gli errori vengono registrati nei log e l'avvio continua. In modalità sola lettura (`openclaw doctor` senza `--fix`) questo controllo viene saltato completamente.
</Accordion>
<Accordion title="8c. Associazione dei dispositivi e deriva dell'autenticazione">
<Accordion title="8c. Associazione dispositivi e deriva auth">
Doctor ora ispeziona lo stato di associazione dei dispositivi come parte del normale passaggio di integrità.
Cosa segnala:
- richieste di prima associazione in sospeso
- upgrade di ruolo in sospeso per dispositivi già associati
- upgrade di ambito in sospeso per dispositivi già associati
- riparazioni di mancata corrispondenza della chiave pubblica dove l'id dispositivo corrisponde ancora ma l'identità del dispositivo non corrisponde più al record approvato
- aggiornamenti di ruolo in sospeso per dispositivi già associati
- aggiornamenti di ambito in sospeso per dispositivi già associati
- riparazioni di mancata corrispondenza della chiave pubblica in cui l'id dispositivo corrisponde ancora ma l'identità del dispositivo non corrisponde più al record approvato
- record associati senza un token attivo per un ruolo approvato
- token associati i cui ambiti derivano fuori dalla baseline di associazione approvata
- voci locali memorizzate nella cache del token dispositivo per la macchina corrente che precedono una rotazione del token lato Gateway o contengono metadati di ambito obsoleti
- voci token dispositivo memorizzate nella cache locale per la macchina corrente che precedono una rotazione del token lato gateway o portano metadati di ambito obsoleti
Doctor non approva automaticamente le richieste di associazione né ruota automaticamente i token dei dispositivi. Stampa invece i passaggi successivi esatti:
Doctor non approva automaticamente le richieste di associazione né ruota automaticamente i token dispositivo. Stampa invece i passaggi successivi esatti:
- ispeziona le richieste in sospeso con `openclaw devices list`
- approva la richiesta esatta con `openclaw devices approve <requestId>`
- ruota un token fresco con `openclaw devices rotate --device <deviceId> --role <role>`
- rimuovi e riapprova un record obsoleto con `openclaw devices remove <deviceId>`
Questo chiude il buco comune "già associato ma riceve ancora richiesta di associazione": doctor ora distingue la prima associazione dagli upgrade di ruolo/ambito in sospeso e dalla deriva di token/identità dispositivo obsoleta.
Questo chiude il comune buco "già associato ma riceve ancora richiesta di associazione": doctor ora distingue la prima associazione dagli aggiornamenti di ruolo/ambito in sospeso e dalla deriva di token/identità dispositivo obsoleti.
</Accordion>
<Accordion title="9. Avvisi di sicurezza">
Doctor emette avvisi quando un provider è aperto ai DM senza un'allowlist, o quando una policy è configurata in modo pericoloso.
Doctor emette avvisi quando un provider è aperto ai DM senza un'allowlist, oppure quando una policy è configurata in modo pericoloso.
</Accordion>
<Accordion title="10. systemd linger (Linux)">
Se è in esecuzione come servizio utente systemd, doctor assicura che linger sia abilitato così il gateway resta attivo dopo il logout.
Se eseguito come servizio utente systemd, doctor assicura che il linger sia abilitato così il gateway resta attivo dopo il logout.
</Accordion>
<Accordion title="11. Stato dell'area di lavoro (Skills, Plugin e directory legacy)">
Doctor stampa un riepilogo dello stato dell'area di lavoro per l'agente predefinito:
<Accordion title="11. Stato del workspace (skills, plugin e directory legacy)">
Doctor stampa un riepilogo dello stato del workspace per l'agente predefinito:
- **Stato delle Skills**: conta le Skill idonee, con requisiti mancanti e bloccate dall'allowlist.
- **Directory legacy dell'area di lavoro**: avvisa quando `~/openclaw` o altre directory legacy dell'area di lavoro esistono accanto all'area di lavoro corrente.
- **Stato dei Plugin**: conta i Plugin abilitati/disabilitati/con errore; elenca gli ID Plugin per eventuali errori; segnala le capacità dei Plugin del bundle.
- **Avvisi di compatibilità dei Plugin**: segnala i Plugin che hanno problemi di compatibilità con il runtime corrente.
- **Diagnostica dei Plugin**: espone eventuali avvisi o errori emessi dal registro dei Plugin in fase di caricamento.
- **Stato Skills**: conta skill idonee, con requisiti mancanti e bloccate dall'allowlist.
- **Directory workspace legacy**: avvisa quando `~/openclaw` o altre directory workspace legacy esistono accanto al workspace corrente.
- **Stato Plugin**: conta plugin abilitati/disabilitati/con errori; elenca gli ID plugin per eventuali errori; segnala le capacità dei plugin del bundle.
- **Avvisi di compatibilità Plugin**: segnala plugin che hanno problemi di compatibilità con il runtime corrente.
- **Diagnostica Plugin**: espone eventuali avvisi o errori in fase di caricamento emessi dal registro plugin.
</Accordion>
<Accordion title="11b. Dimensione del file di bootstrap">
Doctor controlla se i file di bootstrap dell'area di lavoro (per esempio `AGENTS.md`, `CLAUDE.md` o altri file di contesto iniettati) sono vicini o oltre il budget di caratteri configurato. Segnala per ogni file i conteggi di caratteri grezzi rispetto a quelli iniettati, la percentuale di troncamento, la causa del troncamento (`max/file` o `max/total`) e i caratteri iniettati totali come frazione del budget totale. Quando i file sono troncati o vicini al limite, doctor stampa suggerimenti per regolare `agents.defaults.bootstrapMaxChars` e `agents.defaults.bootstrapTotalMaxChars`.
Doctor controlla se i file di bootstrap del workspace (per esempio `AGENTS.md`, `CLAUDE.md` o altri file di contesto iniettati) sono vicini o oltre il budget di caratteri configurato. Segnala per ogni file il conteggio di caratteri grezzi rispetto a quelli iniettati, la percentuale di troncamento, la causa del troncamento (`max/file` o `max/total`) e il totale di caratteri iniettati come frazione del budget totale. Quando i file sono troncati o vicini al limite, doctor stampa suggerimenti per regolare `agents.defaults.bootstrapMaxChars` e `agents.defaults.bootstrapTotalMaxChars`.
</Accordion>
<Accordion title="11d. Pulizia dei Plugin canale obsoleti">
Quando `openclaw doctor --fix` rimuove un Plugin canale mancante, rimuove anche la configurazione pendente con ambito canale che referenziava quel Plugin: voci `channels.<id>`, target Heartbeat che nominavano il canale e override `agents.*.models["<channel>/*"]`. Questo impedisce cicli di avvio del Gateway in cui il runtime del canale è sparito ma la configurazione chiede ancora al gateway di associarsi a esso.
<Accordion title="11d. Pulizia dei plugin canale obsoleti">
Quando `openclaw doctor --fix` rimuove un plugin canale mancante, rimuove anche la configurazione pendente con ambito canale che referenziava quel plugin: voci `channels.<id>`, destinazioni Heartbeat che nominavano il canale e override `agents.*.models["<channel>/*"]`. Questo impedisce cicli di avvio del Gateway in cui il runtime canale è sparito ma la configurazione chiede ancora al gateway di collegarsi a esso.
</Accordion>
<Accordion title="11c. Completamento shell">
<Accordion title="11c. Completamento della shell">
Doctor controlla se il completamento con tab è installato per la shell corrente (zsh, bash, fish o PowerShell):
- Se il profilo della shell usa un pattern di completamento dinamico lento (`source <(openclaw completion ...)`), doctor lo aggiorna alla variante più veloce con file in cache.
- Se il profilo shell usa un pattern di completamento dinamico lento (`source <(openclaw completion ...)`), doctor lo aggiorna alla variante più veloce con file in cache.
- Se il completamento è configurato nel profilo ma il file di cache manca, doctor rigenera automaticamente la cache.
- Se non è configurato alcun completamento, doctor chiede di installarlo (solo modalità interattiva; saltato con `--non-interactive`).
- Se non è configurato alcun completamento, doctor propone di installarlo (solo modalità interattiva; saltato con `--non-interactive`).
Esegui `openclaw completion --write-state` per rigenerare manualmente la cache.
</Accordion>
<Accordion title="12. Controlli di autenticazione Gateway (token locale)">
Doctor controlla la predisposizione dell'autenticazione con token Gateway locale.
<Accordion title="12. Controlli auth del Gateway (token locale)">
Doctor controlla la prontezza dell'autenticazione con token gateway locale.
- Se la modalità token richiede un token e non esiste alcuna sorgente di token, doctor offre di generarne uno.
- Se la modalità token richiede un token e non esiste alcuna sorgente token, doctor offre di generarne uno.
- Se `gateway.auth.token` è gestito da SecretRef ma non disponibile, doctor avvisa e non lo sovrascrive con testo in chiaro.
- `openclaw doctor --generate-gateway-token` forza la generazione solo quando non è configurato alcun SecretRef di token.
- `openclaw doctor --generate-gateway-token` forza la generazione solo quando non è configurato alcun SecretRef del token.
</Accordion>
<Accordion title="12b. Riparazioni di sola lettura consapevoli di SecretRef">
Alcuni flussi di riparazione devono ispezionare le credenziali configurate senza indebolire il comportamento fail-fast del runtime.
Alcuni flussi di riparazione devono ispezionare credenziali configurate senza indebolire il comportamento fail-fast del runtime.
- `openclaw doctor --fix` ora usa lo stesso modello di riepilogo SecretRef di sola lettura dei comandi della famiglia status per riparazioni mirate della configurazione.
- `openclaw doctor --fix` ora usa lo stesso modello di riepilogo SecretRef in sola lettura dei comandi della famiglia status per riparazioni mirate della configurazione.
- Esempio: la riparazione di Telegram `allowFrom` / `groupAllowFrom` `@username` prova a usare le credenziali del bot configurate quando disponibili.
- Se il token del bot Telegram è configurato tramite SecretRef ma non è disponibile nel percorso del comando corrente, doctor segnala che la credenziale è configurata ma non disponibile e salta la risoluzione automatica invece di arrestarsi in modo anomalo o segnalare erroneamente il token come mancante.
</Accordion>
<Accordion title="13. Controllo di integrità del Gateway + riavvio">
Doctor esegue un controllo di integrità e propone di riavviare il gateway quando sembra non integro.
Doctor esegue un controllo di integrità e offre di riavviare il gateway quando sembra non essere integro.
</Accordion>
<Accordion title="13b. Prontezza della ricerca in memoria">
Doctor verifica se il provider di embedding per la ricerca in memoria configurato è pronto per l'agente predefinito. Il comportamento dipende dal backend e dal provider configurati:
- **Backend QMD**: verifica se il binario `qmd` è disponibile e avviabile. In caso contrario, stampa indicazioni per la correzione che includono il pacchetto npm e un'opzione di percorso manuale del binario.
- **Provider locale esplicito**: controlla la presenza di un file modello locale o di un URL modello remoto/scaricabile riconosciuto. Se manca, suggerisce di passare a un provider remoto.
- **Provider remoto esplicito** (`openai`, `voyage`, ecc.): verifica che una chiave API sia presente nell'ambiente o nell'archivio di autenticazione. Stampa suggerimenti di correzione praticabili se manca.
- **Backend QMD**: verifica se il binario `qmd` è disponibile e avviabile. In caso contrario, stampa indicazioni di correzione che includono il pacchetto npm e un'opzione per il percorso manuale del binario.
- **Provider locale esplicito**: controlla la presenza di un file di modello locale o di un URL di modello remoto/scaricabile riconosciuto. Se manca, suggerisce di passare a un provider remoto.
- **Provider remoto esplicito** (`openai`, `voyage`, ecc.): verifica che una chiave API sia presente nell'ambiente o nell'archivio di autenticazione. Stampa suggerimenti di correzione attuabili se manca.
- **Provider automatico**: controlla prima la disponibilità del modello locale, poi prova ogni provider remoto nell'ordine di selezione automatica.
Quando è disponibile un risultato di probe del gateway nella cache (il gateway era integro al momento del controllo), doctor confronta il risultato con la configurazione visibile dalla CLI e segnala eventuali discrepanze. Doctor non avvia un nuovo ping di embedding nel percorso predefinito; usa il comando di stato memoria approfondito quando vuoi un controllo live del provider.
Quando è disponibile un risultato di probe del gateway memorizzato nella cache (il gateway era integro al momento del controllo), doctor incrocia il suo risultato con la configurazione visibile dalla CLI e segnala eventuali discrepanze. Doctor non avvia un nuovo ping di embedding nel percorso predefinito; usa il comando di stato memoria approfondito quando vuoi un controllo live del provider.
Usa `openclaw memory status --deep` per verificare la prontezza degli embedding a runtime.
</Accordion>
<Accordion title="14. Avvisi di stato dei canali">
<Accordion title="14. Avvisi sullo stato dei canali">
Se il gateway è integro, doctor esegue un probe dello stato dei canali e segnala avvisi con correzioni suggerite.
</Accordion>
<Accordion title="15. Audit + riparazione della configurazione supervisor">
Doctor controlla la configurazione supervisor installata (launchd/systemd/schtasks) per impostazioni predefinite mancanti o obsolete (ad es. dipendenze systemd da network-online e ritardo di riavvio). Quando trova una mancata corrispondenza, consiglia un aggiornamento e può riscrivere il file di servizio/task con le impostazioni predefinite correnti.
<Accordion title="15. Audit + riparazione della configurazione del supervisor">
Doctor controlla la configurazione del supervisor installata (launchd/systemd/schtasks) per impostazioni predefinite mancanti o obsolete (ad esempio dipendenze systemd da network-online e ritardo di riavvio). Quando trova una mancata corrispondenza, consiglia un aggiornamento e può riscrivere il file di servizio/task con le impostazioni predefinite correnti.
Note:
- `openclaw doctor` chiede conferma prima di riscrivere la configurazione supervisor.
- `openclaw doctor --yes` accetta le richieste di riparazione predefinite.
- `openclaw doctor --repair` applica le correzioni consigliate senza richieste di conferma.
- `openclaw doctor --repair --force` sovrascrive le configurazioni supervisor personalizzate.
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` mantiene doctor in sola lettura per il ciclo di vita del servizio gateway. Segnala comunque l'integrità del servizio ed esegue riparazioni non di servizio, ma salta installazione/avvio/riavvio/bootstrap del servizio, riscritture della configurazione supervisor e pulizia dei servizi legacy perché un supervisor esterno possiede quel ciclo di vita.
- Su Linux, doctor non riscrive i metadati di comando/entrypoint mentre l'unità systemd gateway corrispondente è attiva. Ignora inoltre unità extra inattive simili al gateway e non legacy durante la scansione dei servizi duplicati, così i file di servizio complementari non creano rumore di pulizia.
- Se l'autenticazione tramite token richiede un token e `gateway.auth.token` è gestito da SecretRef, l'installazione/riparazione del servizio doctor valida la SecretRef ma non persiste valori del token in testo in chiaro risolti nei metadati dell'ambiente del servizio supervisor.
- Doctor rileva valori di ambiente del servizio gestiti basati su `.env`/SecretRef che installazioni meno recenti di LaunchAgent, systemd o Windows Scheduled Task incorporavano inline e riscrive i metadati del servizio in modo che quei valori vengano caricati dalla sorgente runtime invece che dalla definizione supervisor.
- `openclaw doctor` chiede conferma prima di riscrivere la configurazione del supervisor.
- `openclaw doctor --yes` accetta i prompt di riparazione predefiniti.
- `openclaw doctor --repair` applica le correzioni consigliate senza prompt.
- `openclaw doctor --repair --force` sovrascrive le configurazioni personalizzate del supervisor.
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` mantiene doctor in sola lettura per il ciclo di vita del servizio gateway. Segnala comunque l'integrità del servizio ed esegue riparazioni non di servizio, ma salta installazione/avvio/riavvio/bootstrap del servizio, riscritture della configurazione del supervisor e pulizia dei servizi legacy perché un supervisor esterno possiede quel ciclo di vita.
- Su Linux, doctor non riscrive i metadati di comando/entrypoint mentre l'unità gateway systemd corrispondente è attiva. Ignora inoltre unità gateway-like extra inattive non legacy durante la scansione dei servizi duplicati, così i file di servizio companion non creano rumore di pulizia.
- Se l'autenticazione token richiede un token e `gateway.auth.token` è gestito da SecretRef, l'installazione/riparazione del servizio doctor convalida il SecretRef ma non persiste i valori del token in chiaro risolti nei metadati dell'ambiente del servizio supervisor.
- Doctor rileva valori di ambiente del servizio gestiti basati su `.env`/SecretRef che installazioni precedenti di LaunchAgent, systemd o Attività pianificate di Windows avevano incorporato inline e riscrive i metadati del servizio in modo che quei valori vengano caricati dalla sorgente runtime invece che dalla definizione del supervisor.
- Doctor rileva quando il comando del servizio fissa ancora una vecchia `--port` dopo modifiche a `gateway.port` e riscrive i metadati del servizio sulla porta corrente.
- Se l'autenticazione tramite token richiede un token e la SecretRef del token configurata non è risolta, doctor blocca il percorso di installazione/riparazione con indicazioni praticabili.
- Se l'autenticazione token richiede un token e il SecretRef del token configurato non è risolto, doctor blocca il percorso di installazione/riparazione con indicazioni attuabili.
- Se sia `gateway.auth.token` sia `gateway.auth.password` sono configurati e `gateway.auth.mode` non è impostato, doctor blocca installazione/riparazione finché la modalità non viene impostata esplicitamente.
- Per le unità user-systemd Linux, i controlli di divergenza del token di doctor ora includono sia sorgenti `Environment=` sia `EnvironmentFile=` quando confrontano i metadati di autenticazione del servizio.
- Le riparazioni del servizio doctor rifiutano di riscrivere, arrestare o riavviare un servizio gateway da un binario OpenClaw meno recente quando la configurazione è stata scritta l'ultima volta da una versione più recente. Vedi [Risoluzione dei problemi del Gateway](/it/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
- Per le unità user-systemd Linux, i controlli di drift del token di doctor ora includono sia le sorgenti `Environment=` sia `EnvironmentFile=` quando confrontano i metadati di autenticazione del servizio.
- Le riparazioni del servizio doctor rifiutano di riscrivere, arrestare o riavviare un servizio gateway da un binario OpenClaw precedente quando la configurazione è stata scritta l'ultima volta da una versione più recente. Vedi [Risoluzione dei problemi del Gateway](/it/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
- Puoi sempre forzare una riscrittura completa tramite `openclaw gateway install --force`.
</Accordion>
<Accordion title="16. Diagnostica runtime + porta del Gateway">
Doctor ispeziona il runtime del servizio (PID, ultimo stato di uscita) e avvisa quando il servizio è installato ma non è effettivamente in esecuzione. Controlla anche collisioni di porta sulla porta del gateway (predefinita `18789`) e segnala cause probabili (gateway già in esecuzione, tunnel SSH).
<Accordion title="16. Diagnostica del runtime del Gateway + porta">
Doctor ispeziona il runtime del servizio (PID, ultimo stato di uscita) e avvisa quando il servizio è installato ma non è effettivamente in esecuzione. Controlla inoltre le collisioni di porta sulla porta del gateway (predefinita `18789`) e segnala le cause probabili (gateway già in esecuzione, tunnel SSH).
</Accordion>
<Accordion title="17. Best practice runtime del Gateway">
Doctor avvisa quando il servizio gateway viene eseguito su Bun o su un percorso Node gestito da version manager (`nvm`, `fnm`, `volta`, `asdf`, ecc.). I canali WhatsApp + Telegram richiedono Node, e i percorsi dei version manager possono rompersi dopo gli aggiornamenti perché il servizio non carica l'inizializzazione della shell. Doctor propone di migrare a un'installazione Node di sistema quando disponibile (Homebrew/apt/choco).
<Accordion title="17. Buone pratiche per il runtime del Gateway">
Doctor avvisa quando il servizio gateway viene eseguito su Bun o su un percorso Node gestito da versione (`nvm`, `fnm`, `volta`, `asdf`, ecc.). I canali WhatsApp + Telegram richiedono Node, e i percorsi dei gestori di versione possono rompersi dopo gli aggiornamenti perché il servizio non carica l'inizializzazione della shell. Doctor offre di migrare a un'installazione Node di sistema quando disponibile (Homebrew/apt/choco).
I LaunchAgent macOS installati o riparati di recente usano un PATH di sistema canonico (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) invece di copiare il PATH della shell interattiva, così Volta, asdf, fnm, pnpm e altre directory dei version manager non cambiano quale Node viene risolto dai processi figlio. I servizi Linux mantengono comunque radici di ambiente esplicite (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) e directory user-bin stabili, ma le directory fallback dei version manager stimate vengono scritte nel PATH del servizio solo quando quelle directory esistono su disco.
I LaunchAgent macOS appena installati o riparati usano un PATH di sistema canonico (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) invece di copiare il PATH della shell interattiva, quindi Volta, asdf, fnm, pnpm e altre directory dei gestori di versione non cambiano quale Node viene risolto dai processi figli. I servizi Linux mantengono ancora root di ambiente esplicite (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) e directory user-bin stabili, ma le directory di fallback dei gestori di versione dedotte vengono scritte nel PATH del servizio solo quando quelle directory esistono su disco.
</Accordion>
<Accordion title="18. Scrittura della configurazione + metadati wizard">
Doctor persiste eventuali modifiche alla configurazione e marca i metadati del wizard per registrare l'esecuzione di doctor.
<Accordion title="18. Scrittura della configurazione + metadati della procedura guidata">
Doctor persiste eventuali modifiche alla configurazione e marca i metadati della procedura guidata per registrare l'esecuzione di doctor.
</Accordion>
<Accordion title="19. Suggerimenti per workspace (backup + sistema di memoria)">
Doctor suggerisce un sistema di memoria del workspace quando manca e stampa un suggerimento di backup se il workspace non è già sotto git.
<Accordion title="19. Suggerimenti per lo spazio di lavoro (backup + sistema di memoria)">
Doctor suggerisce un sistema di memoria dello spazio di lavoro quando manca e stampa un suggerimento di backup se lo spazio di lavoro non è già sotto git.
Vedi [/concepts/agent-workspace](/it/concepts/agent-workspace) per una guida completa alla struttura del workspace e al backup git (GitHub o GitLab privato consigliato).
Vedi [/concepts/agent-workspace](/it/concepts/agent-workspace) per una guida completa alla struttura dello spazio di lavoro e al backup git (GitHub o GitLab privato consigliato).
</Accordion>
</AccordionGroup>

294
docs/it/install/docker.md
View File

@ -1,46 +1,46 @@
---
read_when:
- Vuoi un Gateway containerizzato invece delle installazioni locali
- Vuoi un Gateway containerizzato invece di installazioni locali
- Stai convalidando il flusso Docker
summary: Configurazione e procedura introduttiva opzionali basate su Docker per OpenClaw
summary: Configurazione e onboarding opzionali basati su Docker per OpenClaw
title: Docker
x-i18n:
generated_at: "2026-05-02T20:47:24Z"
generated_at: "2026-05-05T08:26:22Z"
model: gpt-5.5
provider: openai
source_hash: 5e57659c89a0b207b4b331752e7faaa814fe1f0043dad97043e95e460286c551
source_hash: f57db2ec12f1a1fd681ec90cc43b2c945755a9240f571de46688777e957f1b8e
source_path: install/docker.md
workflow: 16
---
Docker è **facoltativo**. Usalo solo se vuoi un Gateway containerizzato o validare il flusso Docker.
Docker è **opzionale**. Usalo solo se vuoi un Gateway containerizzato o convalidare il flusso Docker.
## Docker fa al caso mio?
## Docker fa per me?
- **Sì**: vuoi un ambiente Gateway isolato e temporaneo, oppure eseguire OpenClaw su un host senza installazioni locali.
- **No**: stai lavorando sulla tua macchina e vuoi solo il ciclo di sviluppo più rapido. Usa invece il normale flusso di installazione.
- **Nota sul sandboxing**: il backend sandbox predefinito usa Docker quando il sandboxing è abilitato, ma il sandboxing è disattivato per impostazione predefinita e **non** richiede che l'intero Gateway venga eseguito in Docker. Sono disponibili anche i backend sandbox SSH e OpenShell. Vedi [Sandboxing](/it/gateway/sandboxing).
- **Sì**: vuoi un ambiente Gateway isolato e temporaneo, oppure eseguire OpenClaw su una macchina senza installazioni locali.
- **No**: stai eseguendo tutto sulla tua macchina e vuoi solo il ciclo di sviluppo più rapido. Usa invece il normale flusso di installazione.
- **Nota sul sandboxing**: il backend sandbox predefinito usa Docker quando il sandboxing è abilitato, ma il sandboxing è disattivato per impostazione predefinita e **non** richiede che l’intero Gateway venga eseguito in Docker. Sono disponibili anche i backend sandbox SSH e OpenShell. Vedi [Sandboxing](/it/gateway/sandboxing).
## Prerequisiti
- Docker Desktop (o Docker Engine) + Docker Compose v2
- Almeno 2 GB di RAM per la build dell'immagine (`pnpm install` potrebbe essere terminato per OOM su host da 1 GB con uscita 137)
- Almeno 2 GB di RAM per la compilazione dell’immagine (`pnpm install` può essere terminato per memoria insufficiente su macchine da 1 GB con codice di uscita 137)
- Spazio su disco sufficiente per immagini e log
- Se esegui su un VPS/host pubblico, consulta
[Rafforzamento della sicurezza per l'esposizione di rete](/it/gateway/security),
- Se esegui su una VPS/macchina pubblica, consulta
[Rafforzamento della sicurezza per l’esposizione di rete](/it/gateway/security),
in particolare la policy firewall Docker `DOCKER-USER`.
## Gateway containerizzato
<Steps>
<Step title="Crea l'immagine">
Dalla root del repo, esegui lo script di configurazione:
<Step title="Compila l’immagine">
Dalla root del repository, esegui lo script di configurazione:
```bash
./scripts/docker/setup.sh
```
Questo crea localmente l'immagine del Gateway. Per usare invece un'immagine precompilata:
Questo compila localmente l’immagine del Gateway. Per usare invece un’immagine precompilata:
```bash
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
@ -49,30 +49,28 @@ Docker è **facoltativo**. Usalo solo se vuoi un Gateway containerizzato o valid
Le immagini precompilate sono pubblicate nel
[GitHub Container Registry](https://github.com/openclaw/openclaw/pkgs/container/openclaw).
Tag comuni: `main`, `latest`, `<version>` (ad es. `2026.2.26`).
Tag comuni: `main`, `latest`, `<version>` (ad esempio `2026.2.26`).
</Step>
<Step title="Completa l'onboarding">
Lo script di configurazione esegue automaticamente l'onboarding. Questo:
<Step title="Completa l’onboarding">
Lo script di configurazione esegue automaticamente l’onboarding. Farà quanto segue:
- richiederà le chiavi API del provider
- richiederà le chiavi API dei provider
- genererà un token del Gateway e lo scriverà in `.env`
- avvierà il Gateway tramite Docker Compose
Durante la configurazione, l'onboarding prima dell'avvio e le scritture della configurazione passano
direttamente da `openclaw-gateway`. `openclaw-cli` è per i comandi che esegui dopo che
il container del Gateway esiste già.
Durante la configurazione, l’onboarding prima dell’avvio e le scritture di configurazione vengono eseguiti direttamente tramite
`openclaw-gateway`. `openclaw-cli` è pensato per i comandi da eseguire dopo
che il container del Gateway esiste già.
</Step>
<Step title="Apri la UI di controllo">
<Step title="Apri la Control UI">
Apri `http://127.0.0.1:18789/` nel browser e incolla il segreto condiviso
configurato in Impostazioni. Per impostazione predefinita lo script di configurazione scrive un token in `.env`;
se cambi la configurazione del container per usare l'autenticazione con password, usa invece quella
password.
configurato nelle Impostazioni. Per impostazione predefinita, lo script di configurazione scrive un token in `.env`; se cambi la configurazione del container per usare l’autenticazione con password, usa invece quella password.
Ti serve di nuovo l'URL?
Ti serve di nuovo l’URL?
```bash
docker compose run --rm openclaw-cli dashboard --no-open
@ -80,7 +78,7 @@ Docker è **facoltativo**. Usalo solo se vuoi un Gateway containerizzato o valid
</Step>
<Step title="Configura i canali (facoltativo)">
<Step title="Configura i canali (opzionale)">
Usa il container CLI per aggiungere canali di messaggistica:
```bash
@ -94,14 +92,14 @@ Docker è **facoltativo**. Usalo solo se vuoi un Gateway containerizzato o valid
docker compose run --rm openclaw-cli channels add --channel discord --token "<token>"
```
Documenti: [WhatsApp](/it/channels/whatsapp), [Telegram](/it/channels/telegram), [Discord](/it/channels/discord)
Documentazione: [WhatsApp](/it/channels/whatsapp), [Telegram](/it/channels/telegram), [Discord](/it/channels/discord)
</Step>
</Steps>
### Flusso manuale
Se preferisci eseguire ogni passaggio autonomamente invece di usare lo script di configurazione:
Se preferisci eseguire ogni passaggio manualmente invece di usare lo script di configurazione:
```bash
docker build -t openclaw:local -f Dockerfile .
@ -113,52 +111,52 @@ docker compose up -d openclaw-gateway
```
<Note>
Esegui `docker compose` dalla root del repo. Se hai abilitato `OPENCLAW_EXTRA_MOUNTS`
Esegui `docker compose` dalla root del repository. Se hai abilitato `OPENCLAW_EXTRA_MOUNTS`
o `OPENCLAW_HOME_VOLUME`, lo script di configurazione scrive `docker-compose.extra.yml`;
includilo con `-f docker-compose.yml -f docker-compose.extra.yml`.
</Note>
<Note>
Poiché `openclaw-cli` condivide il namespace di rete di `openclaw-gateway`, è uno
strumento post-avvio. Prima di `docker compose up -d openclaw-gateway`, esegui l'onboarding
e le scritture della configurazione in fase di setup tramite `openclaw-gateway` con
Poiché `openclaw-cli` condivide lo spazio dei nomi di rete di `openclaw-gateway`, è uno
strumento post-avvio. Prima di `docker compose up -d openclaw-gateway`, esegui l’onboarding
e le scritture di configurazione in fase di configurazione tramite `openclaw-gateway` con
`--no-deps --entrypoint node`.
</Note>
### Variabili d'ambiente
### Variabili d’ambiente
Lo script di configurazione accetta queste variabili d'ambiente facoltative:
Lo script di configurazione accetta queste variabili d’ambiente opzionali:
| Variabile | Scopo |
| ------------------------------------------ | --------------------------------------------------------------- |
| `OPENCLAW_IMAGE` | Usa un'immagine remota invece di crearla localmente |
| `OPENCLAW_DOCKER_APT_PACKAGES` | Installa pacchetti apt aggiuntivi durante la build (separati da spazi) |
| `OPENCLAW_EXTENSIONS` | Include helper Plugin in bundle selezionati in fase di build |
| `OPENCLAW_EXTRA_MOUNTS` | Bind mount host aggiuntivi (`source:target[:opts]` separati da virgole) |
| `OPENCLAW_HOME_VOLUME` | Mantiene `/home/node` in un volume Docker nominato |
| `OPENCLAW_IMAGE` | Usa un’immagine remota invece di compilarla localmente |
| `OPENCLAW_DOCKER_APT_PACKAGES` | Installa pacchetti apt extra durante la compilazione (separati da spazi) |
| `OPENCLAW_EXTENSIONS` | Include helper di Plugin inclusi selezionati in fase di compilazione |
| `OPENCLAW_EXTRA_MOUNTS` | Montaggi bind extra del sistema ospitante (separati da virgole `source:target[:opts]`) |
| `OPENCLAW_HOME_VOLUME` | Persiste `/home/node` in un volume Docker denominato |
| `OPENCLAW_SANDBOX` | Abilita il bootstrap sandbox (`1`, `true`, `yes`, `on`) |
| `OPENCLAW_SKIP_ONBOARDING` | Salta il passaggio di onboarding interattivo (`1`, `true`, `yes`, `on`) |
| `OPENCLAW_DOCKER_SOCKET` | Sovrascrive il percorso del socket Docker |
| `OPENCLAW_DISABLE_BONJOUR` | Disabilita la pubblicità Bonjour/mDNS (predefinito a `1` per Docker) |
| `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS` | Disabilita gli overlay bind-mount del sorgente Plugin in bundle |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint collector OTLP/HTTP condiviso per l'export OpenTelemetry |
| `OTEL_EXPORTER_OTLP_*_ENDPOINT` | Endpoint OTLP specifici per segnale per tracce, metriche o log |
| `OPENCLAW_DISABLE_BONJOUR` | Disabilita la pubblicità Bonjour/mDNS (valore predefinito `1` per Docker) |
| `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS` | Disabilita gli overlay bind-mount del sorgente dei Plugin inclusi |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint del collector OTLP/HTTP condiviso per l’esportazione OpenTelemetry |
| `OTEL_EXPORTER_OTLP_*_ENDPOINT` | Endpoint OTLP specifici del segnale per trace, metriche o log |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | Sovrascrittura del protocollo OTLP. Oggi è supportato solo `http/protobuf` |
| `OTEL_SERVICE_NAME` | Nome del servizio usato per le risorse OpenTelemetry |
| `OTEL_SEMCONV_STABILITY_OPT_IN` | Abilita gli ultimi attributi semantici GenAI sperimentali |
| `OPENCLAW_OTEL_PRELOADED` | Salta l'avvio di un secondo SDK OpenTelemetry quando uno è precaricato |
| `OTEL_SEMCONV_STABILITY_OPT_IN` | Abilita gli attributi semantici GenAI sperimentali più recenti |
| `OPENCLAW_OTEL_PRELOADED` | Salta l’avvio di un secondo SDK OpenTelemetry quando ne è già precaricato uno |
I maintainer possono testare il sorgente Plugin in bundle rispetto a un'immagine pacchettizzata montando
una directory sorgente del Plugin sopra il suo percorso sorgente pacchettizzato, ad esempio
I maintainer possono testare il sorgente dei Plugin inclusi rispetto a un’immagine pacchettizzata montando
una directory sorgente di Plugin sopra il relativo percorso sorgente pacchettizzato, ad esempio
`OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro`.
Quella directory sorgente montata sovrascrive il bundle compilato corrispondente
`/app/dist/extensions/synology-chat` per lo stesso id Plugin.
`/app/dist/extensions/synology-chat` per lo stesso ID Plugin.
### Osservabilità
L'export OpenTelemetry è in uscita dal container Gateway verso il tuo collector
OTLP. Non richiede una porta Docker pubblicata. Se crei l'immagine
localmente e vuoi che l'exporter OpenTelemetry in bundle sia disponibile dentro l'immagine,
L’esportazione OpenTelemetry è in uscita dal container del Gateway verso il tuo collector
OTLP. Non richiede una porta Docker pubblicata. Se compili l’immagine
localmente e vuoi che l’esportatore OpenTelemetry incluso sia disponibile dentro l’immagine,
includi le sue dipendenze runtime:
```bash
@ -169,40 +167,40 @@ export OTEL_SERVICE_NAME="openclaw-gateway"
```
Installa il Plugin ufficiale `@openclaw/diagnostics-otel` da ClawHub nelle
installazioni Docker pacchettizzate prima di abilitare l'export. Le immagini personalizzate create da sorgente possono
comunque includere il sorgente Plugin locale con
`OPENCLAW_EXTENSIONS=diagnostics-otel`. Per abilitare l'export, consenti e abilita il
installazioni Docker pacchettizzate prima di abilitare l’esportazione. Le immagini personalizzate compilate da sorgente possono
ancora includere il sorgente del Plugin locale con
`OPENCLAW_EXTENSIONS=diagnostics-otel`. Per abilitare l’esportazione, consenti e abilita il
Plugin `diagnostics-otel` nella configurazione, quindi imposta
`diagnostics.otel.enabled=true` oppure usa l'esempio di configurazione in [Export
`diagnostics.otel.enabled=true` oppure usa l’esempio di configurazione in [Esportazione
OpenTelemetry](/it/gateway/opentelemetry). Gli header di autenticazione del collector sono configurati tramite
`diagnostics.otel.headers`, non tramite variabili d'ambiente Docker.
`diagnostics.otel.headers`, non tramite variabili d’ambiente Docker.
Le metriche Prometheus usano la porta Gateway già pubblicata. Installa
`clawhub:@openclaw/diagnostics-prometheus`, abilita il Plugin
`diagnostics-prometheus`, quindi esegui lo scrape:
`clawhub:@openclaw/diagnostics-prometheus`, abilita il
Plugin `diagnostics-prometheus`, quindi esegui lo scraping:
```text
http://<gateway-host>:18789/api/diagnostics/prometheus
```
La route è protetta dall'autenticazione Gateway. Non esporre una porta `/metrics`
pubblica separata o un percorso reverse-proxy non autenticato. Vedi
La route è protetta dall’autenticazione del Gateway. Non esporre una porta
pubblica `/metrics` separata o un percorso reverse proxy non autenticato. Vedi
[Metriche Prometheus](/it/gateway/prometheus).
### Controlli di integrità
Endpoint di probe del container (nessuna autenticazione richiesta):
Endpoint probe del container (nessuna autenticazione richiesta):
```bash
curl -fsS http://127.0.0.1:18789/healthz # liveness
curl -fsS http://127.0.0.1:18789/readyz # readiness
```
L'immagine Docker include un `HEALTHCHECK` integrato che esegue ping su `/healthz`.
L’immagine Docker include un `HEALTHCHECK` integrato che interroga `/healthz`.
Se i controlli continuano a fallire, Docker contrassegna il container come `unhealthy` e
i sistemi di orchestrazione possono riavviarlo o sostituirlo.
Snapshot di integrità approfondito autenticato:
Snapshot approfondito di integrità autenticato:
```bash
docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"
@ -210,87 +208,87 @@ docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLA
### LAN vs loopback
`scripts/docker/setup.sh` imposta per impostazione predefinita `OPENCLAW_GATEWAY_BIND=lan`, così l'accesso host a
`scripts/docker/setup.sh` imposta per impostazione predefinita `OPENCLAW_GATEWAY_BIND=lan` così l’accesso dal sistema ospitante a
`http://127.0.0.1:18789` funziona con la pubblicazione delle porte Docker.
- `lan` (predefinito): il browser host e la CLI host possono raggiungere la porta Gateway pubblicata.
- `loopback`: solo i processi dentro il namespace di rete del container possono raggiungere
- `lan` (predefinito): il browser e la CLI del sistema ospitante possono raggiungere la porta pubblicata del Gateway.
- `loopback`: solo i processi all’interno dello spazio dei nomi di rete del container possono raggiungere
direttamente il Gateway.
<Note>
Usa i valori della modalità bind in `gateway.bind` (`lan` / `loopback` / `custom` /
`tailnet` / `auto`), non alias host come `0.0.0.0` o `127.0.0.1`.
Usa i valori della modalità di bind in `gateway.bind` (`lan` / `loopback` / `custom` /
`tailnet` / `auto`), non alias del sistema ospitante come `0.0.0.0` o `127.0.0.1`.
</Note>
### Provider locali sull'host
### Provider locali sul sistema ospitante
Quando OpenClaw viene eseguito in Docker, `127.0.0.1` dentro il container è il container
stesso, non la macchina host. Usa `host.docker.internal` per i provider AI che
vengono eseguiti sull'host:
stesso, non la tua macchina ospitante. Usa `host.docker.internal` per i provider AI che
girano sul sistema ospitante:
| Provider | URL host predefinito | URL setup Docker |
| --------- | ------------------------ | ---------------------------------- |
| LM Studio | `http://127.0.0.1:1234` | `http://host.docker.internal:1234` |
| Provider | URL predefinito del sistema ospitante | URL di configurazione Docker |
| --------- | ------------------------ | ----------------------------------- |
| LM Studio | `http://127.0.0.1:1234` | `http://host.docker.internal:1234` |
| Ollama | `http://127.0.0.1:11434` | `http://host.docker.internal:11434` |
Il setup Docker in bundle usa questi URL host come valori predefiniti di onboarding per LM Studio e Ollama,
e `docker-compose.yml` mappa `host.docker.internal` al Gateway host di Docker per Linux Docker Engine.
Docker Desktop fornisce già lo stesso hostname su macOS e Windows.
La configurazione Docker inclusa usa quegli URL del sistema ospitante come valori predefiniti di onboarding per LM Studio e Ollama,
e `docker-compose.yml` mappa `host.docker.internal` al
Gateway dell’host Docker per Docker Engine su Linux. Docker Desktop fornisce già
lo stesso nome host su macOS e Windows.
Anche i servizi host devono restare in ascolto su un indirizzo raggiungibile da Docker:
Anche i servizi sul sistema ospitante devono restare in ascolto su un indirizzo raggiungibile da Docker:
```bash
lms server start --port 1234 --bind 0.0.0.0
OLLAMA_HOST=0.0.0.0:11434 ollama serve
```
Se usi il tuo file Compose o comando `docker run`, aggiungi tu stesso la stessa
mappatura host, ad esempio
Se usi un tuo file Compose o comando `docker run`, aggiungi personalmente la stessa
mappatura dell’host, ad esempio
`--add-host=host.docker.internal:host-gateway`.
### Bonjour / mDNS
La rete bridge Docker di solito non inoltra in modo affidabile il multicast Bonjour/mDNS
(`224.0.0.251:5353`). Per questo motivo il setup Compose in bundle imposta per impostazione predefinita
`OPENCLAW_DISABLE_BONJOUR=1`, così il Gateway non va in crash-loop né riavvia
ripetutamente la pubblicità quando il bridge scarta il traffico multicast.
(`224.0.0.251:5353`). La configurazione Compose inclusa quindi imposta per impostazione predefinita
`OPENCLAW_DISABLE_BONJOUR=1`, così il Gateway non entra in un ciclo di arresti anomali o non
riavvia ripetutamente la pubblicità quando il bridge perde il traffico multicast.
Usa l'URL Gateway pubblicato, Tailscale o DNS-SD wide-area per gli host Docker.
Imposta `OPENCLAW_DISABLE_BONJOUR=0` solo quando esegui con networking host, macvlan,
o un'altra rete in cui è noto che il multicast mDNS funzioni.
Usa l’URL pubblicato del Gateway, Tailscale o DNS-SD ad area vasta per le macchine Docker.
Imposta `OPENCLAW_DISABLE_BONJOUR=0` solo quando esegui con rete host, macvlan
o un’altra rete in cui è noto che il multicast mDNS funzioni.
Per avvertenze e risoluzione dei problemi, vedi [Scoperta Bonjour](/it/gateway/bonjour).
Per problemi comuni e risoluzione, vedi [Rilevamento Bonjour](/it/gateway/bonjour).
### Archiviazione e persistenza
Docker Compose esegue bind-mount di `OPENCLAW_CONFIG_DIR` su `/home/node/.openclaw` e
di `OPENCLAW_WORKSPACE_DIR` su `/home/node/.openclaw/workspace`, quindi questi percorsi
sopravvivono alla sostituzione del container. Quando una delle due variabili non è impostata, il
`docker-compose.yml` in bundle ripiega su `${HOME}/.openclaw` (e
`${HOME}/.openclaw/workspace` per il mount dello workspace), o su `/tmp/.openclaw`
quando manca anche `HOME`. Questo impedisce a `docker compose up` di
emettere una specifica di volume con sorgente vuota in ambienti essenziali.
Docker Compose monta con bind `OPENCLAW_CONFIG_DIR` su `/home/node/.openclaw` e
`OPENCLAW_WORKSPACE_DIR` su `/home/node/.openclaw/workspace`, quindi quei percorsi
sopravvivono alla sostituzione del container. Quando una delle variabili non è impostata, il
`docker-compose.yml` incluso ripiega su `${HOME}/.openclaw` (e
`${HOME}/.openclaw/workspace` per il montaggio del workspace), oppure su `/tmp/.openclaw`
quando manca anche `HOME`. Questo evita che `docker compose up` emetta
una specifica di volume con sorgente vuota su ambienti essenziali.
Quella directory di configurazione montata è dove OpenClaw conserva:
- `openclaw.json` per la configurazione del comportamento
- `agents/<agentId>/agent/auth-profiles.json` per l'autenticazione OAuth/chiave API del provider archiviata
- `.env` per segreti runtime basati su env come `OPENCLAW_GATEWAY_TOKEN`
- `agents/<agentId>/agent/auth-profiles.json` per le credenziali OAuth/chiavi API dei provider archiviate
- `.env` per segreti runtime basati sull’ambiente come `OPENCLAW_GATEWAY_TOKEN`
I Plugin scaricabili installati archiviano il loro stato di pacchetto sotto la home OpenClaw
montata, quindi i record di installazione dei Plugin e le root dei pacchetti sopravvivono alla sostituzione del container.
L'avvio del Gateway non genera alberi di dipendenze per i Plugin in bundle.
I Plugin scaricabili installati archiviano il loro stato del pacchetto nella home
OpenClaw montata, quindi i record di installazione dei Plugin e le root dei pacchetti sopravvivono alla sostituzione del container. L’avvio del Gateway non genera alberi delle dipendenze dei Plugin inclusi.
Per i dettagli completi sulla persistenza nelle distribuzioni VM, vedi
Per i dettagli completi sulla persistenza nelle distribuzioni su VM, vedi
[Runtime VM Docker - Cosa persiste dove](/it/install/docker-vm-runtime#what-persists-where).
**Punti critici di crescita del disco:** monitora `media/`, i file JSONL delle sessioni,
`cron/runs/*.jsonl`, le radici dei pacchetti Plugin installati e i log su file a rotazione
sotto `/tmp/openclaw/`.
### Helper shell (opzionali)
### Helper shell (facoltativi)
Per semplificare la gestione quotidiana di Docker, installa `ClawDock`:
Per una gestione quotidiana di Docker più semplice, installa `ClawDock`:
```bash
mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh
@ -299,12 +297,12 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc
Se hai installato ClawDock dal vecchio percorso raw `scripts/shell-helpers/clawdock-helpers.sh`, riesegui il comando di installazione sopra in modo che il file helper locale segua la nuova posizione.
Poi usa `clawdock-start`, `clawdock-stop`, `clawdock-dashboard` e così via. Esegui
Poi usa `clawdock-start`, `clawdock-stop`, `clawdock-dashboard`, ecc. Esegui
`clawdock-help` per tutti i comandi.
Vedi [ClawDock](/it/install/clawdock) per la guida completa agli helper.
<AccordionGroup>
<Accordion title="Abilita la sandbox degli agenti per il Gateway Docker">
<Accordion title="Abilita la sandbox dell'agente per il gateway Docker">
```bash
export OPENCLAW_SANDBOX=1
./scripts/docker/setup.sh
@ -318,13 +316,13 @@ Vedi [ClawDock](/it/install/clawdock) per la guida completa agli helper.
./scripts/docker/setup.sh
```
Lo script monta `docker.sock` solo dopo che i prerequisiti della sandbox sono stati superati. Se
Lo script monta `docker.sock` solo dopo che i prerequisiti della sandbox sono stati soddisfatti. Se
la configurazione della sandbox non può essere completata, lo script reimposta `agents.defaults.sandbox.mode`
su `off`.
</Accordion>
<Accordion title="Automazione / CI (non interattiva)">
<Accordion title="Automazione / CI (non interattivo)">
Disabilita l'allocazione pseudo-TTY di Compose con `-T`:
```bash
@ -335,14 +333,14 @@ Vedi [ClawDock](/it/install/clawdock) per la guida completa agli helper.
</Accordion>
<Accordion title="Nota di sicurezza sulla rete condivisa">
`openclaw-cli` usa `network_mode: "service:openclaw-gateway"` in modo che i
comandi CLI possano raggiungere il Gateway su `127.0.0.1`. Trattalo come un confine di
fiducia condiviso. La configurazione Compose rimuove `NET_RAW`/`NET_ADMIN` e abilita
`no-new-privileges` su `openclaw-cli`.
`openclaw-cli` usa `network_mode: "service:openclaw-gateway"` così i comandi
CLI possono raggiungere il Gateway su `127.0.0.1`. Trattalo come un confine
di fiducia condiviso. La configurazione compose rimuove `NET_RAW`/`NET_ADMIN` e abilita
`no-new-privileges` sia su `openclaw-gateway` sia su `openclaw-cli`.
</Accordion>
<Accordion title="Permessi ed EACCES">
L'immagine viene eseguita come `node` (uid 1000). Se vedi errori di permesso su
L'immagine viene eseguita come `node` (uid 1000). Se vedi errori di permessi su
`/home/node/.openclaw`, assicurati che i bind mount dell'host siano di proprietà dell'uid 1000:
```bash
@ -351,8 +349,8 @@ Vedi [ClawDock](/it/install/clawdock) per la guida completa agli helper.
</Accordion>
<Accordion title="Ricompilazioni più rapide">
Ordina il tuo Dockerfile in modo che i layer delle dipendenze siano memorizzati nella cache. Questo evita di rieseguire
<Accordion title="Ricostruzioni più rapide">
Ordina il tuo Dockerfile in modo che i layer delle dipendenze vengano memorizzati nella cache. Questo evita di rieseguire
`pnpm install` a meno che i lockfile non cambino:
```dockerfile
@ -375,20 +373,20 @@ Vedi [ClawDock](/it/install/clawdock) per la guida completa agli helper.
</Accordion>
<Accordion title="Opzioni del container per utenti avanzati">
L'immagine predefinita dà priorità alla sicurezza e viene eseguita come `node` non root. Per un container più
completo:
<Accordion title="Opzioni container per utenti esperti">
L'immagine predefinita privilegia la sicurezza e viene eseguita come `node` non root. Per un container
più completo:
1. **Persistere `/home/node`**: `export OPENCLAW_HOME_VOLUME="openclaw_home"`
2. **Integrare le dipendenze di sistema**: `export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"`
3. **Installare i browser Playwright**:
1. **Persisti `/home/node`**: `export OPENCLAW_HOME_VOLUME="openclaw_home"`
2. **Integra le dipendenze di sistema**: `export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"`
3. **Installa i browser Playwright**:
```bash
docker compose run --rm openclaw-cli \
node /app/node_modules/playwright-core/cli.js install chromium
```
4. **Persistere i download dei browser**: imposta
4. **Persisti i download dei browser**: imposta
`PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright` e usa
`OPENCLAW_HOME_VOLUME` oppure `OPENCLAW_EXTRA_MOUNTS`.
`OPENCLAW_HOME_VOLUME` o `OPENCLAW_EXTRA_MOUNTS`.
</Accordion>
@ -401,36 +399,36 @@ Vedi [ClawDock](/it/install/clawdock) per la guida completa agli helper.
<Accordion title="Metadati dell'immagine base">
L'immagine runtime Docker principale usa `node:24-bookworm-slim` e pubblica annotazioni OCI
dell'immagine base, incluse `org.opencontainers.image.base.name`,
`org.opencontainers.image.source` e altre. Il digest della base Node viene
aggiornato tramite le PR Dependabot per l'immagine base Docker; le build di rilascio non eseguono
`org.opencontainers.image.source` e altre. Il digest base di Node viene
aggiornato tramite PR Dependabot per immagini base Docker; le build di rilascio non eseguono
un layer di aggiornamento della distribuzione. Vedi
[annotazioni delle immagini OCI](https://github.com/opencontainers/image-spec/blob/main/annotations.md).
[annotazioni immagine OCI](https://github.com/opencontainers/image-spec/blob/main/annotations.md).
</Accordion>
</AccordionGroup>
### Esecuzione su una VPS?
### Esecuzione su un VPS?
Vedi [Hetzner (VPS Docker)](/it/install/hetzner) e
[Runtime VM Docker](/it/install/docker-vm-runtime) per i passaggi di distribuzione su VM condivisa,
inclusi baking dei binari, persistenza e aggiornamenti.
[Runtime VM Docker](/it/install/docker-vm-runtime) per i passaggi di distribuzione su VM condivisa
inclusi integrazione dei binari, persistenza e aggiornamenti.
## Sandbox degli agenti
## Sandbox dell'agente
Quando `agents.defaults.sandbox` è abilitato con il backend Docker, il Gateway
esegue l'esecuzione degli strumenti degli agenti (shell, lettura/scrittura file, ecc.) all'interno di container Docker
isolati mentre il Gateway stesso resta sull'host. Questo ti dà una barriera rigida
intorno a sessioni di agenti non attendibili o multi-tenant senza containerizzare l'intero
esegue l'esecuzione degli strumenti dell'agente (shell, lettura/scrittura file, ecc.) dentro container Docker
isolati mentre il Gateway stesso rimane sull'host. Questo ti dà una barriera rigida
attorno a sessioni agente non attendibili o multi-tenant senza containerizzare l'intero
Gateway.
L'ambito della sandbox può essere per agente (predefinito), per sessione o condiviso. Ogni ambito
ottiene il proprio workspace montato in `/workspace`. Puoi anche configurare
criteri allow/deny degli strumenti, isolamento di rete, limiti di risorse e container
criteri allow/deny per gli strumenti, isolamento di rete, limiti di risorse e container
browser.
Per la configurazione completa, immagini, note di sicurezza e profili multi-agente, vedi:
- [Sandboxing](/it/gateway/sandboxing) -- riferimento completo della sandbox
- [OpenShell](/it/gateway/openshell) -- accesso shell interattivo ai container della sandbox
- [OpenShell](/it/gateway/openshell) -- accesso shell interattivo ai container sandbox
- [Sandbox e strumenti multi-agente](/it/tools/multi-agent-sandbox-tools) -- override per agente
### Abilitazione rapida
@ -448,42 +446,42 @@ Per la configurazione completa, immagini, note di sicurezza e profili multi-agen
}
```
Compila l'immagine sandbox predefinita (da un checkout sorgente):
Crea l'immagine sandbox predefinita (da un checkout del sorgente):
```bash
scripts/sandbox-setup.sh
```
Per installazioni npm senza checkout sorgente, vedi [Sandboxing § Immagini e configurazione](/it/gateway/sandboxing#images-and-setup) per comandi `docker build` inline.
Per installazioni npm senza checkout del sorgente, vedi [Sandboxing § Immagini e configurazione](/it/gateway/sandboxing#images-and-setup) per i comandi `docker build` inline.
## Risoluzione dei problemi
<AccordionGroup>
<Accordion title="Immagine mancante o container sandbox che non si avvia">
Compila l'immagine sandbox con
Crea l'immagine sandbox con
[`scripts/sandbox-setup.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh)
(checkout sorgente) oppure il comando `docker build` inline da [Sandboxing § Immagini e configurazione](/it/gateway/sandboxing#images-and-setup) (installazione npm),
(checkout del sorgente) oppure con il comando `docker build` inline da [Sandboxing § Immagini e configurazione](/it/gateway/sandboxing#images-and-setup) (installazione npm),
oppure imposta `agents.defaults.sandbox.docker.image` sulla tua immagine personalizzata.
I container vengono creati automaticamente per sessione su richiesta.
</Accordion>
<Accordion title="Errori di permesso nella sandbox">
Imposta `docker.user` su un UID:GID che corrisponda alla proprietà del workspace montato,
<Accordion title="Errori di permessi nella sandbox">
Imposta `docker.user` su un UID:GID che corrisponde alla proprietà del workspace montato,
oppure esegui chown sulla cartella del workspace.
</Accordion>
<Accordion title="Strumenti personalizzati non trovati nella sandbox">
OpenClaw esegue i comandi con `sh -lc` (shell di login), che legge
`/etc/profile` e potrebbe reimpostare PATH. Imposta `docker.env.PATH` per anteporre i tuoi
OpenClaw esegue i comandi con `sh -lc` (login shell), che carica
`/etc/profile` e può reimpostare PATH. Imposta `docker.env.PATH` per anteporre i tuoi
percorsi degli strumenti personalizzati, oppure aggiungi uno script sotto `/etc/profile.d/` nel tuo Dockerfile.
</Accordion>
<Accordion title="Terminato per OOM durante la build dell'immagine (exit 137)">
La VM richiede almeno 2 GB di RAM. Usa una classe di macchina più grande e riprova.
La VM richiede almeno 2 GB di RAM. Usa una classe macchina più grande e riprova.
</Accordion>
<Accordion title="Non autorizzato o abbinamento richiesto nella Control UI">
Recupera un link della dashboard aggiornato e approva il dispositivo browser:
<Accordion title="Non autorizzato o associazione richiesta nella UI di controllo">
Recupera un nuovo link alla dashboard e approva il dispositivo browser:
```bash
docker compose run --rm openclaw-cli dashboard --no-open
@ -495,7 +493,7 @@ Per installazioni npm senza checkout sorgente, vedi [Sandboxing § Immagini e co
</Accordion>
<Accordion title="La destinazione del Gateway mostra ws://172.x.x.x o errori di abbinamento dalla CLI Docker">
<Accordion title="Il target del Gateway mostra ws://172.x.x.x o errori di associazione dalla CLI Docker">
Reimposta la modalità e il bind del Gateway:
```bash
@ -510,6 +508,6 @@ Per installazioni npm senza checkout sorgente, vedi [Sandboxing § Immagini e co
- [Panoramica installazione](/it/install) — tutti i metodi di installazione
- [Podman](/it/install/podman) — alternativa Podman a Docker
- [ClawDock](/it/install/clawdock) — configurazione community con Docker Compose
- [ClawDock](/it/install/clawdock) — configurazione community Docker Compose
- [Aggiornamento](/it/install/updating) — mantenere OpenClaw aggiornato
- [Configurazione](/it/gateway/configuration) — configurazione del Gateway dopo l'installazione

323
docs/it/reference/session-management-compaction.md
View File

@ -1,118 +1,118 @@
---
read_when:
- È necessario eseguire il debug degli ID di sessione, della trascrizione JSONL o dei campi sessions.json
- Stai modificando il comportamento di auto-Compaction o aggiungendo attività di housekeeping “pre-Compaction”
- È necessario eseguire il debug degli ID di sessione, del JSONL della trascrizione o dei campi di sessions.json
- Stai modificando il comportamento di Compaction automatica o aggiungendo operazioni di manutenzione “pre-Compaction”
- Vuoi implementare svuotamenti della memoria o turni di sistema silenziosi
summary: 'Approfondimento: store delle sessioni + trascrizioni, ciclo di vita e dettagli interni della Compaction (automatica)'
summary: 'Approfondimento: archivio delle sessioni + trascrizioni, ciclo di vita e dettagli interni della (auto)Compaction'
title: Approfondimento sulla gestione delle sessioni
x-i18n:
generated_at: "2026-05-02T21:00:12Z"
generated_at: "2026-05-05T08:26:39Z"
model: gpt-5.5
provider: openai
source_hash: 8271d7b0786e1c47a8cec6e7bd73c3c86a433d629e17937fdd87fa756ed78d73
source_hash: 3161dd9c98bff7ea24266f44a9261693d8a9ee2b47d9af2d152de7057016748b
source_path: reference/session-management-compaction.md
workflow: 16
---
OpenClaw gestisce le sessioni end-to-end in queste aree:
- **Instradamento delle sessioni** (come i messaggi in ingresso vengono mappati a una `sessionKey`)
- **Archivio delle sessioni** (`sessions.json`) e cosa traccia
- **Persistenza delle trascrizioni** (`*.jsonl`) e la relativa struttura
- **Igiene delle trascrizioni** (correzioni specifiche del provider prima delle esecuzioni)
- **Limiti di contesto** (finestra di contesto rispetto ai token tracciati)
- **Compaction** (Compaction manuale e automatica) e dove agganciare il lavoro pre-Compaction
- **Manutenzione silenziosa** (scritture in memoria che non devono produrre output visibile all’utente)
- **Routing delle sessioni** (come i messaggi in ingresso vengono mappati a una `sessionKey`)
- **Store delle sessioni** (`sessions.json`) e cosa traccia
- **Persistenza della trascrizione** (`*.jsonl`) e la sua struttura
- **Igiene della trascrizione** (correzioni specifiche del provider prima delle esecuzioni)
- **Limiti del contesto** (finestra di contesto rispetto ai token tracciati)
- **Compaction** (manuale e automatica) e dove collegare il lavoro pre-Compaction
- **Housekeeping silenzioso** (scritture in memoria che non devono produrre output visibile all'utente)
Se vuoi prima una panoramica di livello più alto, inizia da:
Se vuoi prima una panoramica di livello superiore, inizia da:
- [Gestione delle sessioni](/it/concepts/session)
- [Compaction](/it/concepts/compaction)
- [Panoramica della memoria](/it/concepts/memory)
- [Ricerca in memoria](/it/concepts/memory-search)
- [Ricerca nella memoria](/it/concepts/memory-search)
- [Potatura delle sessioni](/it/concepts/session-pruning)
- [Igiene delle trascrizioni](/it/reference/transcript-hygiene)
- [Igiene della trascrizione](/it/reference/transcript-hygiene)
---
## Fonte di verità: il Gateway
OpenClaw è progettato attorno a un singolo **processo Gateway** che possiede lo stato delle sessioni.
OpenClaw è progettato intorno a un singolo **processo Gateway** che possiede lo stato delle sessioni.
- Le UI (app macOS, Control UI web, TUI) devono interrogare il Gateway per gli elenchi di sessioni e i conteggi dei token.
- In modalità remota, i file di sessione si trovano sull’host remoto; “controllare i file locali del Mac” non rifletterà ciò che il Gateway sta usando.
- Le UI (app macOS, Control UI web, TUI) devono interrogare il Gateway per gli elenchi delle sessioni e i conteggi dei token.
- In modalità remota, i file delle sessioni sono sull'host remoto; “controllare i file locali del Mac” non riflette ciò che il Gateway sta usando.
---
## Due livelli di persistenza
OpenClaw conserva le sessioni in due livelli:
OpenClaw persiste le sessioni in due livelli:
1. **Archivio delle sessioni (`sessions.json`)**
1. **Store delle sessioni (`sessions.json`)**
- Mappa chiave/valore: `sessionKey -> SessionEntry`
- Piccolo, mutabile, sicuro da modificare (o da cui eliminare voci)
- Traccia i metadati della sessione (ID sessione corrente, ultima attività, toggle, contatori di token, ecc.)
- Traccia i metadati della sessione (id della sessione corrente, ultima attività, toggle, contatori dei token, ecc.)
2. **Trascrizione (`<sessionId>.jsonl`)**
- Trascrizione append-only con struttura ad albero (le voci hanno `id` + `parentId`)
- Archivia la conversazione effettiva + le chiamate agli strumenti + i riepiloghi di Compaction
- Memorizza la conversazione effettiva + chiamate agli strumenti + riepiloghi di Compaction
- Usata per ricostruire il contesto del modello per i turni futuri
- I checkpoint di debug pre-Compaction di grandi dimensioni vengono saltati quando la trascrizione
attiva supera il limite di dimensione dei checkpoint, evitando una seconda enorme
copia `.checkpoint.*.jsonl`.
- I checkpoint di debug grandi pre-Compaction vengono saltati quando la
trascrizione attiva supera il limite di dimensione dei checkpoint, evitando una seconda copia
enorme `.checkpoint.*.jsonl`.
I lettori della cronologia del Gateway dovrebbero evitare di materializzare l’intera trascrizione a meno che
la superficie non richieda esplicitamente accesso arbitrario alla cronologia. La cronologia della prima pagina,
la cronologia chat incorporata, il recupero dopo riavvio e i controlli su token/uso usano letture della coda
limitate. Le scansioni complete della trascrizione passano attraverso l’indice asincrono delle trascrizioni, che viene
I lettori della cronologia del Gateway devono evitare di materializzare l'intera trascrizione a meno che
la superficie non richieda esplicitamente accesso storico arbitrario. La cronologia della prima pagina,
la cronologia chat incorporata, il recupero dopo riavvio e i controlli su token/utilizzo usano letture
limitate dalla coda. Le scansioni complete della trascrizione passano dall'indice asincrono delle trascrizioni, che è
memorizzato in cache per percorso file più `mtimeMs`/`size` e condiviso tra lettori concorrenti.
---
## Posizioni su disco
Per agente, sull’host Gateway:
Per agente, sull'host Gateway:
- Archivio: `~/.openclaw/agents/<agentId>/sessions/sessions.json`
- Store: `~/.openclaw/agents/<agentId>/sessions/sessions.json`
- Trascrizioni: `~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl`
- Sessioni di topic Telegram: `.../<sessionId>-topic-<threadId>.jsonl`
- Sessioni argomento Telegram: `.../<sessionId>-topic-<threadId>.jsonl`
OpenClaw le risolve tramite `src/config/sessions.ts`.
---
## Manutenzione dell’archivio e controlli del disco
## Manutenzione dello store e controlli del disco
La persistenza delle sessioni ha controlli di manutenzione automatici (`session.maintenance`) per `sessions.json`, artefatti di trascrizione e sidecar di traiettoria:
La persistenza delle sessioni dispone di controlli automatici di manutenzione (`session.maintenance`) per `sessions.json`, artefatti di trascrizione e sidecar delle traiettorie:
- `mode`: `warn` (predefinito) o `enforce`
- `pruneAfter`: soglia di età per le voci obsolete (predefinito `30d`)
- `maxEntries`: limite di voci in `sessions.json` (predefinito `500`)
- `pruneAfter`: soglia di età delle voci obsolete (predefinito `30d`)
- `maxEntries`: limite delle voci in `sessions.json` (predefinito `500`)
- `resetArchiveRetention`: conservazione per gli archivi di trascrizione `*.reset.<timestamp>` (predefinito: uguale a `pruneAfter`; `false` disabilita la pulizia)
- `maxDiskBytes`: budget opzionale per la directory delle sessioni
- `highWaterBytes`: target opzionale dopo la pulizia (predefinito `80%` di `maxDiskBytes`)
Le normali scritture del Gateway passano attraverso uno writer di sessione per archivio che serializza le mutazioni in-process senza acquisire un lock di file a runtime. Gli helper di patch del percorso caldo prendono in prestito la cache mutabile validata mentre mantengono quello slot di writer, quindi i file `sessions.json` di grandi dimensioni non vengono clonati o riletti per ogni aggiornamento dei metadati. Il codice runtime dovrebbe preferire `updateSessionStore(...)` o `updateSessionStoreEntry(...)`; i salvataggi diretti dell’intero archivio sono strumenti di compatibilità e manutenzione offline. Quando un Gateway è raggiungibile, `openclaw sessions cleanup` e `openclaw agents delete` senza dry run delegano le mutazioni dell’archivio al Gateway, così la pulizia entra nella stessa coda di scrittura; `--store <path>` è il percorso esplicito di riparazione offline per la manutenzione diretta dei file. La pulizia `maxEntries` è ancora raggruppata per limiti di dimensioni di produzione, quindi un archivio può superare brevemente il limite configurato prima che la successiva pulizia high-water lo riscriva riducendolo. Le letture dell’archivio sessioni non potano né limitano le voci durante l’avvio del Gateway; usa le scritture o `openclaw sessions cleanup --enforce` per la pulizia. `openclaw sessions cleanup --enforce` applica comunque immediatamente il limite configurato.
Le scritture normali del Gateway passano attraverso un writer delle sessioni per store che serializza le mutazioni in-process senza acquisire un lock runtime sul file. Gli helper di patch sul percorso caldo prendono in prestito la cache mutabile validata mentre mantengono quello slot del writer, quindi i file `sessions.json` grandi non vengono clonati o riletti per ogni aggiornamento dei metadati. Il codice runtime deve preferire `updateSessionStore(...)` o `updateSessionStoreEntry(...)`; i salvataggi diretti dell'intero store sono strumenti di compatibilità e manutenzione offline. Quando un Gateway è raggiungibile, `openclaw sessions cleanup` e `openclaw agents delete` non dry-run delegano le mutazioni dello store al Gateway, così la pulizia entra nella stessa coda del writer; `--store <path>` è il percorso esplicito di riparazione offline per la manutenzione diretta dei file. La pulizia `maxEntries` è ancora eseguita in batch per limiti di dimensioni di produzione, quindi uno store può superare brevemente il limite configurato prima che la successiva pulizia high-water lo riscriva riportandolo sotto soglia. Le letture dello store delle sessioni non potano né limitano le voci durante l'avvio del Gateway; usa le scritture o `openclaw sessions cleanup --enforce` per la pulizia. `openclaw sessions cleanup --enforce` applica comunque immediatamente il limite configurato e pota vecchi artefatti di trascrizione, checkpoint e traiettorie non referenziati anche quando non è configurato alcun budget disco.
La manutenzione conserva i puntatori durevoli a conversazioni esterne, come sessioni di gruppo
e sessioni chat con ambito thread, ma le voci runtime sintetiche per Cron, hook,
Heartbeat, ACP e sub-agenti possono comunque essere rimosse quando superano il
budget configurato per età, conteggio o disco.
La manutenzione conserva puntatori durevoli a conversazioni esterne come sessioni di gruppo
e sessioni chat con scope di thread, ma le voci runtime sintetiche per Cron, hook,
Heartbeat, ACP e sub-agenti possono comunque essere rimosse quando superano
l'età, il conteggio o il budget disco configurati.
OpenClaw non crea più backup automatici con rotazione `sessions.json.bak.*` durante le scritture del Gateway. La chiave legacy `session.maintenance.rotateBytes` viene ignorata e `openclaw doctor --fix` la rimuove dalle configurazioni più vecchie.
OpenClaw non crea più backup automatici a rotazione `sessions.json.bak.*` durante le scritture del Gateway. La chiave legacy `session.maintenance.rotateBytes` viene ignorata e `openclaw doctor --fix` la rimuove dalle configurazioni più vecchie.
Le mutazioni delle trascrizioni usano un lock di scrittura di sessione sul file di trascrizione. L’acquisizione del lock attende fino a
Le mutazioni della trascrizione usano un lock di scrittura della sessione sul file di trascrizione. L'acquisizione del lock attende fino a
`session.writeLock.acquireTimeoutMs` prima di esporre un errore di sessione occupata; il valore predefinito è `60000`
ms. Aumentalo solo quando lavoro legittimo di preparazione, pulizia, Compaction o mirror della trascrizione contende
ms. Aumentalo solo quando attività legittime di preparazione, pulizia, Compaction o mirror della trascrizione contendono
più a lungo su macchine lente. Il rilevamento dei lock obsoleti e gli avvisi di durata massima restano criteri separati.
Ordine di applicazione per la pulizia del budget disco (`mode: "enforce"`):
1. Rimuovi prima gli artefatti archiviati più vecchi, le trascrizioni orfane o gli artefatti di traiettoria orfani.
1. Rimuovi prima gli artefatti più vecchi archiviati, di trascrizioni orfane o di traiettorie orfane.
2. Se ancora sopra il target, elimina le voci di sessione più vecchie e i relativi file di trascrizione/traiettoria.
3. Continua finché l’uso è pari o inferiore a `highWaterBytes`.
3. Continua finché l'utilizzo è pari o inferiore a `highWaterBytes`.
In `mode: "warn"`, OpenClaw segnala le potenziali espulsioni ma non modifica l’archivio/i file.
In `mode: "warn"`, OpenClaw segnala possibili espulsioni ma non modifica lo store/i file.
Esegui la manutenzione su richiesta:
@ -123,26 +123,26 @@ openclaw sessions cleanup --enforce
---
## Sessioni Cron e log di esecuzione
## Sessioni Cron e log delle esecuzioni
Anche le esecuzioni Cron isolate creano voci di sessione/trascrizioni, e hanno controlli di conservazione dedicati:
Anche le esecuzioni Cron isolate creano voci/trascrizioni di sessione e hanno controlli di conservazione dedicati:
- `cron.sessionRetention` (predefinito `24h`) pota le vecchie sessioni di esecuzione Cron isolate dall’archivio delle sessioni (`false` disabilita).
- `cron.runLog.maxBytes` + `cron.runLog.keepLines` potano i file `~/.openclaw/cron/runs/<jobId>.jsonl` (valori predefiniti: `2_000_000` byte e `2000` righe).
- `cron.sessionRetention` (predefinito `24h`) pota le vecchie sessioni di esecuzione Cron isolate dallo store delle sessioni (`false` disabilita).
- `cron.runLog.maxBytes` + `cron.runLog.keepLines` potano i file `~/.openclaw/cron/runs/<jobId>.jsonl` (predefiniti: `2_000_000` byte e `2000` righe).
Quando Cron forza la creazione di una nuova sessione di esecuzione isolata, sanifica la voce di sessione
`cron:<jobId>` precedente prima di scrivere la nuova riga. Trasporta preferenze sicure
come impostazioni di pensiero/veloce/verboso, etichette e override espliciti
di modello/auth selezionati dall’utente. Elimina il contesto conversazionale ambientale come
instradamento di canale/gruppo, criterio di invio o coda, elevazione, origine e binding runtime
ACP, così una nuova esecuzione isolata non può ereditare consegna obsoleta o
autorità runtime da un’esecuzione più vecchia.
Quando Cron forza la creazione di una nuova sessione di esecuzione isolata, sanifica la voce di sessione precedente
`cron:<jobId>` prima di scrivere la nuova riga. Trasporta preferenze sicure
come impostazioni thinking/fast/verbose, etichette e override espliciti
di modello/auth selezionati dall'utente. Scarta il contesto conversazionale ambientale come
routing di canale/gruppo, criteri di invio o coda, elevazione, origine e binding runtime ACP,
così una nuova esecuzione isolata non può ereditare consegna o autorità runtime
obsolete da un'esecuzione precedente.
---
## Chiavi di sessione (`sessionKey`)
Una `sessionKey` identifica _in quale contenitore di conversazione_ ti trovi (instradamento + isolamento).
Una `sessionKey` identifica _in quale contenitore di conversazione_ ti trovi (routing + isolamento).
Pattern comuni:
@ -150,7 +150,7 @@ Pattern comuni:
- Gruppo: `agent:<agentId>:<channel>:group:<id>`
- Stanza/canale (Discord/Slack): `agent:<agentId>:<channel>:channel:<id>` o `...:room:<id>`
- Cron: `cron:<job.id>`
- Webhook: `hook:<uuid>` (salvo override)
- Webhook: `hook:<uuid>` (se non sovrascritto)
Le regole canoniche sono documentate in [/concepts/session](/it/concepts/session).
@ -158,68 +158,69 @@ Le regole canoniche sono documentate in [/concepts/session](/it/concepts/session
## ID di sessione (`sessionId`)
Ogni `sessionKey` punta a una `sessionId` corrente (il file di trascrizione che continua la conversazione).
Ogni `sessionKey` punta a un `sessionId` corrente (il file di trascrizione che continua la conversazione).
Regole pratiche:
- **Reset** (`/new`, `/reset`) crea un nuovo `sessionId` per quella `sessionKey`.
- **Reset giornaliero** (predefinito 4:00 AM ora locale sull’host gateway) crea un nuovo `sessionId` al messaggio successivo dopo il confine di reset.
- **Scadenza per inattività** (`session.reset.idleMinutes` o legacy `session.idleMinutes`) crea un nuovo `sessionId` quando arriva un messaggio dopo la finestra di inattività. Quando sono configurati sia giornaliero sia inattività, vince quello che scade per primo.
- **Eventi di sistema** (Heartbeat, risvegli Cron, notifiche exec, bookkeeping del Gateway) possono mutare la riga della sessione ma non estendono la freschezza del reset giornaliero/per inattività. Il rollover del reset scarta gli avvisi di eventi di sistema in coda per la sessione precedente prima che venga costruito il prompt fresco.
- **Criterio di fork del genitore** usa il ramo attivo di PI quando crea un thread o un fork di subagente. Se quel ramo è troppo grande, OpenClaw avvia il figlio con contesto isolato invece di fallire o ereditare cronologia inutilizzabile. La policy di dimensionamento è automatica; la configurazione legacy `session.parentForkMaxTokens` viene rimossa da `openclaw doctor --fix`.
- **Reset giornaliero** (predefinito 4:00 AM ora locale sull'host gateway) crea un nuovo `sessionId` al messaggio successivo dopo il limite di reset.
- **Scadenza per inattività** (`session.reset.idleMinutes` o legacy `session.idleMinutes`) crea un nuovo `sessionId` quando arriva un messaggio dopo la finestra di inattività. Quando giornaliero + inattività sono entrambi configurati, vince quello che scade per primo.
- **Eventi di sistema** (Heartbeat, risvegli Cron, notifiche exec, bookkeeping del gateway) possono mutare la riga della sessione ma non estendono la freschezza del reset giornaliero/per inattività. Il rollover del reset scarta gli avvisi di eventi di sistema in coda per la sessione precedente prima che venga costruito il prompt fresco.
- **Criterio di fork del genitore** usa il branch attivo di PI quando crea un thread o un fork subagente. Se quel branch è troppo grande, OpenClaw avvia il figlio con contesto isolato invece di fallire o ereditare cronologia inutilizzabile. Il criterio di dimensionamento è automatico; la configurazione legacy `session.parentForkMaxTokens` viene rimossa da `openclaw doctor --fix`.
Dettaglio implementativo: la decisione avviene in `initSessionState()` in `src/auto-reply/reply/session.ts`.
---
## Schema dell’archivio sessioni (`sessions.json`)
## Schema dello store delle sessioni (`sessions.json`)
Il tipo valore dell’archivio è `SessionEntry` in `src/config/sessions.ts`.
Il tipo valore dello store è `SessionEntry` in `src/config/sessions.ts`.
Campi chiave (non esaustivi):
- `sessionId`: ID della trascrizione corrente (il nome file deriva da questo a meno che `sessionFile` non sia impostato)
- `sessionId`: id della trascrizione corrente (il nome file deriva da questo salvo che `sessionFile` sia impostato)
- `sessionStartedAt`: timestamp di inizio per il `sessionId` corrente; la freschezza del reset giornaliero
usa questo. Le righe legacy possono derivarlo dall’intestazione di sessione JSONL.
- `lastInteractionAt`: timestamp dell’ultima interazione reale utente/canale; la freschezza del reset per inattività
usa questo, quindi Heartbeat, Cron ed eventi exec non mantengono vive le sessioni. Le righe legacy senza questo campo ripiegano sull’ora di inizio sessione recuperata
per la freschezza per inattività.
- `updatedAt`: timestamp dell’ultima mutazione della riga dell’archivio, usato per elenchi, potatura e
bookkeeping. Non è l’autorità per la freschezza del reset giornaliero/per inattività.
usa questo. Le righe legacy possono derivarlo dall'header della sessione JSONL.
- `lastInteractionAt`: timestamp dell'ultima interazione reale utente/canale; la freschezza del reset per inattività
usa questo, così Heartbeat, Cron ed eventi exec non mantengono vive le sessioni.
Le righe legacy senza questo campo ricadono sull'ora di inizio sessione recuperata
per la freschezza dell'inattività.
- `updatedAt`: timestamp dell'ultima mutazione della riga dello store, usato per elenchi, potatura e
bookkeeping. Non è l'autorità per la freschezza del reset giornaliero/per inattività.
- `sessionFile`: override opzionale esplicito del percorso della trascrizione
- `chatType`: `direct | group | room` (aiuta le UI e il criterio di invio)
- `provider`, `subject`, `room`, `space`, `displayName`: metadati per l’etichettatura di gruppo/canale
- `chatType`: `direct | group | room` (aiuta le UI e i criteri di invio)
- `provider`, `subject`, `room`, `space`, `displayName`: metadati per l'etichettatura di gruppi/canali
- Toggle:
- `thinkingLevel`, `verboseLevel`, `reasoningLevel`, `elevatedLevel`
- `sendPolicy` (override per sessione)
- Selezione del modello:
- `providerOverride`, `modelOverride`, `authProfileOverride`
- Contatori di token (best-effort / dipendenti dal provider):
- Contatori dei token (best-effort / dipendenti dal provider):
- `inputTokens`, `outputTokens`, `totalTokens`, `contextTokens`
- `compactionCount`: quante volte la Compaction automatica è stata completata per questa chiave di sessione
- `memoryFlushAt`: timestamp dell’ultimo flush di memoria pre-Compaction
- `memoryFlushCompactionCount`: conteggio di Compaction quando l’ultimo flush è stato eseguito
- `memoryFlushAt`: timestamp dell'ultimo flush della memoria pre-Compaction
- `memoryFlushCompactionCount`: conteggio Compaction quando è stato eseguito l'ultimo flush
L’archivio è sicuro da modificare, ma il Gateway è l’autorità: può riscrivere o reidratare le voci mentre le sessioni sono in esecuzione.
Lo store è sicuro da modificare, ma il Gateway è l'autorità: può riscrivere o reidratare le voci mentre le sessioni vengono eseguite.
---
## Struttura della trascrizione (`*.jsonl`)
Le trascrizioni sono gestite dal `SessionManager` di `@mariozechner/pi-coding-agent`.
Le trascrizioni sono gestite da `SessionManager` di `@mariozechner/pi-coding-agent`.
Il file è JSONL:
- Prima riga: intestazione della sessione (`type: "session"`, include `id`, `cwd`, `timestamp`, `parentSession` opzionale)
- Prima riga: header della sessione (`type: "session"`, include `id`, `cwd`, `timestamp`, `parentSession` opzionale)
- Poi: voci di sessione con `id` + `parentId` (albero)
Tipi di voce rilevanti:
Tipi di voce notevoli:
- `message`: messaggi utente/assistant/toolResult
- `custom_message`: messaggi iniettati dal plugin che _entrano_ nel contesto del modello (possono essere nascosti dalla UI)
- `custom`: stato del plugin che _non_ entra nel contesto del modello
- `custom_message`: messaggi iniettati dall'estensione che _entrano_ nel contesto del modello (possono essere nascosti dalla UI)
- `custom`: stato dell'estensione che _non_ entra nel contesto del modello
- `compaction`: riepilogo di Compaction persistito con `firstKeptEntryId` e `tokensBefore`
- `branch_summary`: riepilogo persistito quando si naviga un ramo dell’albero
- `branch_summary`: riepilogo persistito quando si naviga un branch dell'albero
OpenClaw intenzionalmente **non** “corregge” le trascrizioni; il Gateway usa `SessionManager` per leggerle/scriverle.
@ -230,40 +231,40 @@ OpenClaw intenzionalmente **non** “corregge” le trascrizioni; il Gateway usa
Contano due concetti diversi:
1. **Finestra di contesto del modello**: limite rigido per modello (token visibili al modello)
2. **Contatori dell’archivio sessioni**: statistiche mobili scritte in `sessions.json` (usate per /status e dashboard)
2. **Contatori dello store delle sessioni**: statistiche mobili scritte in `sessions.json` (usate per /status e dashboard)
Se stai regolando i limiti:
- La finestra di contesto proviene dal catalogo dei modelli (e può essere sovrascritta tramite configurazione).
- `contextTokens` nell’archivio è un valore runtime di stima/reportistica; non trattarlo come una garanzia rigida.
- La finestra di contesto viene dal catalogo dei modelli (e può essere sovrascritta tramite configurazione).
- `contextTokens` nello store è un valore di stima/reporting runtime; non trattarlo come una garanzia rigorosa.
Per maggiori informazioni, consulta [/token-use](/it/reference/token-use).
Per saperne di più, vedi [/token-use](/it/reference/token-use).
---
## Compaction: che cos’è
## Compaction: cos'è
La Compaction riassume la conversazione più vecchia in una voce `compaction` persistita nella trascrizione e mantiene intatti i messaggi recenti.
Compaction riepiloga la conversazione più vecchia in una voce `compaction` persistita nella trascrizione e mantiene intatti i messaggi recenti.
Dopo la Compaction, i turni futuri vedono:
- Il riepilogo della Compaction
- Il riepilogo di Compaction
- I messaggi dopo `firstKeptEntryId`
La Compaction è **persistente** (a differenza della potatura delle sessioni). Vedi [/concepts/session-pruning](/it/concepts/session-pruning).
Compaction è **persistente** (a differenza della potatura delle sessioni). Vedi [/concepts/session-pruning](/it/concepts/session-pruning).
## Confini dei chunk di Compaction e abbinamento degli strumenti
## Limiti dei blocchi di Compaction e abbinamento degli strumenti
Quando OpenClaw divide una trascrizione lunga in chunk di Compaction, mantiene
le chiamate agli strumenti dell'assistente abbinate alle rispettive voci `toolResult`.
Quando OpenClaw divide una trascrizione lunga in blocchi di Compaction, mantiene
le chiamate agli strumenti dell'assistente abbinate alle voci `toolResult` corrispondenti.
- Se la divisione per quota di token cade tra una chiamata a uno strumento e il suo risultato, OpenClaw
sposta il confine al messaggio di chiamata allo strumento dell'assistente invece di separare
- Se la divisione basata sulla quota di token cade tra una chiamata a uno strumento e il suo risultato, OpenClaw
sposta il limite al messaggio di chiamata allo strumento dell'assistente invece di separare
la coppia.
- Se un blocco finale di risultato dello strumento farebbe altrimenti superare al chunk il target,
OpenClaw conserva quel blocco di strumento in sospeso e mantiene intatta la coda
- Se un blocco finale di risultati degli strumenti altrimenti porterebbe il blocco oltre l'obiettivo,
OpenClaw conserva quel blocco di strumenti in sospeso e mantiene intatta la coda
non riassunta.
- I blocchi di chiamata allo strumento interrotti o con errore non mantengono aperta una divisione in sospeso.
- I blocchi di chiamate agli strumenti interrotti o con errore non mantengono aperta una divisione in sospeso.
---
@ -271,11 +272,11 @@ le chiamate agli strumenti dell'assistente abbinate alle rispettive voci `toolRe
Nell'agente Pi incorporato, l'auto-Compaction si attiva in due casi:
1. **Recupero da overflow**: il modello restituisce un errore di overflow del contesto
1. **Ripristino da overflow**: il modello restituisce un errore di overflow del contesto
(`request_too_large`, `context length exceeded`, `input exceeds the maximum
number of tokens`, `input token count exceeds the maximum number of input
tokens`, `input is too long for the model`, `ollama error: context length
exceeded` e varianti simili con forma specifica del provider) → compatta → riprova.
exceeded` e varianti simili nella forma del provider) → compatta → riprova.
2. **Manutenzione della soglia**: dopo un turno riuscito, quando:
`contextTokens > contextWindow - reserveTokens`
@ -283,36 +284,36 @@ exceeded` e varianti simili con forma specifica del provider) → compatta → r
Dove:
- `contextWindow` è la finestra di contesto del modello
- `reserveTokens` è il margine riservato per prompt + il prossimo output del modello
- `reserveTokens` è il margine riservato per i prompt + il prossimo output del modello
Queste sono semantiche del runtime Pi (OpenClaw consuma gli eventi, ma Pi decide quando compattare).
OpenClaw può anche attivare una Compaction locale di preflight prima di aprire la prossima
esecuzione quando `agents.defaults.compaction.maxActiveTranscriptBytes` è impostato e il
file della trascrizione attiva raggiunge quella dimensione. Questa è una protezione basata sulla dimensione del file per il costo di
riapertura locale, non archiviazione grezza: OpenClaw esegue comunque la normale Compaction semantica,
OpenClaw può anche attivare una Compaction locale preliminare prima di aprire la
prossima esecuzione quando `agents.defaults.compaction.maxActiveTranscriptBytes` è impostato e il
file della trascrizione attiva raggiunge quella dimensione. Questa è una protezione sulla dimensione del file per il costo
di riapertura locale, non archiviazione grezza: OpenClaw esegue comunque la normale Compaction semantica,
e richiede `truncateAfterCompaction` affinché il riepilogo compattato possa diventare una
nuova trascrizione successiva.
nuova trascrizione successore.
Per le esecuzioni Pi incorporate, `agents.defaults.compaction.midTurnPrecheck.enabled: true`
aggiunge una protezione opzionale del ciclo degli strumenti. Dopo che un risultato dello strumento viene aggiunto e prima della
successiva chiamata al modello, OpenClaw stima la pressione sul prompt usando la stessa logica di budget
di preflight usata all'inizio del turno. Se il contesto non entra più, la protezione
non compatta dentro l'hook `transformContext` di Pi. Genera un segnale strutturato
di precheck a metà turno, interrompe l'invio del prompt corrente e lascia che il
ciclo di esecuzione esterno usi il percorso di recupero esistente: troncare i risultati degli strumenti sovradimensionati
aggiunge una protezione opzionale del ciclo degli strumenti. Dopo che un risultato di strumento viene aggiunto e prima della
prossima chiamata al modello, OpenClaw stima la pressione sul prompt usando la stessa logica di budget preliminare
usata all'inizio del turno. Se il contesto non rientra più, la protezione non
compatta dentro l'hook `transformContext` di Pi. Genera un segnale strutturato
di pre-controllo a metà turno, interrompe l'invio del prompt corrente e lascia che il
ciclo di esecuzione esterno usi il percorso di ripristino esistente: troncare risultati di strumenti sovradimensionati
quando basta, oppure attivare la modalità di Compaction configurata e riprovare. L'opzione
è disabilitata per impostazione predefinita e funziona con entrambe le modalità di Compaction `default` e `safeguard`,
inclusa la Compaction safeguard supportata da provider.
Questo è indipendente da `maxActiveTranscriptBytes`: la protezione basata sulla dimensione in byte viene eseguita
prima che un turno si apra, mentre il precheck a metà turno viene eseguito più tardi nel ciclo degli strumenti Pi incorporato
dopo che nuovi risultati degli strumenti sono stati aggiunti.
inclusa la Compaction `safeguard` supportata da provider.
Questo è indipendente da `maxActiveTranscriptBytes`: la protezione sulla dimensione in byte viene eseguita
prima dell'apertura di un turno, mentre il pre-controllo a metà turno viene eseguito più tardi nel ciclo degli strumenti Pi incorporato
dopo che sono stati aggiunti nuovi risultati degli strumenti.
---
## Impostazioni di Compaction (`reserveTokens`, `keepRecentTokens`)
Le impostazioni di Compaction di Pi si trovano nelle impostazioni Pi:
Le impostazioni di Compaction di Pi risiedono nelle impostazioni di Pi:
```json5
{
@ -324,32 +325,32 @@ Le impostazioni di Compaction di Pi si trovano nelle impostazioni Pi:
}
```
OpenClaw applica anche un limite minimo di sicurezza per le esecuzioni incorporate:
OpenClaw impone anche una soglia minima di sicurezza per le esecuzioni incorporate:
- Se `compaction.reserveTokens < reserveTokensFloor`, OpenClaw lo aumenta.
- Il limite minimo predefinito è `20000` token.
- Imposta `agents.defaults.compaction.reserveTokensFloor: 0` per disabilitare il limite minimo.
- Se è già più alto, OpenClaw lo lascia invariato.
- Il comando manuale `/compact` rispetta un `agents.defaults.compaction.keepRecentTokens`
esplicito e mantiene il punto di taglio della coda recente di Pi. Senza un budget di conservazione esplicito,
la Compaction manuale resta un checkpoint rigido e il contesto ricostruito parte dal
- Se `compaction.reserveTokens < reserveTokensFloor`, OpenClaw la aumenta.
- La soglia minima predefinita è `20000` token.
- Imposta `agents.defaults.compaction.reserveTokensFloor: 0` per disabilitare la soglia minima.
- Se è già più alta, OpenClaw la lascia invariata.
- `/compact` manuale rispetta un valore esplicito di `agents.defaults.compaction.keepRecentTokens`
e mantiene il punto di taglio della coda recente di Pi. Senza un budget di conservazione esplicito,
la Compaction manuale rimane un checkpoint rigido e il contesto ricostruito parte dal
nuovo riepilogo.
- Imposta `agents.defaults.compaction.midTurnPrecheck.enabled: true` per eseguire il
precheck opzionale del ciclo degli strumenti dopo i nuovi risultati degli strumenti e prima della successiva chiamata al modello.
Questo è solo un trigger; la generazione del riepilogo usa comunque il percorso di
pre-controllo opzionale del ciclo degli strumenti dopo i nuovi risultati degli strumenti e prima della prossima chiamata al modello.
È solo un trigger; la generazione del riepilogo usa comunque il percorso di
Compaction configurato. È indipendente da `maxActiveTranscriptBytes`, che è una
protezione basata sulla dimensione in byte della trascrizione attiva all'inizio del turno.
protezione sulla dimensione in byte della trascrizione attiva all'inizio del turno.
- Imposta `agents.defaults.compaction.maxActiveTranscriptBytes` su un valore in byte o
una stringa come `"20mb"` per eseguire la Compaction locale prima di un turno quando la trascrizione
attiva diventa grande. Questa protezione è attiva solo quando anche
`truncateAfterCompaction` è abilitato. Lascialo non impostato o impostalo a `0` per
una stringa come `"20mb"` per eseguire una Compaction locale prima di un turno quando la trascrizione attiva
diventa grande. Questa protezione è attiva solo quando
anche `truncateAfterCompaction` è abilitato. Lasciala non impostata o impostala a `0` per
disabilitarla.
- Quando `agents.defaults.compaction.truncateAfterCompaction` è abilitato,
OpenClaw ruota la trascrizione attiva in un successore JSONL compattato dopo la
Compaction. La vecchia trascrizione completa resta archiviata e collegata dal
checkpoint di Compaction invece di essere riscritta sul posto.
Motivo: lasciare abbastanza margine per la “manutenzione” multi-turno (come le scritture in memoria) prima che la Compaction diventi inevitabile.
Perché: lasciare abbastanza margine per la “manutenzione” multi-turno (come le scritture in memoria) prima che la Compaction diventi inevitabile.
Implementazione: `ensurePiCompactionReserveTokens()` in `src/agents/pi-settings.ts`
(chiamata da `src/agents/pi-embedded-runner.ts`).
@ -358,18 +359,18 @@ Implementazione: `ensurePiCompactionReserveTokens()` in `src/agents/pi-settings.
## Provider di Compaction collegabili
I Plugin possono registrare un provider di Compaction tramite `registerCompactionProvider()` nell'API del Plugin. Quando `agents.defaults.compaction.provider` è impostato sull'id di un provider registrato, il Plugin safeguard delega la sintesi a quel provider invece della pipeline integrata `summarizeInStages`.
I Plugin possono registrare un provider di Compaction tramite `registerCompactionProvider()` sull'API del Plugin. Quando `agents.defaults.compaction.provider` è impostato su un ID di provider registrato, l'estensione `safeguard` delega la sintesi a quel provider invece che alla pipeline integrata `summarizeInStages`.
- `provider`: id di un Plugin provider di Compaction registrato. Lascialo non impostato per la sintesi LLM predefinita.
- `provider`: ID di un Plugin provider di Compaction registrato. Lascialo non impostato per la sintesi LLM predefinita.
- Impostare un `provider` forza `mode: "safeguard"`.
- I provider ricevono le stesse istruzioni di Compaction e la stessa policy di conservazione degli identificatori del percorso integrato.
- Il safeguard conserva comunque il contesto del suffisso dei turni recenti e dei turni divisi dopo l'output del provider.
- La sintesi safeguard integrata ridistilla i riepiloghi precedenti con i nuovi messaggi
invece di preservare letteralmente l'intero riepilogo precedente.
- La modalità safeguard abilita per impostazione predefinita gli audit di qualità del riepilogo; imposta
`qualityGuard.enabled: false` per saltare il comportamento di nuovo tentativo in caso di output malformato.
- Il `safeguard` conserva comunque il contesto dei turni recenti e del suffisso del turno diviso dopo l'output del provider.
- La sintesi `safeguard` integrata ridistilla i riepiloghi precedenti con i nuovi messaggi
invece di conservare testualmente l'intero riepilogo precedente.
- La modalità `safeguard` abilita per impostazione predefinita gli audit della qualità dei riepiloghi; imposta
`qualityGuard.enabled: false` per saltare il comportamento di ripetizione in caso di output malformato.
- Se il provider fallisce o restituisce un risultato vuoto, OpenClaw ripiega automaticamente sulla sintesi LLM integrata.
- I segnali di interruzione/timeout vengono rilanciati (non inghiottiti) per rispettare l'annullamento del chiamante.
- I segnali di interruzione/timeout vengono rilanciati (non assorbiti) per rispettare l'annullamento del chiamante.
Fonte: `src/plugins/compaction-provider.ts`, `src/agents/pi-hooks/compaction-safeguard.ts`.
@ -377,18 +378,18 @@ Fonte: `src/plugins/compaction-provider.ts`, `src/agents/pi-hooks/compaction-saf
## Superfici visibili all'utente
Puoi osservare la Compaction e lo stato della sessione tramite:
Puoi osservare Compaction e stato della sessione tramite:
- `/status` (in qualsiasi sessione di chat)
- `openclaw status` (CLI)
- `openclaw sessions` / `sessions --json`
- Modalità dettagliata: `🧹 Auto-compaction complete` + conteggio delle Compaction
- Modalità verbosa: `🧹 Auto-compaction complete` + conteggio delle Compaction
---
## Manutenzione silenziosa (`NO_REPLY`)
OpenClaw supporta turni “silenziosi” per attività in background in cui l'utente non dovrebbe vedere output intermedio.
OpenClaw supporta turni “silenziosi” per attività in background in cui l'utente non dovrebbe vedere output intermedi.
Convenzione:
@ -397,24 +398,24 @@ Convenzione:
- OpenClaw lo rimuove/sopprime nel livello di consegna.
- La soppressione del token silenzioso esatto non distingue tra maiuscole e minuscole, quindi `NO_REPLY` e
`no_reply` contano entrambi quando l'intero payload è solo il token silenzioso.
- Questo serve solo per veri turni in background/senza consegna; non è una scorciatoia per
normali richieste utente operative.
- Questo è solo per veri turni in background/senza consegna; non è una scorciatoia per
normali richieste utente azionabili.
A partire da `2026.1.10`, OpenClaw sopprime anche lo **streaming di bozza/digitazione** quando un
chunk parziale inizia con `NO_REPLY`, quindi le operazioni silenziose non espongono output parziale
a metà turno.
A partire da `2026.1.10`, OpenClaw sopprime anche lo **streaming di bozze/digitazione** quando un
blocco parziale inizia con `NO_REPLY`, così le operazioni silenziose non perdono output
parziale a metà turno.
---
## "Flush della memoria" pre-Compaction (implementato)
Obiettivo: prima che avvenga l'auto-Compaction, eseguire un turno agentico silenzioso che scriva lo stato durevole
su disco (ad es. `memory/YYYY-MM-DD.md` nello spazio di lavoro dell'agente) in modo che la Compaction non possa
Obiettivo: prima che avvenga l'auto-Compaction, eseguire un turno agentico silenzioso che scrive lo stato durevole
su disco (ad esempio `memory/YYYY-MM-DD.md` nello spazio di lavoro dell'agente) così che la Compaction non possa
cancellare contesto critico.
OpenClaw usa l'approccio **flush pre-soglia**:
1. Monitora l'utilizzo del contesto della sessione.
1. Monitora l'uso del contesto della sessione.
2. Quando supera una “soglia morbida” (sotto la soglia di Compaction di Pi), esegui una direttiva silenziosa
“scrivi la memoria ora” per l'agente.
3. Usa il token silenzioso esatto `NO_REPLY` / `no_reply` così l'utente non vede
@ -426,7 +427,7 @@ Configurazione (`agents.defaults.compaction.memoryFlush`):
- `model` (override opzionale esatto provider/modello per il turno di flush, ad esempio `ollama/qwen3:8b`)
- `softThresholdTokens` (predefinito: `4000`)
- `prompt` (messaggio utente per il turno di flush)
- `systemPrompt` (prompt di sistema extra aggiunto per il turno di flush)
- `systemPrompt` (prompt di sistema aggiuntivo aggiunto per il turno di flush)
Note:
@ -440,20 +441,20 @@ Note:
- Il flush viene saltato quando lo spazio di lavoro della sessione è in sola lettura (`workspaceAccess: "ro"` o `"none"`).
- Vedi [Memoria](/it/concepts/memory) per il layout dei file dello spazio di lavoro e i pattern di scrittura.
Pi espone anche un hook `session_before_compact` nell'API del Plugin, ma la logica di
flush di OpenClaw oggi vive sul lato Gateway.
Pi espone anche un hook `session_before_compact` nell'API dell'estensione, ma oggi la logica di
flush di OpenClaw vive sul lato Gateway.
---
## Checklist per la risoluzione dei problemi
- Chiave di sessione errata? Inizia da [/concepts/session](/it/concepts/session) e conferma il `sessionKey` in `/status`.
- Incompatibilità tra archivio e trascrizione? Conferma l'host Gateway e il percorso dell'archivio da `openclaw status`.
- Mancata corrispondenza tra store e trascrizione? Conferma l'host Gateway e il percorso dello store da `openclaw status`.
- Troppa Compaction? Controlla:
- finestra di contesto del modello (troppo piccola)
- impostazioni di Compaction (`reserveTokens` troppo alto per la finestra del modello può causare Compaction anticipata)
- eccesso nei risultati degli strumenti: abilita/regola la potatura della sessione
- I turni silenziosi perdono output? Conferma che la risposta inizi con `NO_REPLY` (token esatto senza distinzione tra maiuscole e minuscole) e di usare una build che include la correzione della soppressione dello streaming.
- crescita eccessiva dei risultati degli strumenti: abilita/regola la potatura della sessione
- Turni silenziosi che trapelano? Conferma che la risposta inizi con `NO_REPLY` (token esatto senza distinzione tra maiuscole/minuscole) e che tu sia su una build che include la correzione della soppressione dello streaming.
## Correlati