diff --git a/docs/it/concepts/dreaming.md b/docs/it/concepts/dreaming.md index ca024ebbc..e35aa950b 100644 --- a/docs/it/concepts/dreaming.md +++ b/docs/it/concepts/dreaming.md @@ -1,140 +1,135 @@ --- read_when: - Vuoi che la promozione della memoria venga eseguita automaticamente - - Vuoi capire cosa fa ogni fase di Dreaming - - Vuoi regolare il consolidamento senza inquinare MEMORY.md -summary: Consolidamento della memoria in background con fasi light, deep e REM più un Diario dei sogni -title: Dreaming (sperimentale) + - Vuoi capire cosa fa ogni fase del Dreaming + - Vuoi regolare il consolidamento senza inquinare `MEMORY.md` +summary: Consolidamento della memoria in background con fasi leggere, profonde e REM, più un Diario dei sogni +title: Dreaming x-i18n: - generated_at: "2026-04-15T08:18:06Z" + generated_at: "2026-04-15T14:40:32Z" model: gpt-5.4 provider: openai - source_hash: 5882a5068f2eabe54ca9893184e5385330a432b921870c38626399ce11c31e25 + source_hash: a5bcaec80f62e7611ed533094ef1917bd72c885f57252824db910e1f0496adc6 source_path: concepts/dreaming.md workflow: 15 --- -# Dreaming (sperimentale) +# Dreaming Dreaming è il sistema di consolidamento della memoria in background in `memory-core`. -Aiuta OpenClaw a spostare segnali forti a breve termine nella memoria durevole mantenendo -il processo spiegabile e verificabile. +Aiuta OpenClaw a spostare forti segnali della memoria a breve termine in una memoria durevole, mantenendo al tempo stesso il processo spiegabile e verificabile. -Dreaming è **facoltativo** ed è disattivato per impostazione predefinita. +Dreaming è **opt-in** ed è disabilitato per impostazione predefinita. ## Cosa scrive Dreaming Dreaming mantiene due tipi di output: -- **Stato macchina** in `memory/.dreams/` (archivio di richiamo, segnali di fase, checkpoint di ingestione, lock). -- **Output leggibile da esseri umani** in `DREAMS.md` (o `dreams.md` esistente) e file di report di fase facoltativi in `memory/dreaming//YYYY-MM-DD.md`. +- **Stato della macchina** in `memory/.dreams/` (archivio di richiamo, segnali di fase, checkpoint di ingestione, lock). +- **Output leggibile dall'uomo** in `DREAMS.md` (o `dreams.md` esistente) e file di report di fase opzionali in `memory/dreaming//YYYY-MM-DD.md`. La promozione a lungo termine continua a scrivere solo in `MEMORY.md`. -## Modello di fase +## Modello delle fasi Dreaming usa tre fasi cooperative: | Fase | Scopo | Scrittura durevole | | ----- | ----------------------------------------- | ------------------ | | Light | Ordina e prepara il materiale recente a breve termine | No | -| Deep | Valuta e promuove i candidati durevoli | Sì (`MEMORY.md`) | +| Deep | Assegna un punteggio e promuove i candidati durevoli | Sì (`MEMORY.md`) | | REM | Riflette su temi e idee ricorrenti | No | -Queste fasi sono dettagli interni di implementazione, non "modalità" -separate configurabili dall'utente. +Queste fasi sono dettagli interni di implementazione, non "modalità" separate configurabili dall'utente. ### Fase Light -La fase Light acquisisce segnali recenti della memoria giornaliera e tracce di richiamo, li deduplica -e prepara righe candidate. +La fase Light acquisisce segnali recenti della memoria giornaliera e tracce di richiamo, li deduplica e prepara righe candidate. - Legge dallo stato di richiamo a breve termine, dai file recenti della memoria giornaliera e dalle trascrizioni di sessione redatte quando disponibili. - Scrive un blocco gestito `## Light Sleep` quando l'archiviazione include output inline. -- Registra segnali di rinforzo per la successiva classificazione deep. +- Registra segnali di rinforzo per il ranking deep successivo. - Non scrive mai in `MEMORY.md`. ### Fase Deep La fase Deep decide cosa diventa memoria a lungo termine. -- Classifica i candidati usando punteggi ponderati e soglie di accesso. +- Classifica i candidati usando punteggio pesato e soglie di accesso. - Richiede il superamento di `minScore`, `minRecallCount` e `minUniqueQueries`. -- Reidrata gli snippet dai file giornalieri live prima di scrivere, quindi gli snippet obsoleti/eliminati vengono saltati. +- Reidrata gli snippet dai file giornalieri attivi prima della scrittura, quindi gli snippet obsoleti/eliminati vengono saltati. - Aggiunge le voci promosse a `MEMORY.md`. -- Scrive un riepilogo `## Deep Sleep` in `DREAMS.md` e facoltativamente scrive `memory/dreaming/deep/YYYY-MM-DD.md`. +- Scrive un riepilogo `## Deep Sleep` in `DREAMS.md` e opzionalmente scrive `memory/dreaming/deep/YYYY-MM-DD.md`. ### Fase REM La fase REM estrae pattern e segnali riflessivi. -- Costruisce riepiloghi di temi e riflessioni dalle recenti tracce a breve termine. +- Costruisce riepiloghi di temi e riflessioni a partire da tracce recenti a breve termine. - Scrive un blocco gestito `## REM Sleep` quando l'archiviazione include output inline. -- Registra segnali di rinforzo REM usati dalla classificazione deep. +- Registra segnali di rinforzo REM usati dal ranking deep. - Non scrive mai in `MEMORY.md`. -## Acquisizione delle trascrizioni di sessione +## Ingestione delle trascrizioni di sessione -Dreaming può acquisire trascrizioni di sessione redatte nel corpus di dreaming. Quando -le trascrizioni sono disponibili, vengono inviate alla fase Light insieme ai segnali della -memoria giornaliera e alle tracce di richiamo. I contenuti personali e sensibili vengono redatti -prima dell'acquisizione. +Dreaming può acquisire trascrizioni di sessione redatte nel corpus di Dreaming. Quando +le trascrizioni sono disponibili, vengono passate alla fase Light insieme ai +segnali della memoria giornaliera e alle tracce di richiamo. Il contenuto personale e sensibile viene redatto +prima dell'ingestione. -## Dream Diary +## Diario dei sogni -Dreaming mantiene anche un **Dream Diary** narrativo in `DREAMS.md`. -Dopo che ogni fase ha materiale sufficiente, `memory-core` esegue un turno in background -best-effort del sottoagente (usando il modello di runtime predefinito) e aggiunge una breve voce del diario. +Dreaming mantiene anche un **Diario dei sogni** narrativo in `DREAMS.md`. +Dopo che ogni fase ha raccolto materiale sufficiente, `memory-core` esegue un turno in background best-effort di un subagent (usando il modello di runtime predefinito) e aggiunge una breve voce di diario. Questo diario è destinato alla lettura umana nella UI Dreams, non è una fonte di promozione. -Gli artefatti di diario/report generati da Dreaming sono esclusi dalla -promozione a breve termine. Solo gli snippet di memoria fondati possono essere promossi in +Gli artifact di diario/report generati da Dreaming sono esclusi dalla +promozione a breve termine. Solo gli snippet di memoria fondati sono idonei alla promozione in `MEMORY.md`. -Esiste anche un percorso di backfill storico fondato per il lavoro di revisione e recupero: +Esiste anche un percorso di backfill storico fondato per attività di revisione e recupero: -- `memory rem-harness --path ... --grounded` mostra in anteprima l'output del diario fondato da note storiche `YYYY-MM-DD.md`. -- `memory rem-backfill --path ...` scrive voci reversibili del diario fondato in `DREAMS.md`. -- `memory rem-backfill --path ... --stage-short-term` prepara candidati durevoli fondati nello stesso archivio di evidenze a breve termine già usato dalla normale fase deep. -- `memory rem-backfill --rollback` e `--rollback-short-term` rimuovono questi artefatti di backfill preparati senza toccare le normali voci del diario o il richiamo live a breve termine. +- `memory rem-harness --path ... --grounded` mostra in anteprima l'output del diario fondato dalle note storiche `YYYY-MM-DD.md`. +- `memory rem-backfill --path ...` scrive voci di diario fondate e reversibili in `DREAMS.md`. +- `memory rem-backfill --path ... --stage-short-term` prepara candidati durevoli fondati nello stesso archivio di evidenze a breve termine che la normale fase Deep usa già. +- `memory rem-backfill --rollback` e `--rollback-short-term` rimuovono questi artifact di backfill preparati senza toccare le normali voci di diario o il richiamo attivo a breve termine. -La Control UI espone lo stesso flusso di backfill/reset del diario così puoi ispezionare -i risultati nella scena Dreams prima di decidere se i candidati fondati +La UI di controllo espone lo stesso flusso di backfill/reset del diario così puoi ispezionare i +risultati nella scena Dreams prima di decidere se i candidati fondati meritano la promozione. La scena mostra anche un percorso fondato distinto così puoi vedere -quali voci a breve termine preparate provengono dal replay storico, quali elementi promossi -sono stati guidati dal fondamento e cancellare solo le voci preparate esclusivamente fondate senza -toccare il normale stato live a breve termine. +quali voci preparate a breve termine provengono dalla riproduzione storica, quali elementi promossi +sono stati guidati dal grounded e cancellare solo le voci preparate esclusivamente grounded senza +toccare il normale stato attivo a breve termine. -## Segnali di classificazione deep +## Segnali di ranking Deep -La classificazione deep usa sei segnali base ponderati più il rinforzo di fase: +Il ranking Deep usa sei segnali di base pesati più il rinforzo di fase: -| Segnale | Peso | Descrizione | -| ------------------ | ---- | -------------------------------------------------- | -| Frequenza | 0.24 | Quanti segnali a breve termine ha accumulato la voce | -| Rilevanza | 0.30 | Qualità media di recupero per la voce | -| Diversità delle query | 0.15 | Contesti distinti di query/giorno che l'hanno fatta emergere | -| Recenza | 0.15 | Punteggio di freschezza con decadimento temporale | -| Consolidamento | 0.10 | Forza di ricorrenza su più giorni | -| Ricchezza concettuale | 0.06 | Densità di tag concettuali da snippet/percorso | +| Segnale | Peso | Descrizione | +| ------------------- | ------ | -------------------------------------------------- | +| Frequenza | 0.24 | Quanti segnali a breve termine ha accumulato la voce | +| Rilevanza | 0.30 | Qualità media di recupero per la voce | +| Diversità delle query | 0.15 | Contesti distinti di query/giorno in cui è emersa | +| Recenza | 0.15 | Punteggio di freschezza con decadimento temporale | +| Consolidamento | 0.10 | Forza di ricorrenza su più giorni | +| Ricchezza concettuale | 0.06 | Densità di tag concettuali da snippet/percorso | -I riscontri delle fasi Light e REM aggiungono un piccolo incremento con decadimento di recenza da +Le occorrenze delle fasi Light e REM aggiungono un piccolo incremento con decadimento di recenza da `memory/.dreams/phase-signals.json`. ## Pianificazione -Quando è abilitato, `memory-core` gestisce automaticamente un job Cron per una sweep completa -di dreaming. Ogni sweep esegue le fasi in ordine: light -> REM -> deep. +Quando è abilitato, `memory-core` gestisce automaticamente un job Cron per una sweep completa di Dreaming. Ogni sweep esegue le fasi in ordine: light -> REM -> deep. -Comportamento di cadenza predefinito: +Comportamento della cadenza predefinita: -| Impostazione | Predefinito | -| ------------------- | ----------- | +| Impostazione | Predefinito | +| -------------------- | ----------- | | `dreaming.frequency` | `0 3 * * *` | ## Avvio rapido -Abilita dreaming: +Abilita Dreaming: ```json { @@ -152,7 +147,7 @@ Abilita dreaming: } ``` -Abilita dreaming con una cadenza di sweep personalizzata: +Abilita Dreaming con una cadenza di sweep personalizzata: ```json { @@ -192,8 +187,8 @@ openclaw memory promote --limit 5 openclaw memory status --deep ``` -Il comando manuale `memory promote` usa per impostazione predefinita le soglie della fase deep, salvo override -tramite flag CLI. +`memory promote` manuale usa per impostazione predefinita le soglie della fase Deep, salvo override +con flag CLI. Spiega perché un candidato specifico verrebbe o non verrebbe promosso: @@ -202,7 +197,7 @@ openclaw memory promote-explain "router vlan" openclaw memory promote-explain "router vlan" --json ``` -Mostra in anteprima riflessioni REM, verità candidate e output della promozione deep senza +Mostra in anteprima riflessioni REM, verità candidate e output di promozione Deep senza scrivere nulla: ```bash @@ -219,26 +214,26 @@ Tutte le impostazioni si trovano in `plugins.entries.memory-core.config.dreaming | `enabled` | `false` | | `frequency` | `0 3 * * *` | -La policy di fase, le soglie e il comportamento di archiviazione sono dettagli interni di implementazione -(non configurazione esposta all'utente). +Criteri di fase, soglie e comportamento di archiviazione sono dettagli interni di implementazione +(non configurazione rivolta all'utente). -Vedi [Riferimento della configurazione Memory](/it/reference/memory-config#dreaming-experimental) +Vedi [Riferimento alla configurazione della memoria](/it/reference/memory-config#dreaming) per l'elenco completo delle chiavi. ## UI Dreams -Quando è abilitato, la scheda **Dreams** del Gateway mostra: +Quando è abilitata, la scheda **Dreams** del Gateway mostra: -- stato corrente di abilitazione di dreaming +- stato attuale di abilitazione di Dreaming - stato a livello di fase e presenza di sweep gestita -- conteggi di breve termine, fondati, segnali e promossi-oggi -- tempistica della prossima esecuzione pianificata -- un percorso Scene fondato distinto per le voci di replay storico preparate -- un lettore Dream Diary espandibile supportato da `doctor.memory.dreamDiary` +- conteggi di elementi a breve termine, grounded, segnali e promossi oggi +- orario della prossima esecuzione pianificata +- un percorso grounded distinto nella scena per le voci preparate dalla riproduzione storica +- un lettore espandibile del Diario dei sogni basato su `doctor.memory.dreamDiary` ## Correlati -- [Memory](/it/concepts/memory) -- [Memory Search](/it/concepts/memory-search) -- [memory CLI](/cli/memory) -- [Riferimento della configurazione Memory](/it/reference/memory-config) +- [Memoria](/it/concepts/memory) +- [Ricerca nella memoria](/it/concepts/memory-search) +- [CLI memory](/cli/memory) +- [Riferimento alla configurazione della memoria](/it/reference/memory-config) diff --git a/docs/it/concepts/experimental-features.md b/docs/it/concepts/experimental-features.md new file mode 100644 index 000000000..7d39a151d --- /dev/null +++ b/docs/it/concepts/experimental-features.md @@ -0,0 +1,54 @@ +--- +read_when: + - Vedi una chiave di configurazione `.experimental` e vuoi sapere se è stabile + - Vuoi provare le funzionalità di runtime in anteprima senza confonderle con i valori predefiniti normali + - Vuoi un unico posto in cui trovare i flag sperimentali attualmente documentati +summary: Cosa significano i flag sperimentali in OpenClaw e quali sono attualmente documentati +title: Funzionalità sperimentali +x-i18n: + generated_at: "2026-04-15T14:40:33Z" + model: gpt-5.4 + provider: openai + source_hash: 2d1c7b3d4cd56ef8a0bdab1deb9918e9b2c9a33f956d63193246087f8633dcf3 + source_path: concepts/experimental-features.md + workflow: 15 +--- + +# Funzionalità sperimentali + +Le funzionalità sperimentali in OpenClaw sono **superfici di anteprima su base opt-in**. Sono +dietro flag espliciti perché hanno ancora bisogno di utilizzo nel mondo reale prima di +meritare un valore predefinito stabile o un contratto pubblico duraturo. + +Trattale in modo diverso dalla configurazione normale: + +- Tienile **disattivate per impostazione predefinita** a meno che la documentazione correlata non ti dica di provarne una. +- Aspettati che **struttura e comportamento cambino** più rapidamente rispetto alla configurazione stabile. +- Preferisci prima il percorso stabile quando ne esiste già uno. +- Se stai distribuendo OpenClaw su larga scala, testa i flag sperimentali in un ambiente + più piccolo prima di integrarli in una baseline condivisa. + +## Flag attualmente documentati + +| Superficie | Chiave | Usala quando | Altro | +| ------------------------ | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | +| Runtime del modello locale | `agents.defaults.experimental.localModelLean` | Un backend locale più piccolo o più rigoroso va in difficoltà con la superficie completa degli strumenti predefiniti di OpenClaw | [Modelli locali](/it/gateway/local-models) | +| Ricerca nella memoria | `agents.defaults.memorySearch.experimental.sessionMemory` | Vuoi che `memory_search` indicizzi le trascrizioni delle sessioni precedenti e accetti il costo aggiuntivo di archiviazione/indicizzazione | [Riferimento della configurazione della memoria](/it/reference/memory-config#session-memory-search-experimental) | +| Strumento di pianificazione strutturata | `tools.experimental.planTool` | Vuoi che lo strumento strutturato `update_plan` sia esposto per il monitoraggio del lavoro in più fasi in runtime e interfacce compatibili | [Riferimento della configurazione del Gateway](/it/gateway/configuration-reference#toolsexperimental) | + +## Modalità lean del modello locale + +`agents.defaults.experimental.localModelLean: true` è una valvola di sfogo +per configurazioni di modelli locali più deboli. Riduce strumenti predefiniti pesanti come +`browser`, `cron` e `message` in modo che la struttura del prompt sia più piccola e meno fragile +per backend compatibili con OpenAI con contesto ridotto o più rigorosi. + +Questa intenzionalmente **non** è la modalità normale. Se il tuo backend gestisce il +runtime completo senza problemi, lascia questa opzione disattivata. + +## Sperimentale non significa nascosto + +Se una funzionalità è sperimentale, OpenClaw dovrebbe dirlo chiaramente nella documentazione e nel +percorso di configurazione stesso. Quello che **non** dovrebbe fare è introdurre di nascosto un comportamento +di anteprima in una manopola predefinita dall'aspetto stabile e fingere che sia normale. È così che le +superfici di configurazione diventano disordinate. diff --git a/docs/it/concepts/memory-search.md b/docs/it/concepts/memory-search.md index 526f38537..500c49ded 100644 --- a/docs/it/concepts/memory-search.md +++ b/docs/it/concepts/memory-search.md @@ -1,15 +1,15 @@ --- read_when: - - Vuoi capire come funziona `memory_search` - - Vuoi scegliere un provider di embedding + - Vuoi capire come funziona memory_search + - Vuoi scegliere un provider di embeddings - Vuoi ottimizzare la qualità della ricerca summary: Come la ricerca nella memoria trova note pertinenti usando embeddings e recupero ibrido title: Ricerca nella memoria x-i18n: - generated_at: "2026-04-12T23:28:06Z" + generated_at: "2026-04-15T14:40:29Z" model: gpt-5.4 provider: openai - source_hash: 71fde251b7d2dc455574aa458e7e09136f30613609ad8dafeafd53b2729a0310 + source_hash: f5757aa8fe8f7fec30ef5c826f72230f591ce4cad591d81a091189d50d4262ed source_path: concepts/memory-search.md workflow: 15 --- @@ -17,13 +17,12 @@ x-i18n: # Ricerca nella memoria `memory_search` trova note pertinenti dai tuoi file di memoria, anche quando la -formulazione differisce dal testo originale. Funziona indicizzando la memoria in -piccoli blocchi e cercandoli tramite embeddings, parole chiave o entrambi. +formulazione differisce dal testo originale. Funziona indicizzando la memoria in piccoli +blocchi e cercandoli usando embeddings, parole chiave o entrambi. -## Avvio rapido +## Guida rapida -Se hai configurato una chiave API OpenAI, Gemini, Voyage o Mistral, la ricerca -nella memoria funziona automaticamente. Per impostare esplicitamente un provider: +Se hai un abbonamento a GitHub Copilot, oppure una chiave API OpenAI, Gemini, Voyage o Mistral configurata, la ricerca nella memoria funziona automaticamente. Per impostare esplicitamente un provider: ```json5 { @@ -42,15 +41,16 @@ node-llama-cpp). ## Provider supportati -| Provider | ID | Richiede chiave API | Note | -| -------- | --------- | ------------------- | ---------------------------------------------------- | -| OpenAI | `openai` | Sì | Rilevato automaticamente, veloce | -| Gemini | `gemini` | Sì | Supporta l'indicizzazione di immagini/audio | -| Voyage | `voyage` | Sì | Rilevato automaticamente | -| Mistral | `mistral` | Sì | Rilevato automaticamente | -| Bedrock | `bedrock` | No | Rilevato automaticamente quando la catena di credenziali AWS si risolve | -| Ollama | `ollama` | No | Locale, deve essere impostato esplicitamente | -| Local | `local` | No | Modello GGUF, download di ~0,6 GB | +| Provider | ID | Richiede chiave API | Note | +| -------------- | ---------------- | ------------------- | ---------------------------------------------------- | +| Bedrock | `bedrock` | No | Rilevato automaticamente quando la catena di credenziali AWS si risolve | +| Gemini | `gemini` | Sì | Supporta l'indicizzazione di immagini/audio | +| GitHub Copilot | `github-copilot` | No | Rilevato automaticamente, usa l'abbonamento Copilot | +| Local | `local` | No | Modello GGUF, download di ~0,6 GB | +| Mistral | `mistral` | Sì | Rilevato automaticamente | +| Ollama | `ollama` | No | Locale, deve essere impostato esplicitamente | +| OpenAI | `openai` | Sì | Rilevato automaticamente, veloce | +| Voyage | `voyage` | Sì | Rilevato automaticamente | ## Come funziona la ricerca @@ -67,25 +67,24 @@ flowchart LR M --> R["Top Results"] ``` -- **Ricerca vettoriale** trova note con significato simile ("gateway host" - corrisponde a "la macchina che esegue OpenClaw"). -- **Ricerca per parole chiave BM25** trova corrispondenze esatte (ID, stringhe - di errore, chiavi di configurazione). +- **La ricerca vettoriale** trova note con significato simile ("gateway host" corrisponde + a "la macchina che esegue OpenClaw"). +- **La ricerca per parole chiave BM25** trova corrispondenze esatte (ID, stringhe di errore, chiavi + di configurazione). -Se è disponibile un solo percorso (nessun embedding o nessun FTS), l'altro non viene usato. +Se è disponibile un solo percorso (nessun embeddings o nessun FTS), viene eseguito da solo l'altro. -Quando gli embeddings non sono disponibili, OpenClaw usa comunque il ranking lessicale sui risultati FTS invece di ripiegare solo sull'ordinamento grezzo per corrispondenza esatta. Questa modalità degradata dà priorità ai blocchi con una copertura più forte dei termini della query e percorsi file pertinenti, mantenendo utile il richiamo anche senza `sqlite-vec` o un provider di embedding. +Quando gli embeddings non sono disponibili, OpenClaw usa comunque il ranking lessicale sui risultati FTS invece di ripiegare solo sull'ordinamento grezzo per corrispondenza esatta. Questa modalità degradata aumenta il peso dei blocchi con una copertura più forte dei termini della query e percorsi file pertinenti, mantenendo utile il richiamo anche senza `sqlite-vec` o un provider di embeddings. ## Migliorare la qualità della ricerca -Due funzionalità opzionali aiutano quando hai una cronologia note molto ampia: +Due funzionalità opzionali aiutano quando hai una cronologia di note molto ampia: ### Decadimento temporale -Le note vecchie perdono gradualmente peso nel ranking, così le informazioni più -recenti emergono per prime. Con l'emivita predefinita di 30 giorni, una nota -del mese scorso ottiene il 50% del suo peso originale. I file permanenti come -`MEMORY.md` non subiscono mai decadimento. +Le note vecchie perdono gradualmente peso nel ranking, così le informazioni recenti emergono per prime. +Con l'emivita predefinita di 30 giorni, una nota del mese scorso ottiene un punteggio pari al 50% del +suo peso originale. I file evergreen come `MEMORY.md` non vengono mai penalizzati. Abilita il decadimento temporale se il tuo agente ha mesi di note giornaliere e @@ -94,13 +93,12 @@ le informazioni obsolete continuano a superare nel ranking il contesto recente. ### MMR (diversità) -Riduce i risultati ridondanti. Se cinque note menzionano tutte la stessa -configurazione del router, MMR assicura che i risultati principali coprano temi -diversi invece di ripetersi. +Riduce i risultati ridondanti. Se cinque note menzionano tutte la stessa configurazione del router, MMR +fa in modo che i risultati principali coprano argomenti diversi invece di ripetersi. -Abilita MMR se `memory_search` continua a restituire frammenti quasi duplicati -da note giornaliere diverse. +Abilita MMR se `memory_search` continua a restituire frammenti quasi duplicati da +note giornaliere diverse. ### Abilitare entrambi @@ -125,29 +123,29 @@ da note giornaliere diverse. ## Memoria multimodale Con Gemini Embedding 2, puoi indicizzare immagini e file audio insieme al -Markdown. Le query di ricerca restano testuali, ma corrispondono a contenuti -visivi e audio. Consulta il [riferimento della configurazione della memoria](/it/reference/memory-config) per la configurazione. +Markdown. Le query di ricerca restano testuali, ma trovano corrispondenze anche nel contenuto visivo e audio. +Consulta il [riferimento di configurazione della memoria](/it/reference/memory-config) per la configurazione. -## Ricerca nella memoria di sessione +## Ricerca nella memoria delle sessioni -Puoi facoltativamente indicizzare le trascrizioni delle sessioni così che -`memory_search` possa richiamare conversazioni precedenti. Questa opzione è -attivabile tramite `memorySearch.experimental.sessionMemory`. Consulta il -[riferimento della configurazione](/it/reference/memory-config) per i dettagli. +Puoi facoltativamente indicizzare le trascrizioni delle sessioni in modo che `memory_search` possa richiamare +conversazioni precedenti. Questa funzione è attivabile esplicitamente tramite +`memorySearch.experimental.sessionMemory`. Consulta il +[riferimento di configurazione](/it/reference/memory-config) per i dettagli. ## Risoluzione dei problemi **Nessun risultato?** Esegui `openclaw memory status` per controllare l'indice. Se è vuoto, esegui `openclaw memory index --force`. -**Solo corrispondenze per parole chiave?** Il tuo provider di embedding potrebbe non essere configurato. Controlla +**Solo corrispondenze per parole chiave?** Il tuo provider di embeddings potrebbe non essere configurato. Controlla `openclaw memory status --deep`. **Testo CJK non trovato?** Ricostruisci l'indice FTS con `openclaw memory index --force`. -## Approfondimenti +## Ulteriori letture -- [Active Memory](/it/concepts/active-memory) -- memoria del sotto-agente per sessioni di chat interattive +- [Active Memory](/it/concepts/active-memory) -- memoria del sottoagente per sessioni di chat interattive - [Memory](/it/concepts/memory) -- layout dei file, backend, strumenti -- [Riferimento della configurazione della memoria](/it/reference/memory-config) -- tutte le opzioni di configurazione +- [Riferimento di configurazione della memoria](/it/reference/memory-config) -- tutte le opzioni di configurazione diff --git a/docs/it/concepts/memory.md b/docs/it/concepts/memory.md index 779766204..cd6040511 100644 --- a/docs/it/concepts/memory.md +++ b/docs/it/concepts/memory.md @@ -5,10 +5,10 @@ read_when: summary: Come OpenClaw ricorda le cose tra una sessione e l'altra title: Panoramica della memoria x-i18n: - generated_at: "2026-04-09T01:27:39Z" + generated_at: "2026-04-15T14:40:28Z" model: gpt-5.4 provider: openai - source_hash: 2fe47910f5bf1c44be379e971c605f1cb3a29befcf2a7ee11fb3833cbe3b9059 + source_hash: ad1adafe1d81f1703d24f48a9c9da2b25a0ebbd4aad4f65d8bde5df78195d55b source_path: concepts/memory.md workflow: 15 --- @@ -16,42 +16,41 @@ x-i18n: # Panoramica della memoria OpenClaw ricorda le cose scrivendo **semplici file Markdown** nello spazio di lavoro -del tuo agente. Il modello "ricorda" solo ciò che viene salvato su disco: non esiste +del tuo agente. Il modello "ricorda" solo ciò che viene salvato su disco -- non esiste alcuno stato nascosto. ## Come funziona -Il tuo agente ha tre file correlati alla memoria: +Il tuo agente ha tre file relativi alla memoria: - **`MEMORY.md`** -- memoria a lungo termine. Fatti durevoli, preferenze e - decisioni. Viene caricato all'inizio di ogni sessione DM. -- **`memory/YYYY-MM-DD.md`** -- note giornaliere. Contesto corrente e osservazioni. + decisioni. Caricato all'inizio di ogni sessione di DM. +- **`memory/YYYY-MM-DD.md`** -- note giornaliere. Contesto in evoluzione e osservazioni. Le note di oggi e di ieri vengono caricate automaticamente. -- **`DREAMS.md`** (sperimentale, facoltativo) -- Diario dei sogni e riepiloghi - delle scansioni oniriche per la revisione umana, incluse voci di backfill - storico basate sui dati. +- **`DREAMS.md`** (facoltativo) -- diario dei sogni e riepiloghi delle scansioni di + Dreaming per la revisione umana, incluse voci di backfill storico con fondamento. -Questi file si trovano nello spazio di lavoro dell'agente (predefinito `~/.openclaw/workspace`). +Questi file si trovano nello spazio di lavoro dell'agente (predefinito: `~/.openclaw/workspace`). -Se vuoi che il tuo agente ricordi qualcosa, basta chiederglielo: "Ricorda che +Se vuoi che il tuo agente ricordi qualcosa, chiediglielo semplicemente: "Ricorda che preferisco TypeScript." Lo scriverà nel file appropriato. ## Strumenti di memoria -L'agente ha due strumenti per lavorare con la memoria: +L'agente dispone di due strumenti per lavorare con la memoria: -- **`memory_search`** -- trova note pertinenti usando la ricerca semantica, anche - quando la formulazione è diversa da quella originale. +- **`memory_search`** -- trova note rilevanti usando la ricerca semantica, anche quando + la formulazione differisce dall'originale. - **`memory_get`** -- legge un file di memoria specifico o un intervallo di righe. -Entrambi gli strumenti sono forniti dal plugin di memoria attivo (predefinito: `memory-core`). +Entrambi gli strumenti sono forniti dal Plugin di memoria attivo (predefinito: `memory-core`). ## Plugin complementare Memory Wiki -Se vuoi che la memoria durevole si comporti più come una base di conoscenza -mantenuta che come semplici note grezze, usa il plugin integrato `memory-wiki`. +Se vuoi che la memoria durevole si comporti più come una base di conoscenza mantenuta +che come semplici note grezze, usa il Plugin integrato `memory-wiki`. `memory-wiki` compila la conoscenza durevole in un archivio wiki con: @@ -59,46 +58,45 @@ mantenuta che come semplici note grezze, usa il plugin integrato `memory-wiki`. - affermazioni ed evidenze strutturate - tracciamento di contraddizioni e aggiornamento - dashboard generate -- digest compilati per i consumer dell'agente/runtime +- digest compilati per i consumatori agente/runtime - strumenti nativi della wiki come `wiki_search`, `wiki_get`, `wiki_apply` e `wiki_lint` -Non sostituisce il plugin di memoria attivo. Il plugin di memoria attivo continua -a gestire il richiamo, la promozione e il dreaming. `memory-wiki` aggiunge un -livello di conoscenza ricco di provenienza accanto a esso. +Non sostituisce il Plugin di memoria attivo. Il Plugin di memoria attivo continua +a gestire richiamo, promozione e Dreaming. `memory-wiki` aggiunge accanto a esso +un livello di conoscenza ricco di provenienza. Vedi [Memory Wiki](/it/plugins/memory-wiki). ## Ricerca nella memoria Quando è configurato un provider di embedding, `memory_search` usa la **ricerca -ibrida** -- combinando la similarità vettoriale (significato semantico) con la -corrispondenza per parole chiave (termini esatti come ID e simboli di codice). -Funziona subito, una volta che hai una chiave API per qualsiasi provider supportato. +ibrida** -- combinando similarità vettoriale (significato semantico) con corrispondenza +per parole chiave (termini esatti come ID e simboli di codice). Funziona subito +appena disponi di una chiave API per qualsiasi provider supportato. -OpenClaw rileva automaticamente il tuo provider di embedding dalle chiavi API -disponibili. Se hai configurato una chiave OpenAI, Gemini, Voyage o Mistral, la -ricerca nella memoria viene abilitata automaticamente. +OpenClaw rileva automaticamente il tuo provider di embedding dalle chiavi API disponibili. Se +hai configurato una chiave OpenAI, Gemini, Voyage o Mistral, la ricerca nella memoria +viene abilitata automaticamente. -Per dettagli su come funziona la ricerca, sulle opzioni di configurazione e -sull'impostazione del provider, vedi -[Memory Search](/it/concepts/memory-search). +Per dettagli su come funziona la ricerca, sulle opzioni di regolazione e sulla configurazione +del provider, vedi [Memory Search](/it/concepts/memory-search). -## Backend della memoria +## Backend di memoria -Basato su SQLite. Funziona subito con ricerca per parole chiave, similarità -vettoriale e ricerca ibrida. Nessuna dipendenza aggiuntiva. +Basato su SQLite. Funziona subito con ricerca per parole chiave, similarità vettoriale e +ricerca ibrida. Nessuna dipendenza aggiuntiva. -Sidecar local-first con reranking, espansione delle query e capacità di -indicizzare directory esterne allo spazio di lavoro. +Sidecar local-first con reranking, espansione delle query e capacità di indicizzare +directory esterne allo spazio di lavoro. -Memoria cross-session nativa per l'AI con modellazione dell'utente, ricerca -semantica e consapevolezza multi-agente. Installazione tramite plugin. +Memoria cross-session AI-native con modellazione dell'utente, ricerca semantica e +consapevolezza multi-agente. Installazione del Plugin. @@ -106,53 +104,53 @@ semantica e consapevolezza multi-agente. Installazione tramite plugin. -Compila la memoria durevole in un archivio wiki ricco di provenienza con -affermazioni, dashboard, modalità bridge e flussi di lavoro compatibili con Obsidian. +Compila la memoria durevole in un archivio wiki ricco di provenienza con affermazioni, +dashboard, bridge mode e flussi di lavoro compatibili con Obsidian. ## Flush automatico della memoria -Prima che la [compaction](/it/concepts/compaction) riassuma la tua conversazione, OpenClaw -esegue un turno silenzioso che ricorda all'agente di salvare il contesto importante -nei file di memoria. Questa funzione è attiva per impostazione predefinita: non devi configurare nulla. +Prima che la [Compaction](/it/concepts/compaction) riepiloghi la tua conversazione, OpenClaw +esegue un turno silenzioso che ricorda all'agente di salvare il contesto importante nei file +di memoria. È attivo per impostazione predefinita -- non devi configurare nulla. -Il flush della memoria evita la perdita di contesto durante la compaction. Se il -tuo agente ha fatti importanti nella conversazione che non sono ancora stati -scritti in un file, verranno salvati automaticamente prima che avvenga il riepilogo. +Il flush della memoria impedisce la perdita di contesto durante la Compaction. Se il tuo agente ha +fatti importanti nella conversazione che non sono ancora stati scritti in un file, verranno +salvati automaticamente prima che avvenga il riepilogo. -## Dreaming (sperimentale) +## Dreaming -Il dreaming è un passaggio facoltativo di consolidamento in background per la -memoria. Raccoglie segnali a breve termine, valuta i candidati e promuove nella -memoria a lungo termine (`MEMORY.md`) solo gli elementi qualificati. +Dreaming è un passaggio facoltativo di consolidamento in background per la memoria. Raccoglie +segnali a breve termine, assegna un punteggio ai candidati e promuove nella memoria a lungo termine +(`MEMORY.md`) solo gli elementi qualificati. È progettato per mantenere alta la qualità della memoria a lungo termine: -- **Opt-in**: disattivato per impostazione predefinita. -- **Pianificato**: quando è abilitato, `memory-core` gestisce automaticamente un - job cron ricorrente per una scansione completa del dreaming. -- **Con soglie**: le promozioni devono superare soglie di punteggio, frequenza - di richiamo e diversità delle query. -- **Rivedibile**: i riepiloghi delle fasi e le voci del diario vengono scritti in - `DREAMS.md` per la revisione umana. +- **Su adesione esplicita**: disattivato per impostazione predefinita. +- **Pianificato**: quando è abilitato, `memory-core` gestisce automaticamente un processo Cron + ricorrente per una scansione completa di Dreaming. +- **Con soglia**: le promozioni devono superare soglie di punteggio, frequenza di richiamo e + diversità delle query. +- **Revisionabile**: i riepiloghi delle fasi e le voci del diario vengono scritti in `DREAMS.md` + per la revisione umana. -Per il comportamento delle fasi, i segnali di punteggio e i dettagli del Diario -dei sogni, vedi [Dreaming (experimental)](/it/concepts/dreaming). +Per il comportamento delle fasi, i segnali di punteggio e i dettagli del diario dei sogni, vedi +[Dreaming](/it/concepts/dreaming). -## Backfill basato sui dati e promozione live +## Backfill con fondamento e promozione in tempo reale -Il sistema di dreaming ora ha due percorsi di revisione strettamente correlati: +Il sistema di Dreaming ora ha due percorsi di revisione strettamente correlati: -- **Live dreaming** funziona a partire dall'archivio di dreaming a breve termine - in `memory/.dreams/` ed è ciò che la normale fase profonda usa quando decide - cosa può essere promosso in `MEMORY.md`. -- **Grounded backfill** legge le note storiche `memory/YYYY-MM-DD.md` come file - giornalieri autonomi e scrive output di revisione strutturati in `DREAMS.md`. +- **Live dreaming** lavora dall'archivio Dreaming a breve termine sotto + `memory/.dreams/` ed è ciò che la normale fase profonda usa per decidere cosa + può essere promosso in `MEMORY.md`. +- **Grounded backfill** legge le note storiche `memory/YYYY-MM-DD.md` come + file giornalieri autonomi e scrive output di revisione strutturato in `DREAMS.md`. -Grounded backfill è utile quando vuoi rielaborare note più vecchie e controllare +Grounded backfill è utile quando vuoi ripercorrere note più vecchie e ispezionare ciò che il sistema considera durevole senza modificare manualmente `MEMORY.md`. Quando usi: @@ -161,15 +159,14 @@ Quando usi: openclaw memory rem-backfill --path ./memory --stage-short-term ``` -i candidati durevoli basati sui dati non vengono promossi direttamente. Vengono -messi in staging nello stesso archivio di dreaming a breve termine che la normale -fase profonda usa già. Ciò significa che: +i candidati durevoli con fondamento non vengono promossi direttamente. Vengono messi in staging +nello stesso archivio Dreaming a breve termine che la normale fase profonda usa già. Questo significa: -- `DREAMS.md` resta la superficie di revisione umana. -- l'archivio a breve termine resta la superficie di classificazione rivolta alla macchina. +- `DREAMS.md` rimane la superficie di revisione umana. +- l'archivio a breve termine rimane la superficie di classificazione rivolta alla macchina. - `MEMORY.md` continua a essere scritto solo dalla promozione profonda. -Se decidi che il replay non è stato utile, puoi rimuovere gli artefatti in staging +Se decidi che il replay non è stato utile, puoi rimuovere gli artefatti messi in staging senza toccare le normali voci del diario o il normale stato di richiamo: ```bash @@ -181,19 +178,19 @@ openclaw memory rem-backfill --rollback-short-term ```bash openclaw memory status # Controlla lo stato dell'indice e il provider -openclaw memory search "query" # Esegui una ricerca dalla riga di comando -openclaw memory index --force # Ricostruisci l'indice +openclaw memory search "query" # Esegue una ricerca dalla riga di comando +openclaw memory index --force # Ricostruisce l'indice ``` -## Ulteriori letture +## Approfondimenti - [Builtin Memory Engine](/it/concepts/memory-builtin) -- backend SQLite predefinito - [QMD Memory Engine](/it/concepts/memory-qmd) -- sidecar local-first avanzato -- [Honcho Memory](/it/concepts/memory-honcho) -- memoria cross-session nativa per l'AI +- [Honcho Memory](/it/concepts/memory-honcho) -- memoria cross-session AI-native - [Memory Wiki](/it/plugins/memory-wiki) -- archivio di conoscenza compilato e strumenti nativi della wiki - [Memory Search](/it/concepts/memory-search) -- pipeline di ricerca, provider e - configurazione -- [Dreaming (experimental)](/it/concepts/dreaming) -- promozione in background + regolazione +- [Dreaming](/it/concepts/dreaming) -- promozione in background dal richiamo a breve termine alla memoria a lungo termine -- [Memory configuration reference](/it/reference/memory-config) -- tutte le opzioni di configurazione -- [Compaction](/it/concepts/compaction) -- come la compaction interagisce con la memoria +- [Riferimento della configurazione della memoria](/it/reference/memory-config) -- tutte le opzioni di configurazione +- [Compaction](/it/concepts/compaction) -- come la Compaction interagisce con la memoria diff --git a/docs/it/gateway/configuration-reference.md b/docs/it/gateway/configuration-reference.md index 4616ded30..8fba33673 100644 --- a/docs/it/gateway/configuration-reference.md +++ b/docs/it/gateway/configuration-reference.md @@ -1,14 +1,14 @@ --- read_when: - - Hai bisogno della semantica esatta dei campi di configurazione o dei valori predefiniti - - Stai convalidando blocchi di configurazione di canale, modello, gateway o strumento -summary: Riferimento della configurazione del gateway per le chiavi principali di OpenClaw, i valori predefiniti e i collegamenti ai riferimenti dedicati dei sottosistemi + - Hai bisogno della semantica esatta della configurazione a livello di campo o dei valori predefiniti. + - Stai convalidando i blocchi di configurazione di canali, modelli, Gateway o strumenti +summary: Riferimento della configurazione del Gateway per le chiavi principali di OpenClaw, i valori predefiniti e i link ai riferimenti dedicati dei sottosistemi title: Riferimento della configurazione x-i18n: - generated_at: "2026-04-11T15:16:04Z" + generated_at: "2026-04-15T14:40:29Z" model: gpt-5.4 provider: openai - source_hash: 351a245bed59d852ea8582e4e9fec5017a5c623cd6f0034766cdea1b5330be3c + source_hash: 7a4da3b41d0304389bd6359aac1185c231e529781b607656ab352f8a8104bdba source_path: gateway/configuration-reference.md workflow: 15 --- @@ -17,54 +17,54 @@ x-i18n: Riferimento della configurazione principale per `~/.openclaw/openclaw.json`. Per una panoramica orientata alle attività, vedi [Configuration](/it/gateway/configuration). -Questa pagina copre le principali superfici di configurazione di OpenClaw e rimanda ad altre pagine quando un sottosistema ha un proprio riferimento più approfondito. **Non** cerca di includere in linea ogni catalogo di comandi posseduto da canali/plugin o ogni impostazione avanzata di memoria/QMD in un'unica pagina. +Questa pagina copre le principali superfici di configurazione di OpenClaw e rimanda altrove quando un sottosistema ha un proprio riferimento più approfondito. **Non** cerca di includere in linea ogni catalogo di comandi posseduto da canali/plugin né ogni parametro avanzato di memoria/QMD in un'unica pagina. -Verità del codice: +Fonte autorevole del codice: -- `openclaw config schema` stampa lo Schema JSON live usato per la convalida e per la Control UI, con i metadati bundled/plugin/canale uniti quando disponibili -- `config.schema.lookup` restituisce un nodo dello schema limitato a un percorso per gli strumenti di analisi dettagliata -- `pnpm config:docs:check` / `pnpm config:docs:gen` convalidano l'hash di baseline della documentazione di configurazione rispetto alla superficie dello schema corrente +- `openclaw config schema` stampa lo JSON Schema live usato per la convalida e la Control UI, con i metadati bundled/plugin/channel uniti quando disponibili +- `config.schema.lookup` restituisce un nodo di schema delimitato a un singolo percorso per gli strumenti di approfondimento +- `pnpm config:docs:check` / `pnpm config:docs:gen` convalidano l'hash baseline della documentazione di configurazione rispetto alla superficie di schema corrente Riferimenti dedicati approfonditi: -- [Riferimento della configurazione della memoria](/it/reference/memory-config) per `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` e la configurazione dreaming sotto `plugins.entries.memory-core.config.dreaming` +- [Riferimento della configurazione della memoria](/it/reference/memory-config) per `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` e la configurazione di Dreaming sotto `plugins.entries.memory-core.config.dreaming` - [Comandi slash](/it/tools/slash-commands) per il catalogo corrente dei comandi integrati + bundled - pagine del canale/plugin proprietario per le superfici di comando specifiche del canale -Il formato di configurazione è **JSON5** (commenti + virgole finali consentiti). Tutti i campi sono facoltativi: OpenClaw usa valori predefiniti sicuri quando vengono omessi. +Il formato della configurazione è **JSON5** (commenti + virgole finali consentiti). Tutti i campi sono opzionali: OpenClaw usa valori predefiniti sicuri quando vengono omessi. --- ## Canali -Ogni canale si avvia automaticamente quando esiste la sua sezione di configurazione (a meno che `enabled: false`). +Ogni canale si avvia automaticamente quando la sua sezione di configurazione esiste (a meno che `enabled: false`). ### Accesso DM e gruppi -Tutti i canali supportano criteri DM e criteri per i gruppi: +Tutti i canali supportano criteri per i DM e criteri per i gruppi: | Criterio DM | Comportamento | | ------------------- | -------------------------------------------------------------- | -| `pairing` (default) | I mittenti sconosciuti ricevono un codice di associazione monouso; il proprietario deve approvare | -| `allowlist` | Solo i mittenti in `allowFrom` (o nell'archivio allow associato) | +| `pairing` (default) | I mittenti sconosciuti ricevono un codice di abbinamento monouso; il proprietario deve approvare | +| `allowlist` | Solo i mittenti in `allowFrom` (o nello store allow associato) | | `open` | Consenti tutti i DM in ingresso (richiede `allowFrom: ["*"]`) | | `disabled` | Ignora tutti i DM in ingresso | -| Criterio gruppo | Comportamento | +| Criterio gruppi | Comportamento | | --------------------- | ----------------------------------------------------- | -| `allowlist` (default) | Solo i gruppi che corrispondono alla allowlist configurata | -| `open` | Ignora le allowlist dei gruppi (la limitazione tramite menzione si applica comunque) | +| `allowlist` (default) | Solo i gruppi che corrispondono all'allowlist configurata | +| `open` | Ignora le allowlist dei gruppi (la gating per menzione si applica comunque) | | `disabled` | Blocca tutti i messaggi di gruppo/stanza | `channels.defaults.groupPolicy` imposta il valore predefinito quando `groupPolicy` di un provider non è impostato. -I codici di associazione scadono dopo 1 ora. Le richieste DM di associazione in sospeso sono limitate a **3 per canale**. -Se un blocco provider manca completamente (`channels.` assente), il criterio gruppo a runtime torna a `allowlist` (fail-closed) con un avviso all'avvio. +I codici di abbinamento scadono dopo 1 ora. Le richieste di abbinamento DM in sospeso sono limitate a **3 per canale**. +Se un blocco provider è completamente assente (`channels.` assente), il criterio gruppi a runtime torna a `allowlist` (fail-closed) con un avviso all'avvio. ### Override del modello per canale -Usa `channels.modelByChannel` per fissare ID di canali specifici a un modello. I valori accettano `provider/model` o alias di modello configurati. La mappatura del canale si applica quando una sessione non ha già un override del modello (ad esempio impostato tramite `/model`). +Usa `channels.modelByChannel` per vincolare ID di canale specifici a un modello. I valori accettano `provider/model` o alias di modello configurati. La mappatura del canale si applica quando una sessione non ha già un override del modello (ad esempio impostato tramite `/model`). ```json5 { @@ -85,9 +85,9 @@ Usa `channels.modelByChannel` per fissare ID di canali specifici a un modello. I } ``` -### Valori predefiniti dei canali e heartbeat +### Valori predefiniti del canale e Heartbeat -Usa `channels.defaults` per il comportamento condiviso di criteri gruppo e heartbeat tra i provider: +Usa `channels.defaults` per il comportamento condiviso di criterio gruppi e Heartbeat tra i provider: ```json5 { @@ -105,15 +105,15 @@ Usa `channels.defaults` per il comportamento condiviso di criteri gruppo e heart } ``` -- `channels.defaults.groupPolicy`: criterio gruppo di fallback quando `groupPolicy` a livello provider non è impostato. -- `channels.defaults.contextVisibility`: modalità predefinita di visibilità del contesto supplementare per tutti i canali. Valori: `all` (predefinito, include tutto il contesto citato/thread/cronologia), `allowlist` (include solo il contesto da mittenti presenti nella allowlist), `allowlist_quote` (come allowlist ma mantiene il contesto esplicito di citazione/risposta). Override per canale: `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk`: include gli stati dei canali integri nell'output heartbeat. -- `channels.defaults.heartbeat.showAlerts`: include gli stati degradati/di errore nell'output heartbeat. -- `channels.defaults.heartbeat.useIndicator`: mostra un output heartbeat compatto in stile indicatore. +- `channels.defaults.groupPolicy`: criterio gruppi di fallback quando il `groupPolicy` a livello provider non è impostato. +- `channels.defaults.contextVisibility`: modalità predefinita di visibilità del contesto supplementare per tutti i canali. Valori: `all` (predefinito, include tutto il contesto di citazioni/thread/storia), `allowlist` (include solo il contesto da mittenti in allowlist), `allowlist_quote` (come allowlist ma mantiene il contesto esplicito di citazione/risposta). Override per canale: `channels..contextVisibility`. +- `channels.defaults.heartbeat.showOk`: includi gli stati sani dei canali nell'output Heartbeat. +- `channels.defaults.heartbeat.showAlerts`: includi gli stati degradati/di errore nell'output Heartbeat. +- `channels.defaults.heartbeat.useIndicator`: visualizza un output Heartbeat compatto in stile indicatore. ### WhatsApp -WhatsApp viene eseguito tramite il canale web del gateway (Baileys Web). Si avvia automaticamente quando esiste una sessione collegata. +WhatsApp funziona tramite il canale web del Gateway (Baileys Web). Si avvia automaticamente quando esiste una sessione collegata. ```json5 { @@ -124,7 +124,7 @@ WhatsApp viene eseguito tramite il canale web del gateway (Baileys Web). Si avvi textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // blue ticks (false in self-chat mode) + sendReadReceipts: true, // spunte blu (false in modalità chat con sé stessi) groups: { "*": { requireMention: true }, }, @@ -164,9 +164,9 @@ WhatsApp viene eseguito tramite il canale web del gateway (Baileys Web). Si avvi } ``` -- I comandi in uscita usano per impostazione predefinita l'account `default` se presente; altrimenti il primo ID account configurato (ordinato). -- L'opzione facoltativa `channels.whatsapp.defaultAccount` sovrascrive quella selezione predefinita dell'account di fallback quando corrisponde a un ID account configurato. -- La directory di autenticazione Baileys legacy a singolo account viene migrata da `openclaw doctor` in `whatsapp/default`. +- I comandi in uscita usano come valore predefinito l'account `default` se presente; altrimenti il primo ID account configurato (ordinato). +- L'opzionale `channels.whatsapp.defaultAccount` sovrascrive quella selezione predefinita di account di fallback quando corrisponde a un ID account configurato. +- La directory di autenticazione Baileys legacy per account singolo viene migrata da `openclaw doctor` in `whatsapp/default`. - Override per account: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -225,12 +225,12 @@ WhatsApp viene eseguito tramite il canale web del gateway (Baileys Web). Si avvi } ``` -- Token del bot: `channels.telegram.botToken` oppure `channels.telegram.tokenFile` (solo file regolari; i symlink vengono rifiutati), con `TELEGRAM_BOT_TOKEN` come fallback per l'account predefinito. -- L'opzione facoltativa `channels.telegram.defaultAccount` sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. -- Nelle configurazioni multi-account (2+ ID account), imposta un valore predefinito esplicito (`channels.telegram.defaultAccount` oppure `channels.telegram.accounts.default`) per evitare il routing di fallback; `openclaw doctor` avvisa quando questo manca o non è valido. -- `configWrites: false` blocca le scritture di configurazione avviate da Telegram (migrazioni ID supergruppo, `/config set|unset`). -- Le voci `bindings[]` di primo livello con `type: "acp"` configurano binding ACP persistenti per gli argomenti del forum (usa il formato canonico `chatId:topic:topicId` in `match.peer.id`). La semantica dei campi è condivisa in [ACP Agents](/it/tools/acp-agents#channel-specific-settings). -- Le anteprime di stream Telegram usano `sendMessage` + `editMessageText` (funziona nelle chat dirette e di gruppo). +- Token del bot: `channels.telegram.botToken` o `channels.telegram.tokenFile` (solo file regolare; i symlink sono rifiutati), con `TELEGRAM_BOT_TOKEN` come fallback per l'account predefinito. +- L'opzionale `channels.telegram.defaultAccount` sovrascrive la selezione predefinita dell'account quando corrisponde a un ID account configurato. +- Nelle configurazioni multi-account (2+ ID account), imposta un valore predefinito esplicito (`channels.telegram.defaultAccount` o `channels.telegram.accounts.default`) per evitare il routing di fallback; `openclaw doctor` avvisa quando questo manca o non è valido. +- `configWrites: false` blocca le scritture di configurazione avviate da Telegram (migrazioni degli ID dei supergruppi, `/config set|unset`). +- Le voci `bindings[]` di livello superiore con `type: "acp"` configurano binding ACP persistenti per gli argomenti del forum (usa il canonico `chatId:topic:topicId` in `match.peer.id`). La semantica dei campi è condivisa in [ACP Agents](/it/tools/acp-agents#channel-specific-settings). +- Le anteprime di streaming di Telegram usano `sendMessage` + `editMessageText` (funziona in chat dirette e di gruppo). - Criterio di retry: vedi [Retry policy](/it/concepts/retry). ### Discord @@ -334,32 +334,32 @@ WhatsApp viene eseguito tramite il canale web del gateway (Baileys Web). Si avvi ``` - Token: `channels.discord.token`, con `DISCORD_BOT_TOKEN` come fallback per l'account predefinito. -- Le chiamate dirette in uscita che forniscono un `token` Discord esplicito usano quel token per la chiamata; le impostazioni di retry/criterio dell'account provengono comunque dall'account selezionato nello snapshot runtime attivo. -- L'opzione facoltativa `channels.discord.defaultAccount` sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- Le chiamate dirette in uscita che forniscono un `token` Discord esplicito usano quel token per la chiamata; le impostazioni di retry/criterio dell'account continuano comunque a provenire dall'account selezionato nello snapshot runtime attivo. +- L'opzionale `channels.discord.defaultAccount` sovrascrive la selezione predefinita dell'account quando corrisponde a un ID account configurato. - Usa `user:` (DM) o `channel:` (canale guild) per i target di consegna; gli ID numerici senza prefisso vengono rifiutati. -- Gli slug delle guild sono in minuscolo con gli spazi sostituiti da `-`; le chiavi dei canali usano il nome in formato slug (senza `#`). Preferisci gli ID delle guild. -- I messaggi creati dal bot vengono ignorati per impostazione predefinita. `allowBots: true` li abilita; usa `allowBots: "mentions"` per accettare solo i messaggi dei bot che menzionano il bot (i propri messaggi restano comunque filtrati). -- `channels.discord.guilds..ignoreOtherMentions` (e gli override a livello canale) elimina i messaggi che menzionano un altro utente o ruolo ma non il bot (escludendo @everyone/@here). -- `maxLinesPerMessage` (predefinito 17) divide i messaggi alti anche quando restano sotto 2000 caratteri. -- `channels.discord.threadBindings` controlla il routing vincolato ai thread Discord: - - `enabled`: override Discord per le funzionalità di sessione vincolate ai thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` e consegna/routing associati) - - `idleHours`: override Discord per il disaccoppiamento automatico per inattività in ore (`0` disabilita) - - `maxAgeHours`: override Discord per l'età massima rigida in ore (`0` disabilita) - - `spawnSubagentSessions`: interruttore opt-in per la creazione/associazione automatica dei thread di `sessions_spawn({ thread: true })` -- Le voci `bindings[]` di primo livello con `type: "acp"` configurano binding ACP persistenti per canali e thread (usa l'id del canale/thread in `match.peer.id`). La semantica dei campi è condivisa in [ACP Agents](/it/tools/acp-agents#channel-specific-settings). -- `channels.discord.ui.components.accentColor` imposta il colore di accento per i contenitori Discord components v2. -- `channels.discord.voice` abilita le conversazioni nei canali vocali Discord e gli override facoltativi di auto-join + TTS. -- `channels.discord.voice.daveEncryption` e `channels.discord.voice.decryptionFailureTolerance` vengono passati a `@discordjs/voice` come opzioni DAVE (`true` e `24` per impostazione predefinita). +- Gli slug delle guild sono in minuscolo con gli spazi sostituiti da `-`; le chiavi dei canali usano il nome trasformato in slug (senza `#`). Preferisci gli ID delle guild. +- I messaggi scritti dal bot vengono ignorati per impostazione predefinita. `allowBots: true` li abilita; usa `allowBots: "mentions"` per accettare solo i messaggi dei bot che menzionano il bot (i propri messaggi restano comunque filtrati). +- `channels.discord.guilds..ignoreOtherMentions` (e gli override a livello di canale) elimina i messaggi che menzionano un altro utente o ruolo ma non il bot (escludendo @everyone/@here). +- `maxLinesPerMessage` (predefinito 17) divide i messaggi lunghi in altezza anche quando sono sotto i 2000 caratteri. +- `channels.discord.threadBindings` controlla il routing associato ai thread di Discord: + - `enabled`: override Discord per le funzionalità di sessione associate ai thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` e consegna/routing associati) + - `idleHours`: override Discord per l'auto-unfocus dovuto a inattività in ore (`0` lo disabilita) + - `maxAgeHours`: override Discord per l'età massima rigida in ore (`0` lo disabilita) + - `spawnSubagentSessions`: interruttore opt-in per la creazione/associazione automatica di thread con `sessions_spawn({ thread: true })` +- Le voci `bindings[]` di livello superiore con `type: "acp"` configurano binding ACP persistenti per canali e thread (usa l'id del canale/thread in `match.peer.id`). La semantica dei campi è condivisa in [ACP Agents](/it/tools/acp-agents#channel-specific-settings). +- `channels.discord.ui.components.accentColor` imposta il colore d'accento per i contenitori Discord components v2. +- `channels.discord.voice` abilita le conversazioni nei canali vocali Discord e gli override opzionali di auto-join + TTS. +- `channels.discord.voice.daveEncryption` e `channels.discord.voice.decryptionFailureTolerance` vengono passati a `@discordjs/voice` come opzioni DAVE (rispettivamente `true` e `24` per impostazione predefinita). - OpenClaw tenta inoltre il recupero della ricezione vocale uscendo e rientrando in una sessione vocale dopo ripetuti errori di decrittazione. -- `channels.discord.streaming` è la chiave canonica della modalità di stream. I valori legacy `streamMode` e booleani `streaming` vengono migrati automaticamente. -- `channels.discord.autoPresence` mappa la disponibilità runtime alla presenza del bot (healthy => online, degraded => idle, exhausted => dnd) e consente override facoltativi del testo di stato. -- `channels.discord.dangerouslyAllowNameMatching` riabilita la corrispondenza per nome/tag modificabile (modalità di compatibilità break-glass). +- `channels.discord.streaming` è la chiave canonica per la modalità di streaming. I valori legacy `streamMode` e booleani `streaming` vengono migrati automaticamente. +- `channels.discord.autoPresence` mappa la disponibilità runtime alla presenza del bot (healthy => online, degraded => idle, exhausted => dnd) e consente override opzionali del testo di stato. +- `channels.discord.dangerouslyAllowNameMatching` riabilita la corrispondenza tramite nome/tag mutabili (modalità di compatibilità break-glass). - `channels.discord.execApprovals`: consegna nativa Discord delle approvazioni exec e autorizzazione degli approvatori. - `enabled`: `true`, `false` o `"auto"` (predefinito). In modalità auto, le approvazioni exec si attivano quando gli approvatori possono essere risolti da `approvers` o `commands.ownerAllowFrom`. - `approvers`: ID utente Discord autorizzati ad approvare le richieste exec. Se omesso, usa `commands.ownerAllowFrom` come fallback. - - `agentFilter`: allowlist facoltativa di ID agente. Omettila per inoltrare le approvazioni per tutti gli agenti. - - `sessionFilter`: pattern facoltativi di chiavi sessione (sottostringa o regex). - - `target`: dove inviare i prompt di approvazione. `"dm"` (predefinito) li invia ai DM degli approvatori, `"channel"` li invia al canale di origine, `"both"` li invia a entrambi. Quando il target include `"channel"`, i pulsanti possono essere usati solo dagli approvatori risolti. + - `agentFilter`: allowlist opzionale di ID agente. Omettilo per inoltrare le approvazioni per tutti gli agenti. + - `sessionFilter`: pattern opzionali di chiavi sessione (sottostringa o regex). + - `target`: dove inviare le richieste di approvazione. `"dm"` (predefinito) le invia ai DM degli approvatori, `"channel"` le invia al canale di origine, `"both"` le invia a entrambi. Quando il target include `"channel"`, i pulsanti possono essere usati solo dagli approvatori risolti. - `cleanupAfterResolve`: quando `true`, elimina i DM di approvazione dopo approvazione, rifiuto o timeout. **Modalità di notifica delle reazioni:** `off` (nessuna), `own` (messaggi del bot, predefinita), `all` (tutti i messaggi), `allowlist` (da `guilds..users` su tutti i messaggi). @@ -394,10 +394,10 @@ WhatsApp viene eseguito tramite il canale web del gateway (Baileys Web). Si avvi ``` - JSON dell'account di servizio: inline (`serviceAccount`) o basato su file (`serviceAccountFile`). -- È supportato anche SecretRef dell'account di servizio (`serviceAccountRef`). -- Fallback env: `GOOGLE_CHAT_SERVICE_ACCOUNT` o `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. +- È supportato anche SecretRef per l'account di servizio (`serviceAccountRef`). +- Fallback da env: `GOOGLE_CHAT_SERVICE_ACCOUNT` o `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. - Usa `spaces/` o `users/` per i target di consegna. -- `channels.googlechat.dangerouslyAllowNameMatching` riabilita la corrispondenza modificabile del principal email (modalità di compatibilità break-glass). +- `channels.googlechat.dangerouslyAllowNameMatching` riabilita la corrispondenza tramite principal email mutabile (modalità di compatibilità break-glass). ### Slack @@ -464,21 +464,21 @@ WhatsApp viene eseguito tramite il canale web del gateway (Baileys Web). Si avvi } ``` -- **Socket mode** richiede sia `botToken` sia `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` come fallback env dell'account predefinito). -- **HTTP mode** richiede `botToken` più `signingSecret` (alla radice o per account). +- **La modalità Socket** richiede sia `botToken` sia `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` come fallback env dell'account predefinito). +- **La modalità HTTP** richiede `botToken` più `signingSecret` (alla radice o per account). - `botToken`, `appToken`, `signingSecret` e `userToken` accettano stringhe in chiaro o oggetti SecretRef. -- Gli snapshot degli account Slack espongono campi per origine/stato delle credenziali, come `botTokenSource`, `botTokenStatus`, `appTokenStatus` e, in modalità HTTP, `signingSecretStatus`. `configured_unavailable` significa che l'account è configurato tramite SecretRef ma il comando/percorso runtime corrente non ha potuto risolvere il valore del segreto. +- Gli snapshot degli account Slack espongono campi source/status per credenziale, come `botTokenSource`, `botTokenStatus`, `appTokenStatus` e, in modalità HTTP, `signingSecretStatus`. `configured_unavailable` significa che l'account è configurato tramite SecretRef ma il percorso corrente di comando/runtime non ha potuto risolvere il valore del segreto. - `configWrites: false` blocca le scritture di configurazione avviate da Slack. -- L'opzione facoltativa `channels.slack.defaultAccount` sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. -- `channels.slack.streaming.mode` è la chiave canonica della modalità di stream Slack. `channels.slack.streaming.nativeTransport` controlla il trasporto streaming nativo di Slack. I valori legacy `streamMode`, booleani `streaming` e `nativeStreaming` vengono migrati automaticamente. +- L'opzionale `channels.slack.defaultAccount` sovrascrive la selezione predefinita dell'account quando corrisponde a un ID account configurato. +- `channels.slack.streaming.mode` è la chiave canonica per la modalità di streaming di Slack. `channels.slack.streaming.nativeTransport` controlla il trasporto di streaming nativo di Slack. I valori legacy `streamMode`, booleani `streaming` e `nativeStreaming` vengono migrati automaticamente. - Usa `user:` (DM) o `channel:` per i target di consegna. **Modalità di notifica delle reazioni:** `off`, `own` (predefinita), `all`, `allowlist` (da `reactionAllowlist`). -**Isolamento della sessione del thread:** `thread.historyScope` è per-thread (predefinito) o condiviso nel canale. `thread.inheritParent` copia la trascrizione del canale padre nei nuovi thread. +**Isolamento delle sessioni thread:** `thread.historyScope` è per-thread (predefinito) o condiviso nel canale. `thread.inheritParent` copia la trascrizione del canale padre nei nuovi thread. -- Lo streaming nativo di Slack, insieme allo stato del thread in stile assistente Slack "is typing...", richiede un target di risposta nel thread. I DM di primo livello restano fuori thread per impostazione predefinita, quindi usano `typingReaction` o la consegna normale invece dell'anteprima in stile thread. -- `typingReaction` aggiunge una reazione temporanea al messaggio Slack in ingresso mentre una risposta è in esecuzione, poi la rimuove al completamento. Usa uno shortcode emoji Slack come `"hourglass_flowing_sand"`. +- Lo streaming nativo di Slack più lo stato del thread in stile assistente Slack "is typing..." richiedono un target di risposta nel thread. I DM di livello superiore restano fuori thread per impostazione predefinita, quindi usano `typingReaction` o la consegna normale invece dell'anteprima in stile thread. +- `typingReaction` aggiunge una reazione temporanea al messaggio Slack in ingresso mentre una risposta è in corso, quindi la rimuove al completamento. Usa uno shortcode emoji Slack come `"hourglass_flowing_sand"`. - `channels.slack.execApprovals`: consegna nativa Slack delle approvazioni exec e autorizzazione degli approvatori. Stesso schema di Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID utente Slack), `agentFilter`, `sessionFilter` e `target` (`"dm"`, `"channel"` o `"both"`). | Gruppo di azioni | Predefinito | Note | @@ -491,7 +491,7 @@ WhatsApp viene eseguito tramite il canale web del gateway (Baileys Web). Si avvi ### Mattermost -Mattermost viene distribuito come plugin: `openclaw plugins install @openclaw/mattermost`. +Mattermost viene distribuito come Plugin: `openclaw plugins install @openclaw/mattermost`. ```json5 { @@ -511,7 +511,7 @@ Mattermost viene distribuito come plugin: `openclaw plugins install @openclaw/ma native: true, // opt-in nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // Optional explicit URL for reverse-proxy/public deployments + // URL esplicito opzionale per deployment reverse-proxy/pubblici callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -521,18 +521,18 @@ Mattermost viene distribuito come plugin: `openclaw plugins install @openclaw/ma } ``` -Modalità chat: `oncall` (risponde a @-mention, predefinita), `onmessage` (ogni messaggio), `onchar` (messaggi che iniziano con un prefisso trigger). +Modalità chat: `oncall` (risponde a @-mention, predefinita), `onmessage` (ogni messaggio), `onchar` (messaggi che iniziano con il prefisso trigger). -Quando i comandi nativi Mattermost sono abilitati: +Quando i comandi nativi di Mattermost sono abilitati: - `commands.callbackPath` deve essere un percorso (ad esempio `/api/channels/mattermost/command`), non un URL completo. -- `commands.callbackUrl` deve risolversi all'endpoint gateway OpenClaw ed essere raggiungibile dal server Mattermost. -- I callback slash nativi sono autenticati con i token per comando restituiti da Mattermost durante la registrazione del comando slash. Se la registrazione fallisce o non viene attivato alcun comando, OpenClaw rifiuta i callback con `Unauthorized: invalid command token.` -- Per host callback privati/tailnet/interni, Mattermost può richiedere che `ServiceSettings.AllowedUntrustedInternalConnections` includa l'host/dominio del callback. Usa valori host/dominio, non URL completi. -- `channels.mattermost.configWrites`: consenti o nega le scritture di configurazione avviate da Mattermost. +- `commands.callbackUrl` deve risolversi nell'endpoint Gateway di OpenClaw ed essere raggiungibile dal server Mattermost. +- I callback slash nativi vengono autenticati con i token per comando restituiti da Mattermost durante la registrazione dei comandi slash. Se la registrazione fallisce o nessun comando viene attivato, OpenClaw rifiuta i callback con `Unauthorized: invalid command token.` +- Per host di callback privati/tailnet/interni, Mattermost potrebbe richiedere che `ServiceSettings.AllowedUntrustedInternalConnections` includa l'host/dominio del callback. Usa valori host/dominio, non URL completi. +- `channels.mattermost.configWrites`: consente o nega le scritture di configurazione avviate da Mattermost. - `channels.mattermost.requireMention`: richiede `@mention` prima di rispondere nei canali. -- `channels.mattermost.groups..requireMention`: override per canale della limitazione tramite menzione (`"*"` per il predefinito). -- L'opzione facoltativa `channels.mattermost.defaultAccount` sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- `channels.mattermost.groups..requireMention`: override del gating per menzione per canale (`"*"` per il predefinito). +- L'opzionale `channels.mattermost.defaultAccount` sovrascrive la selezione predefinita dell'account quando corrisponde a un ID account configurato. ### Signal @@ -541,7 +541,7 @@ Quando i comandi nativi Mattermost sono abilitati: channels: { signal: { enabled: true, - account: "+15555550123", // optional account binding + account: "+15555550123", // binding opzionale dell'account dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -556,12 +556,12 @@ Quando i comandi nativi Mattermost sono abilitati: **Modalità di notifica delle reazioni:** `off`, `own` (predefinita), `all`, `allowlist` (da `reactionAllowlist`). - `channels.signal.account`: vincola l'avvio del canale a una specifica identità account Signal. -- `channels.signal.configWrites`: consenti o nega le scritture di configurazione avviate da Signal. -- L'opzione facoltativa `channels.signal.defaultAccount` sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- `channels.signal.configWrites`: consente o nega le scritture di configurazione avviate da Signal. +- L'opzionale `channels.signal.defaultAccount` sovrascrive la selezione predefinita dell'account quando corrisponde a un ID account configurato. ### BlueBubbles -BlueBubbles è il percorso iMessage consigliato (supportato da plugin, configurato sotto `channels.bluebubbles`). +BlueBubbles è il percorso iMessage consigliato (supportato da Plugin, configurato sotto `channels.bluebubbles`). ```json5 { @@ -569,16 +569,16 @@ BlueBubbles è il percorso iMessage consigliato (supportato da plugin, configura bluebubbles: { enabled: true, dmPolicy: "pairing", - // serverUrl, password, webhookPath, group controls, and advanced actions: - // see /channels/bluebubbles + // serverUrl, password, webhookPath, controlli di gruppo e azioni avanzate: + // vedi /channels/bluebubbles }, }, } ``` -- I percorsi chiave principali trattati qui: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- L'opzione facoltativa `channels.bluebubbles.defaultAccount` sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. -- Le voci `bindings[]` di primo livello con `type: "acp"` possono associare conversazioni BlueBubbles a sessioni ACP persistenti. Usa un handle BlueBubbles o una stringa target (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) in `match.peer.id`. Semantica condivisa dei campi: [ACP Agents](/it/tools/acp-agents#channel-specific-settings). +- Percorsi delle chiavi core coperti qui: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. +- L'opzionale `channels.bluebubbles.defaultAccount` sovrascrive la selezione predefinita dell'account quando corrisponde a un ID account configurato. +- Le voci `bindings[]` di livello superiore con `type: "acp"` possono associare le conversazioni BlueBubbles a sessioni ACP persistenti. Usa un handle BlueBubbles o una stringa target (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) in `match.peer.id`. Semantica dei campi condivisa: [ACP Agents](/it/tools/acp-agents#channel-specific-settings). - La configurazione completa del canale BlueBubbles è documentata in [BlueBubbles](/it/channels/bluebubbles). ### iMessage @@ -607,15 +607,15 @@ OpenClaw avvia `imsg rpc` (JSON-RPC su stdio). Non è richiesto alcun demone o p } ``` -- L'opzione facoltativa `channels.imessage.defaultAccount` sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- L'opzionale `channels.imessage.defaultAccount` sovrascrive la selezione predefinita dell'account quando corrisponde a un ID account configurato. -- Richiede Full Disk Access al database Messaggi. -- Preferisci target `chat_id:`. Usa `imsg chats --limit 20` per elencare le chat. -- `cliPath` può puntare a un wrapper SSH; imposta `remoteHost` (`host` o `user@host`) per il recupero degli allegati tramite SCP. +- Richiede l'accesso completo al disco per il database di Messaggi. +- Preferisci i target `chat_id:`. Usa `imsg chats --limit 20` per elencare le chat. +- `cliPath` può puntare a un wrapper SSH; imposta `remoteHost` (`host` o `user@host`) per il recupero degli allegati via SCP. - `attachmentRoots` e `remoteAttachmentRoots` limitano i percorsi degli allegati in ingresso (predefinito: `/Users/*/Library/Messages/Attachments`). - SCP usa il controllo rigoroso della chiave host, quindi assicurati che la chiave host del relay esista già in `~/.ssh/known_hosts`. -- `channels.imessage.configWrites`: consenti o nega le scritture di configurazione avviate da iMessage. -- Le voci `bindings[]` di primo livello con `type: "acp"` possono associare conversazioni iMessage a sessioni ACP persistenti. Usa un handle normalizzato o un target chat esplicito (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) in `match.peer.id`. Semantica condivisa dei campi: [ACP Agents](/it/tools/acp-agents#channel-specific-settings). +- `channels.imessage.configWrites`: consente o nega le scritture di configurazione avviate da iMessage. +- Le voci `bindings[]` di livello superiore con `type: "acp"` possono associare le conversazioni iMessage a sessioni ACP persistenti. Usa un handle normalizzato o un target chat esplicito (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) in `match.peer.id`. Semantica dei campi condivisa: [ACP Agents](/it/tools/acp-agents#channel-specific-settings). @@ -659,19 +659,19 @@ Matrix è supportato da estensione ed è configurato sotto `channels.matrix`. ``` - L'autenticazione tramite token usa `accessToken`; l'autenticazione tramite password usa `userId` + `password`. -- `channels.matrix.proxy` instrada il traffico HTTP Matrix attraverso un proxy HTTP(S) esplicito. Gli account nominati possono sovrascriverlo con `channels.matrix.accounts..proxy`. +- `channels.matrix.proxy` instrada il traffico HTTP di Matrix attraverso un proxy HTTP(S) esplicito. Gli account denominati possono sovrascriverlo con `channels.matrix.accounts..proxy`. - `channels.matrix.network.dangerouslyAllowPrivateNetwork` consente homeserver privati/interni. `proxy` e questo opt-in di rete sono controlli indipendenti. - `channels.matrix.defaultAccount` seleziona l'account preferito nelle configurazioni multi-account. -- `channels.matrix.autoJoin` ha valore predefinito `off`, quindi le stanze invitate e i nuovi inviti in stile DM vengono ignorati finché non imposti `autoJoin: "allowlist"` con `autoJoinAllowlist` o `autoJoin: "always"`. +- `channels.matrix.autoJoin` ha come predefinito `off`, quindi le stanze invitate e i nuovi inviti in stile DM vengono ignorati finché non imposti `autoJoin: "allowlist"` con `autoJoinAllowlist` oppure `autoJoin: "always"`. - `channels.matrix.execApprovals`: consegna nativa Matrix delle approvazioni exec e autorizzazione degli approvatori. - `enabled`: `true`, `false` o `"auto"` (predefinito). In modalità auto, le approvazioni exec si attivano quando gli approvatori possono essere risolti da `approvers` o `commands.ownerAllowFrom`. - - `approvers`: ID utente Matrix (ad es. `@owner:example.org`) autorizzati ad approvare richieste exec. - - `agentFilter`: allowlist facoltativa di ID agente. Omettila per inoltrare le approvazioni per tutti gli agenti. - - `sessionFilter`: pattern facoltativi di chiavi sessione (sottostringa o regex). - - `target`: dove inviare i prompt di approvazione. `"dm"` (predefinito), `"channel"` (stanza di origine) o `"both"`. + - `approvers`: ID utente Matrix (ad es. `@owner:example.org`) autorizzati ad approvare le richieste exec. + - `agentFilter`: allowlist opzionale di ID agente. Omettilo per inoltrare le approvazioni per tutti gli agenti. + - `sessionFilter`: pattern opzionali di chiavi sessione (sottostringa o regex). + - `target`: dove inviare le richieste di approvazione. `"dm"` (predefinito), `"channel"` (stanza di origine) o `"both"`. - Override per account: `channels.matrix.accounts..execApprovals`. - `channels.matrix.dm.sessionScope` controlla come i DM Matrix vengono raggruppati in sessioni: `per-user` (predefinito) condivide per peer instradato, mentre `per-room` isola ogni stanza DM. -- I probe di stato Matrix e le ricerche live nella directory usano lo stesso criterio proxy del traffico runtime. +- I probe di stato di Matrix e le ricerche live nella directory usano lo stesso criterio proxy del traffico runtime. - La configurazione completa di Matrix, le regole di targeting e gli esempi di configurazione sono documentati in [Matrix](/it/channels/matrix). ### Microsoft Teams @@ -684,14 +684,14 @@ Microsoft Teams è supportato da estensione ed è configurato sotto `channels.ms msteams: { enabled: true, configWrites: true, - // appId, appPassword, tenantId, webhook, team/channel policies: - // see /channels/msteams + // appId, appPassword, tenantId, webhook, criteri team/canale: + // vedi /channels/msteams }, }, } ``` -- I percorsi chiave principali trattati qui: `channels.msteams`, `channels.msteams.configWrites`. +- Percorsi delle chiavi core coperti qui: `channels.msteams`, `channels.msteams.configWrites`. - La configurazione completa di Teams (credenziali, webhook, criterio DM/gruppi, override per team/per canale) è documentata in [Microsoft Teams](/it/channels/msteams). ### IRC @@ -717,9 +717,9 @@ IRC è supportato da estensione ed è configurato sotto `channels.irc`. } ``` -- I percorsi chiave principali trattati qui: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- L'opzione facoltativa `channels.irc.defaultAccount` sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. -- La configurazione completa del canale IRC (host/porta/TLS/canali/allowlist/limitazione tramite menzione) è documentata in [IRC](/it/channels/irc). +- Percorsi delle chiavi core coperti qui: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. +- L'opzionale `channels.irc.defaultAccount` sovrascrive la selezione predefinita dell'account quando corrisponde a un ID account configurato. +- La configurazione completa del canale IRC (host/porta/TLS/canali/allowlist/gating per menzione) è documentata in [IRC](/it/channels/irc). ### Multi-account (tutti i canali) @@ -731,11 +731,11 @@ Esegui più account per canale (ognuno con il proprio `accountId`): telegram: { accounts: { default: { - name: "Primary bot", + name: "Bot principale", botToken: "123456:ABC...", }, alerts: { - name: "Alerts bot", + name: "Bot avvisi", botToken: "987654:XYZ...", }, }, @@ -744,28 +744,28 @@ Esegui più account per canale (ognuno con il proprio `accountId`): } ``` -- `default` viene usato quando `accountId` viene omesso (CLI + routing). +- `default` viene usato quando `accountId` è omesso (CLI + routing). - I token env si applicano solo all'account **default**. -- Le impostazioni base del canale si applicano a tutti gli account salvo override per account. +- Le impostazioni base del canale si applicano a tutti gli account, salvo override per account. - Usa `bindings[].match.accountId` per instradare ogni account a un agente diverso. -- Se aggiungi un account non predefinito tramite `openclaw channels add` (o onboarding del canale) mentre sei ancora su una configurazione di canale top-level a singolo account, OpenClaw promuove prima i valori top-level a singolo account con ambito account nella mappa account del canale, così l'account originale continua a funzionare. La maggior parte dei canali li sposta in `channels..accounts.default`; Matrix può invece preservare un target nominato/predefinito esistente corrispondente. -- I binding esistenti solo-canale (senza `accountId`) continuano a corrispondere all'account predefinito; i binding con ambito account restano facoltativi. -- `openclaw doctor --fix` ripara anche le forme miste spostando i valori top-level a singolo account con ambito account nell'account promosso scelto per quel canale. La maggior parte dei canali usa `accounts.default`; Matrix può preservare un target nominato/predefinito esistente corrispondente. +- Se aggiungi un account non predefinito tramite `openclaw channels add` (o onboarding del canale) mentre sei ancora su una configurazione di canale di livello superiore single-account, OpenClaw promuove prima i valori single-account di livello superiore con ambito account nella mappa degli account del canale, così l'account originale continua a funzionare. La maggior parte dei canali li sposta in `channels..accounts.default`; Matrix può invece preservare un target denominato/predefinito esistente corrispondente. +- I binding esistenti solo-canale (senza `accountId`) continuano a corrispondere all'account predefinito; i binding con ambito account restano opzionali. +- Anche `openclaw doctor --fix` ripara le forme miste spostando i valori single-account di livello superiore con ambito account nell'account promosso scelto per quel canale. La maggior parte dei canali usa `accounts.default`; Matrix può invece preservare un target denominato/predefinito esistente corrispondente. ### Altri canali di estensione -Molti canali di estensione sono configurati come `channels.` e documentati nelle rispettive pagine dedicate ai canali (ad esempio Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat e Twitch). +Molti canali di estensione sono configurati come `channels.` e documentati nelle rispettive pagine dedicate del canale (ad esempio Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat e Twitch). Vedi l'indice completo dei canali: [Channels](/it/channels). -### Limitazione tramite menzione nelle chat di gruppo +### Gating per menzione nelle chat di gruppo -I messaggi di gruppo richiedono per impostazione predefinita una **menzione obbligatoria** (metadati di menzione o pattern regex sicuri). Si applica a WhatsApp, Telegram, Discord, Google Chat e chat di gruppo iMessage. +I messaggi di gruppo richiedono per impostazione predefinita **una menzione obbligatoria** (menzione nei metadati o pattern regex sicuri). Si applica alle chat di gruppo di WhatsApp, Telegram, Discord, Google Chat e iMessage. **Tipi di menzione:** -- **Menzioni nei metadati**: @-mention native della piattaforma. Ignorate nella modalità self-chat di WhatsApp. +- **Menzioni nei metadati**: @-mention native della piattaforma. Ignorate nella modalità chat con sé stessi di WhatsApp. - **Pattern di testo**: pattern regex sicuri in `agents.list[].groupChat.mentionPatterns`. I pattern non validi e le ripetizioni annidate non sicure vengono ignorati. -- La limitazione tramite menzione viene applicata solo quando il rilevamento è possibile (menzioni native o almeno un pattern). +- Il gating per menzione viene applicato solo quando il rilevamento è possibile (menzioni native o almeno un pattern). ```json5 { @@ -795,13 +795,13 @@ I messaggi di gruppo richiedono per impostazione predefinita una **menzione obbl } ``` -Risoluzione: override per DM → valore predefinito del provider → nessun limite (tutto conservato). +Risoluzione: override per-DM → valore predefinito del provider → nessun limite (tutto conservato). Supportati: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. -#### Modalità self-chat +#### Modalità chat con sé stessi -Includi il tuo numero in `allowFrom` per abilitare la modalità self-chat (ignora le @-mention native, risponde solo ai pattern di testo): +Includi il tuo numero in `allowFrom` per abilitare la modalità chat con sé stessi (ignora le @-mention native, risponde solo ai pattern di testo): ```json5 { @@ -822,21 +822,21 @@ Includi il tuo numero in `allowFrom` per abilitare la modalità self-chat (ignor } ``` -### Comandi (gestione dei comandi chat) +### Comandi (gestione dei comandi in chat) ```json5 { commands: { - native: "auto", // register native commands when supported - nativeSkills: "auto", // register native skill commands when supported - text: true, // parse /commands in chat messages - bash: false, // allow ! (alias: /bash) + native: "auto", // registra i comandi nativi quando supportati + nativeSkills: "auto", // registra i comandi nativi delle skill quando supportati + text: true, // analizza i /command nei messaggi chat + bash: false, // consente ! (alias: /bash) bashForegroundMs: 2000, - config: false, // allow /config - mcp: false, // allow /mcp - plugins: false, // allow /plugins - debug: false, // allow /debug - restart: true, // allow /restart + gateway restart tool + config: false, // consente /config + mcp: false, // consente /mcp + plugins: false, // consente /plugins + debug: false, // consente /debug + restart: true, // consente /restart + strumento di riavvio del gateway ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -852,37 +852,37 @@ Includi il tuo numero in `allowFrom` per abilitare la modalità self-chat (ignor - Questo blocco configura le superfici dei comandi. Per il catalogo corrente dei comandi integrati + bundled, vedi [Slash Commands](/it/tools/slash-commands). -- Questa pagina è un **riferimento delle chiavi di configurazione**, non il catalogo completo dei comandi. I comandi posseduti da canali/plugin come QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` e Talk `/voice` sono documentati nelle rispettive pagine di canale/plugin e in [Slash Commands](/it/tools/slash-commands). -- I comandi di testo devono essere messaggi **autonomi** con `/` iniziale. +- Questa pagina è un **riferimento delle chiavi di configurazione**, non il catalogo completo dei comandi. I comandi posseduti da canali/plugin, come QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` e Talk `/voice`, sono documentati nelle rispettive pagine del canale/plugin e in [Slash Commands](/it/tools/slash-commands). +- I comandi testuali devono essere messaggi **autonomi** con `/` iniziale. - `native: "auto"` attiva i comandi nativi per Discord/Telegram, lascia Slack disattivato. - `nativeSkills: "auto"` attiva i comandi nativi delle Skills per Discord/Telegram, lascia Slack disattivato. - Override per canale: `channels.discord.commands.native` (bool o `"auto"`). `false` cancella i comandi registrati in precedenza. -- Sovrascrivi la registrazione nativa delle Skills per canale con `channels..commands.nativeSkills`. +- Sovrascrivi la registrazione delle skill native per canale con `channels..commands.nativeSkills`. - `channels.telegram.customCommands` aggiunge voci extra al menu del bot Telegram. - `bash: true` abilita `! ` per la shell host. Richiede `tools.elevated.enabled` e il mittente in `tools.elevated.allowFrom.`. -- `config: true` abilita `/config` (legge/scrive `openclaw.json`). Per i client gateway `chat.send`, le scritture persistenti `/config set|unset` richiedono anche `operator.admin`; il comando in sola lettura `/config show` resta disponibile ai normali client operatore con ambito di scrittura. -- `mcp: true` abilita `/mcp` per la configurazione del server MCP gestito da OpenClaw sotto `mcp.servers`. -- `plugins: true` abilita `/plugins` per rilevamento plugin, installazione e controlli di abilitazione/disabilitazione. -- `channels..configWrites` controlla le mutazioni di configurazione per canale (predefinito: true). -- Per i canali multi-account, `channels..accounts..configWrites` controlla anche le scritture che puntano a quell'account (ad esempio `/allowlist --config --account ` o `/config set channels..accounts....`). +- `config: true` abilita `/config` (legge/scrive `openclaw.json`). Per i client gateway `chat.send`, le scritture persistenti `/config set|unset` richiedono anche `operator.admin`; il solo accesso in lettura `/config show` resta disponibile per i normali client operator con ambito di scrittura. +- `mcp: true` abilita `/mcp` per la configurazione dei server MCP gestiti da OpenClaw sotto `mcp.servers`. +- `plugins: true` abilita `/plugins` per il rilevamento dei plugin, l'installazione e i controlli di abilitazione/disabilitazione. +- `channels..configWrites` regola le mutazioni della configurazione per canale (predefinito: true). +- Per i canali multi-account, anche `channels..accounts..configWrites` regola le scritture che hanno come destinazione quell'account (ad esempio `/allowlist --config --account ` o `/config set channels..accounts....`). - `restart: false` disabilita `/restart` e le azioni dello strumento di riavvio del gateway. Predefinito: `true`. -- `ownerAllowFrom` è la allowlist esplicita del proprietario per comandi/strumenti solo proprietario. È separata da `allowFrom`. +- `ownerAllowFrom` è l'allowlist esplicita del proprietario per i comandi/strumenti riservati al proprietario. È separata da `allowFrom`. - `ownerDisplay: "hash"` applica l'hash agli ID del proprietario nel prompt di sistema. Imposta `ownerDisplaySecret` per controllare l'hashing. -- `allowFrom` è per-provider. Quando è impostato, è l'**unica** fonte di autorizzazione (le allowlist/associazioni del canale e `useAccessGroups` vengono ignorati). +- `allowFrom` è per provider. Quando è impostato, è l'**unica** fonte di autorizzazione (le allowlist/l'abbinamento del canale e `useAccessGroups` vengono ignorati). - `useAccessGroups: false` consente ai comandi di bypassare i criteri dei gruppi di accesso quando `allowFrom` non è impostato. - Mappa della documentazione dei comandi: - catalogo integrato + bundled: [Slash Commands](/it/tools/slash-commands) - - superfici di comando specifiche del canale: [Channels](/it/channels) + - superfici dei comandi specifiche del canale: [Channels](/it/channels) - comandi QQ Bot: [QQ Bot](/it/channels/qqbot) - - comandi di associazione: [Pairing](/it/channels/pairing) + - comandi di abbinamento: [Pairing](/it/channels/pairing) - comando card di LINE: [LINE](/it/channels/line) - - dreaming della memoria: [Dreaming](/it/concepts/dreaming) + - Dreaming della memoria: [Dreaming](/it/concepts/dreaming) --- -## Valori predefiniti degli agenti +## Valori predefiniti dell'agente ### `agents.defaults.workspace` @@ -896,7 +896,7 @@ Predefinito: `~/.openclaw/workspace`. ### `agents.defaults.repoRoot` -Radice del repository facoltativa mostrata nella riga Runtime del prompt di sistema. Se non impostata, OpenClaw la rileva automaticamente risalendo dalla workspace. +Radice opzionale del repository mostrata nella riga Runtime del prompt di sistema. Se non impostata, OpenClaw la rileva automaticamente risalendo dalla workspace. ```json5 { @@ -906,7 +906,7 @@ Radice del repository facoltativa mostrata nella riga Runtime del prompt di sist ### `agents.defaults.skills` -Allowlist predefinita facoltativa delle Skills per gli agenti che non impostano +Allowlist predefinita opzionale di Skills per gli agenti che non impostano `agents.list[].skills`. ```json5 @@ -914,9 +914,9 @@ Allowlist predefinita facoltativa delle Skills per gli agenti che non impostano agents: { defaults: { skills: ["github", "weather"] }, list: [ - { id: "writer" }, // inherits github, weather - { id: "docs", skills: ["docs-search"] }, // replaces defaults - { id: "locked-down", skills: [] }, // no skills + { id: "writer" }, // eredita github, weather + { id: "docs", skills: ["docs-search"] }, // sostituisce i valori predefiniti + { id: "locked-down", skills: [] }, // nessuna skill ], }, } @@ -924,8 +924,8 @@ Allowlist predefinita facoltativa delle Skills per gli agenti che non impostano - Ometti `agents.defaults.skills` per avere Skills senza restrizioni per impostazione predefinita. - Ometti `agents.list[].skills` per ereditare i valori predefiniti. -- Imposta `agents.list[].skills: []` per non avere Skills. -- Un elenco non vuoto `agents.list[].skills` è l'insieme finale per quell'agente; non viene unito ai valori predefiniti. +- Imposta `agents.list[].skills: []` per nessuna Skills. +- Un elenco non vuoto in `agents.list[].skills` è l'insieme finale per quell'agente; non viene unito ai valori predefiniti. ### `agents.defaults.skipBootstrap` @@ -941,7 +941,7 @@ Disabilita la creazione automatica dei file bootstrap della workspace (`AGENTS.m Controlla quando i file bootstrap della workspace vengono iniettati nel prompt di sistema. Predefinito: `"always"`. -- `"continuation-skip"`: i turni di continuazione sicura (dopo una risposta completata dell'assistente) saltano la reiniezione del bootstrap della workspace, riducendo la dimensione del prompt. Le esecuzioni heartbeat e i tentativi successivi alla compattazione ricostruiscono comunque il contesto. +- `"continuation-skip"`: i turni di continuazione sicura (dopo una risposta completata dell'assistente) saltano la re-iniezione del bootstrap della workspace, riducendo la dimensione del prompt. Le esecuzioni Heartbeat e i tentativi successivi alla Compaction ricostruiscono comunque il contesto. ```json5 { @@ -974,8 +974,8 @@ Numero massimo totale di caratteri iniettati in tutti i file bootstrap della wor Controlla il testo di avviso visibile all'agente quando il contesto bootstrap viene troncato. Predefinito: `"once"`. -- `"off"`: non iniettare mai testo di avviso nel prompt di sistema. -- `"once"`: inietta l'avviso una sola volta per ogni firma di troncamento univoca (consigliato). +- `"off"`: non iniettare mai il testo di avviso nel prompt di sistema. +- `"once"`: inietta l'avviso una volta per ogni firma di troncamento univoca (consigliato). - `"always"`: inietta l'avviso a ogni esecuzione quando esiste un troncamento. ```json5 @@ -986,10 +986,10 @@ Predefinito: `"once"`. ### `agents.defaults.imageMaxDimensionPx` -Dimensione massima in pixel del lato più lungo dell'immagine nei blocchi immagine di transcript/strumenti prima delle chiamate al provider. +Dimensione massima in pixel del lato più lungo dell'immagine nei blocchi immagine del transcript/strumento prima delle chiamate al provider. Predefinito: `1200`. -Valori più bassi riducono di solito l'uso di vision token e la dimensione del payload della richiesta per esecuzioni ricche di screenshot. +Valori più bassi di solito riducono l'uso di vision-token e la dimensione del payload della richiesta per esecuzioni ricche di screenshot. Valori più alti preservano più dettaglio visivo. ```json5 @@ -1000,7 +1000,7 @@ Valori più alti preservano più dettaglio visivo. ### `agents.defaults.userTimezone` -Fuso orario per il contesto del prompt di sistema (non per i timestamp dei messaggi). Usa come fallback il fuso orario dell'host. +Fuso orario per il contesto del prompt di sistema (non i timestamp dei messaggi). Se assente, usa il fuso orario dell'host. ```json5 { @@ -1010,7 +1010,7 @@ Fuso orario per il contesto del prompt di sistema (non per i timestamp dei messa ### `agents.defaults.timeFormat` -Formato orario nel prompt di sistema. Predefinito: `auto` (preferenza del sistema operativo). +Formato dell'ora nel prompt di sistema. Predefinito: `auto` (preferenza del sistema operativo). ```json5 { @@ -1048,9 +1048,9 @@ Formato orario nel prompt di sistema. Predefinito: `auto` (preferenza del sistem primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // global default provider params + params: { cacheRetention: "long" }, // parametri predefiniti globali del provider embeddedHarness: { - runtime: "auto", // auto | pi | registered harness id, e.g. codex + runtime: "auto", // auto | pi | harness id registrato, ad es. codex fallback: "pi", // pi | none }, pdfMaxBytesMb: 10, @@ -1074,41 +1074,41 @@ Formato orario nel prompt di sistema. Predefinito: `auto` (preferenza del sistem - Usato dal percorso dello strumento `image` come configurazione del modello di visione. - Usato anche come routing di fallback quando il modello selezionato/predefinito non può accettare input immagine. - `imageGenerationModel`: accetta sia una stringa (`"provider/model"`) sia un oggetto (`{ primary, fallbacks }`). - - Usato dalla capacità condivisa di generazione immagini e da qualsiasi futura superficie di strumento/plugin che generi immagini. - - Valori tipici: `google/gemini-3.1-flash-image-preview` per la generazione immagini Gemini nativa, `fal/fal-ai/flux/dev` per fal, oppure `openai/gpt-image-1` per OpenAI Images. + - Usato dalla capability condivisa di generazione immagini e da qualsiasi futura superficie di strumenti/plugin che generi immagini. + - Valori tipici: `google/gemini-3.1-flash-image-preview` per la generazione nativa di immagini Gemini, `fal/fal-ai/flux/dev` per fal, oppure `openai/gpt-image-1` per OpenAI Images. - Se selezioni direttamente un provider/modello, configura anche l'autenticazione/la chiave API del provider corrispondente (ad esempio `GEMINI_API_KEY` o `GOOGLE_API_KEY` per `google/*`, `OPENAI_API_KEY` per `openai/*`, `FAL_KEY` per `fal/*`). - - Se omesso, `image_generate` può comunque dedurre un provider predefinito supportato da autenticazione. Prova prima il provider predefinito corrente, poi i restanti provider di generazione immagini registrati in ordine di ID provider. + - Se omesso, `image_generate` può comunque dedurre un provider predefinito supportato da autenticazione. Prova prima il provider predefinito corrente, poi i restanti provider di generazione immagini registrati in ordine di provider-id. - `musicGenerationModel`: accetta sia una stringa (`"provider/model"`) sia un oggetto (`{ primary, fallbacks }`). - - Usato dalla capacità condivisa di generazione musicale e dallo strumento integrato `music_generate`. - - Valori tipici: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` o `minimax/music-2.5+`. - - Se omesso, `music_generate` può comunque dedurre un provider predefinito supportato da autenticazione. Prova prima il provider predefinito corrente, poi i restanti provider di generazione musicale registrati in ordine di ID provider. + - Usato dalla capability condivisa di generazione musicale e dallo strumento integrato `music_generate`. + - Valori tipici: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` oppure `minimax/music-2.5+`. + - Se omesso, `music_generate` può comunque dedurre un provider predefinito supportato da autenticazione. Prova prima il provider predefinito corrente, poi i restanti provider di generazione musicale registrati in ordine di provider-id. - Se selezioni direttamente un provider/modello, configura anche l'autenticazione/la chiave API del provider corrispondente. - `videoGenerationModel`: accetta sia una stringa (`"provider/model"`) sia un oggetto (`{ primary, fallbacks }`). - - Usato dalla capacità condivisa di generazione video e dallo strumento integrato `video_generate`. - - Valori tipici: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` o `qwen/wan2.7-r2v`. - - Se omesso, `video_generate` può comunque dedurre un provider predefinito supportato da autenticazione. Prova prima il provider predefinito corrente, poi i restanti provider di generazione video registrati in ordine di ID provider. + - Usato dalla capability condivisa di generazione video e dallo strumento integrato `video_generate`. + - Valori tipici: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` oppure `qwen/wan2.7-r2v`. + - Se omesso, `video_generate` può comunque dedurre un provider predefinito supportato da autenticazione. Prova prima il provider predefinito corrente, poi i restanti provider di generazione video registrati in ordine di provider-id. - Se selezioni direttamente un provider/modello, configura anche l'autenticazione/la chiave API del provider corrispondente. - Il provider bundled di generazione video Qwen supporta fino a 1 video in uscita, 1 immagine in ingresso, 4 video in ingresso, durata di 10 secondi e opzioni a livello provider `size`, `aspectRatio`, `resolution`, `audio` e `watermark`. - `pdfModel`: accetta sia una stringa (`"provider/model"`) sia un oggetto (`{ primary, fallbacks }`). - Usato dallo strumento `pdf` per il routing del modello. - - Se omesso, lo strumento PDF usa come fallback `imageModel`, poi il modello di sessione/predefinito risolto. -- `pdfMaxBytesMb`: limite predefinito della dimensione PDF per lo strumento `pdf` quando `maxBytesMb` non viene passato al momento della chiamata. -- `pdfMaxPages`: numero massimo predefinito di pagine considerate dalla modalità fallback di estrazione nello strumento `pdf`. + - Se omesso, lo strumento PDF usa come fallback `imageModel`, poi il modello risolto della sessione/predefinito. +- `pdfMaxBytesMb`: limite predefinito di dimensione PDF per lo strumento `pdf` quando `maxBytesMb` non viene passato al momento della chiamata. +- `pdfMaxPages`: numero massimo predefinito di pagine considerate dalla modalità di fallback di estrazione nello strumento `pdf`. - `verboseDefault`: livello verboso predefinito per gli agenti. Valori: `"off"`, `"on"`, `"full"`. Predefinito: `"off"`. - `elevatedDefault`: livello predefinito di output elevato per gli agenti. Valori: `"off"`, `"on"`, `"ask"`, `"full"`. Predefinito: `"on"`. -- `model.primary`: formato `provider/model` (ad esempio `openai/gpt-5.4`). Se ometti il provider, OpenClaw prova prima un alias, poi una corrispondenza univoca del provider configurato per quell'esatto ID modello e solo dopo usa come fallback il provider predefinito configurato (comportamento di compatibilità deprecato, quindi preferisci `provider/model` esplicito). Se quel provider non espone più il modello predefinito configurato, OpenClaw usa come fallback il primo provider/modello configurato invece di mostrare un valore predefinito obsoleto di un provider rimosso. -- `models`: il catalogo e la allowlist dei modelli configurati per `/model`. Ogni voce può includere `alias` (scorciatoia) e `params` (specifici del provider, ad esempio `temperature`, `maxTokens`, `cacheRetention`, `context1m`). -- `params`: parametri globali predefiniti del provider applicati a tutti i modelli. Impostati in `agents.defaults.params` (ad es. `{ cacheRetention: "long" }`). -- Precedenza di unione di `params` (config): `agents.defaults.params` (base globale) viene sovrascritto da `agents.defaults.models["provider/model"].params` (per modello), quindi `agents.list[].params` (ID agente corrispondente) sovrascrive per chiave. Vedi [Prompt Caching](/it/reference/prompt-caching) per i dettagli. -- `embeddedHarness`: criterio predefinito del runtime embedded a basso livello dell'agente. Usa `runtime: "auto"` per lasciare che gli harness plugin registrati rivendichino i modelli supportati, `runtime: "pi"` per forzare l'harness PI integrato, oppure un ID harness registrato come `runtime: "codex"`. Imposta `fallback: "none"` per disabilitare il fallback automatico a PI. -- I writer di configurazione che modificano questi campi (ad esempio `/models set`, `/models set-image` e i comandi di aggiunta/rimozione fallback) salvano la forma canonica a oggetto e preservano gli elenchi fallback esistenti quando possibile. -- `maxConcurrent`: numero massimo di esecuzioni parallele di agenti tra le sessioni (ogni sessione resta comunque serializzata). Predefinito: 4. +- `model.primary`: formato `provider/model` (ad es. `openai/gpt-5.4`). Se ometti il provider, OpenClaw prova prima un alias, poi una corrispondenza univoca del provider configurato per quell'esatto model id, e solo dopo torna al provider predefinito configurato (comportamento di compatibilità deprecato, quindi è preferibile `provider/model` esplicito). Se quel provider non espone più il modello predefinito configurato, OpenClaw ripiega sul primo provider/modello configurato invece di mostrare un valore predefinito obsoleto di un provider rimosso. +- `models`: il catalogo di modelli configurato e l'allowlist per `/model`. Ogni voce può includere `alias` (scorciatoia) e `params` (specifici del provider, ad esempio `temperature`, `maxTokens`, `cacheRetention`, `context1m`). +- `params`: parametri predefiniti globali del provider applicati a tutti i modelli. Si impostano in `agents.defaults.params` (ad es. `{ cacheRetention: "long" }`). +- Precedenza di unione di `params` (config): `agents.defaults.params` (base globale) è sovrascritto da `agents.defaults.models["provider/model"].params` (per modello), poi `agents.list[].params` (ID agente corrispondente) sovrascrive per chiave. Vedi [Prompt Caching](/it/reference/prompt-caching) per i dettagli. +- `embeddedHarness`: criterio predefinito di runtime embedded a basso livello per l'agente. Usa `runtime: "auto"` per lasciare che gli harness dei plugin registrati rivendichino i modelli supportati, `runtime: "pi"` per forzare l'harness PI integrato, oppure un id harness registrato come `runtime: "codex"`. Imposta `fallback: "none"` per disabilitare il fallback automatico a Pi. +- Gli scrittori di configurazione che modificano questi campi (ad esempio `/models set`, `/models set-image` e i comandi di aggiunta/rimozione fallback) salvano la forma oggetto canonica e preservano gli elenchi fallback esistenti quando possibile. +- `maxConcurrent`: numero massimo di esecuzioni parallele degli agenti tra le sessioni (ogni sessione resta comunque serializzata). Predefinito: 4. ### `agents.defaults.embeddedHarness` -`embeddedHarness` controlla quale esecutore a basso livello esegue i turni degli agenti embedded. -La maggior parte delle distribuzioni dovrebbe mantenere il valore predefinito `{ runtime: "auto", fallback: "pi" }`. -Usalo quando un plugin attendibile fornisce un harness nativo, come l'harness bundled dell'app-server Codex. +`embeddedHarness` controlla quale esecutore di basso livello esegue i turni embedded dell'agente. +La maggior parte dei deployment dovrebbe mantenere il valore predefinito `{ runtime: "auto", fallback: "pi" }`. +Usalo quando un plugin attendibile fornisce un harness nativo, come l'harness bundled del server app Codex. ```json5 { @@ -1124,11 +1124,11 @@ Usalo quando un plugin attendibile fornisce un harness nativo, come l'harness bu } ``` -- `runtime`: `"auto"`, `"pi"` o un ID harness plugin registrato. Il plugin bundled Codex registra `codex`. -- `fallback`: `"pi"` o `"none"`. `"pi"` mantiene l'harness PI integrato come fallback di compatibilità. `"none"` fa fallire la selezione di un harness plugin mancante o non supportato invece di usare silenziosamente PI. -- Override d'ambiente: `OPENCLAW_AGENT_RUNTIME=` sovrascrive `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` disabilita il fallback a PI per quel processo. -- Per distribuzioni solo Codex, imposta `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` e `embeddedHarness.fallback: "none"`. -- Questo controlla solo l'harness della chat embedded. Generazione media, visione, PDF, musica, video e TTS usano comunque le rispettive impostazioni provider/modello. +- `runtime`: `"auto"`, `"pi"` o un id harness plugin registrato. Il plugin bundled Codex registra `codex`. +- `fallback`: `"pi"` o `"none"`. `"pi"` mantiene l'harness PI integrato come fallback di compatibilità. `"none"` fa sì che una selezione di harness plugin mancante o non supportata fallisca invece di usare silenziosamente Pi. +- Override da ambiente: `OPENCLAW_AGENT_RUNTIME=` sovrascrive `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` disabilita il fallback a Pi per quel processo. +- Per deployment solo-Codex, imposta `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` e `embeddedHarness.fallback: "none"`. +- Questo controlla solo l'harness di chat embedded. Generazione media, visione, PDF, musica, video e TTS continuano a usare le rispettive impostazioni provider/modello. **Scorciatoie alias integrate** (si applicano solo quando il modello è in `agents.defaults.models`): @@ -1143,7 +1143,7 @@ Usalo quando un plugin attendibile fornisce un harness nativo, come l'harness bu | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -Gli alias da te configurati hanno sempre la precedenza su quelli predefiniti. +Gli alias configurati da te hanno sempre la precedenza sui valori predefiniti. I modelli Z.AI GLM-4.x abilitano automaticamente la modalità thinking a meno che tu non imposti `--thinking off` o definisca tu stesso `agents.defaults.models["zai/"].params.thinking`. I modelli Z.AI abilitano `tool_stream` per impostazione predefinita per lo streaming delle chiamate agli strumenti. Imposta `agents.defaults.models["zai/"].params.tool_stream` su `false` per disabilitarlo. @@ -1151,7 +1151,7 @@ I modelli Anthropic Claude 4.6 usano per impostazione predefinita il thinking `a ### `agents.defaults.cliBackends` -Backend CLI facoltativi per esecuzioni di fallback solo testo (senza chiamate agli strumenti). Utili come backup quando i provider API falliscono. +Backend CLI opzionali per esecuzioni di fallback solo testuali (senza chiamate a strumenti). Utili come backup quando i provider API falliscono. ```json5 { @@ -1185,13 +1185,13 @@ Backend CLI facoltativi per esecuzioni di fallback solo testo (senza chiamate ag ### `agents.defaults.systemPromptOverride` -Sostituisce l'intero prompt di sistema assemblato da OpenClaw con una stringa fissa. Impostalo a livello predefinito (`agents.defaults.systemPromptOverride`) o per agente (`agents.list[].systemPromptOverride`). I valori per agente hanno la precedenza; un valore vuoto o composto solo da spazi viene ignorato. Utile per esperimenti controllati sui prompt. +Sostituisce l'intero prompt di sistema assemblato da OpenClaw con una stringa fissa. Impostalo a livello predefinito (`agents.defaults.systemPromptOverride`) o per agente (`agents.list[].systemPromptOverride`). I valori per agente hanno la precedenza; un valore vuoto o composto solo da spazi viene ignorato. Utile per esperimenti controllati sul prompt. ```json5 { agents: { defaults: { - systemPromptOverride: "You are a helpful assistant.", + systemPromptOverride: "Sei un assistente utile.", }, }, } @@ -1199,24 +1199,24 @@ Sostituisce l'intero prompt di sistema assemblato da OpenClaw con una stringa fi ### `agents.defaults.heartbeat` -Esecuzioni heartbeat periodiche. +Esecuzioni periodiche Heartbeat. ```json5 { agents: { defaults: { heartbeat: { - every: "30m", // 0m disables + every: "30m", // 0m disabilita model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt - lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files - isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) + includeSystemPromptSection: true, // predefinito: true; false omette la sezione Heartbeat dal prompt di sistema + lightContext: false, // predefinito: false; true mantiene solo HEARTBEAT.md dai file bootstrap della workspace + isolatedSession: false, // predefinito: false; true esegue ogni heartbeat in una sessione nuova (senza cronologia conversazionale) session: "main", to: "+15555550123", - directPolicy: "allow", // allow (default) | block - target: "none", // default: none | options: last | whatsapp | telegram | discord | ... - prompt: "Read HEARTBEAT.md if it exists...", + directPolicy: "allow", // allow (predefinito) | block + target: "none", // predefinito: none | opzioni: last | whatsapp | telegram | discord | ... + prompt: "Leggi HEARTBEAT.md se esiste...", ackMaxChars: 300, suppressToolErrorWarnings: false, timeoutSeconds: 45, @@ -1226,15 +1226,15 @@ Esecuzioni heartbeat periodiche. } ``` -- `every`: stringa di durata (ms/s/m/h). Predefinito: `30m` (autenticazione con chiave API) o `1h` (autenticazione OAuth). Imposta `0m` per disabilitare. +- `every`: stringa di durata (ms/s/m/h). Predefinito: `30m` (autenticazione con chiave API) oppure `1h` (autenticazione OAuth). Imposta `0m` per disabilitare. - `includeSystemPromptSection`: quando è false, omette la sezione Heartbeat dal prompt di sistema e salta l'iniezione di `HEARTBEAT.md` nel contesto bootstrap. Predefinito: `true`. -- `suppressToolErrorWarnings`: quando è true, sopprime i payload di avviso degli errori degli strumenti durante le esecuzioni heartbeat. -- `timeoutSeconds`: tempo massimo in secondi consentito per un turno agente heartbeat prima che venga interrotto. Lascialo non impostato per usare `agents.defaults.timeoutSeconds`. -- `directPolicy`: criterio di consegna diretta/DM. `allow` (predefinito) consente la consegna a target diretto. `block` sopprime la consegna a target diretto ed emette `reason=dm-blocked`. -- `lightContext`: quando è true, le esecuzioni heartbeat usano un contesto bootstrap leggero e mantengono solo `HEARTBEAT.md` tra i file bootstrap della workspace. -- `isolatedSession`: quando è true, ogni heartbeat viene eseguito in una sessione nuova senza cronologia conversazionale precedente. Stesso schema di isolamento di cron `sessionTarget: "isolated"`. Riduce il costo in token per heartbeat da circa 100K a circa 2-5K token. -- Per agente: imposta `agents.list[].heartbeat`. Quando un qualsiasi agente definisce `heartbeat`, gli heartbeat vengono eseguiti **solo da quegli agenti**. -- Gli heartbeat eseguono turni agente completi: intervalli più brevi consumano più token. +- `suppressToolErrorWarnings`: quando è true, sopprime i payload di avviso sugli errori degli strumenti durante le esecuzioni Heartbeat. +- `timeoutSeconds`: tempo massimo in secondi consentito per un turno agente Heartbeat prima che venga interrotto. Se non impostato, usa `agents.defaults.timeoutSeconds`. +- `directPolicy`: criterio di consegna diretta/DM. `allow` (predefinito) consente la consegna a target diretti. `block` sopprime la consegna a target diretti ed emette `reason=dm-blocked`. +- `lightContext`: quando è true, le esecuzioni Heartbeat usano un contesto bootstrap leggero e mantengono solo `HEARTBEAT.md` tra i file bootstrap della workspace. +- `isolatedSession`: quando è true, ogni heartbeat viene eseguito in una sessione nuova senza cronologia conversazionale precedente. Stesso schema di isolamento del Cron `sessionTarget: "isolated"`. Riduce il costo in token per heartbeat da ~100K a ~2-5K token. +- Per agente: imposta `agents.list[].heartbeat`. Quando un qualsiasi agente definisce `heartbeat`, **solo quegli agenti** eseguono heartbeat. +- Gli heartbeat eseguono turni completi dell'agente: intervalli più brevi consumano più token. ### `agents.defaults.compaction` @@ -1244,19 +1244,19 @@ Esecuzioni heartbeat periodiche. defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // id di un plugin provider di compattazione registrato (opzionale) + provider: "my-provider", // id di un plugin provider di Compaction registrato (opzionale) timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserva esattamente gli ID di deployment, gli ID dei ticket e le coppie host:port.", // usato quando identifierPolicy=custom - postCompactionSections: ["Session Startup", "Red Lines"], // [] disabilita la reiniezione - model: "openrouter/anthropic/claude-sonnet-4-6", // override opzionale del modello solo per la compattazione - notifyUser: true, // invia un breve avviso quando inizia la compattazione (predefinito: false) + identifierInstructions: "Preserva esattamente gli ID di deployment, gli ID ticket e le coppie host:port.", // usato quando identifierPolicy=custom + postCompactionSections: ["Session Startup", "Red Lines"], // [] disabilita la re-iniezione + model: "openrouter/anthropic/claude-sonnet-4-6", // override opzionale del modello solo per la Compaction + notifyUser: true, // invia un breve avviso quando inizia la Compaction (predefinito: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, - systemPrompt: "La sessione si sta avvicinando alla compattazione. Archivia ora i ricordi durevoli.", - prompt: "Scrivi eventuali note durature in memory/YYYY-MM-DD.md; rispondi con l'esatto token silenzioso NO_REPLY se non c'è nulla da archiviare.", + systemPrompt: "La sessione si sta avvicinando alla Compaction. Archivia ora i ricordi durevoli.", + prompt: "Scrivi eventuali note durature in memory/YYYY-MM-DD.md; rispondi con il token silenzioso esatto NO_REPLY se non c'è nulla da archiviare.", }, }, }, @@ -1264,19 +1264,19 @@ Esecuzioni heartbeat periodiche. } ``` -- `mode`: `default` o `safeguard` (riepilogo suddiviso in blocchi per cronologie lunghe). Vedi [Compaction](/it/concepts/compaction). -- `provider`: id di un plugin provider di compattazione registrato. Quando impostato, viene chiamato `summarize()` del provider invece del riepilogo LLM integrato. In caso di errore, torna a quello integrato. Impostare un provider forza `mode: "safeguard"`. Vedi [Compaction](/it/concepts/compaction). -- `timeoutSeconds`: numero massimo di secondi consentiti per una singola operazione di compattazione prima che OpenClaw la interrompa. Predefinito: `900`. -- `identifierPolicy`: `strict` (predefinito), `off` o `custom`. `strict` antepone linee guida integrate per la conservazione di identificatori opachi durante il riepilogo della compattazione. -- `identifierInstructions`: testo personalizzato facoltativo per la conservazione degli identificatori usato quando `identifierPolicy=custom`. -- `postCompactionSections`: nomi facoltativi di sezioni H2/H3 di AGENTS.md da reiniettare dopo la compattazione. Il valore predefinito è `["Session Startup", "Red Lines"]`; imposta `[]` per disabilitare la reiniezione. Se non è impostato o viene impostato esplicitamente a quella coppia predefinita, anche le intestazioni meno recenti `Every Session`/`Safety` sono accettate come fallback legacy. -- `model`: override facoltativo `provider/model-id` solo per il riepilogo della compattazione. Usalo quando la sessione principale deve mantenere un modello ma i riepiloghi di compattazione devono essere eseguiti con un altro; se non impostato, la compattazione usa il modello primario della sessione. -- `notifyUser`: quando `true`, invia un breve avviso all'utente quando inizia la compattazione (per esempio, "Compattazione del contesto in corso..."). Disabilitato per impostazione predefinita per mantenere la compattazione silenziosa. -- `memoryFlush`: turno agentico silenzioso prima della compattazione automatica per archiviare ricordi durevoli. Saltato quando il workspace è in sola lettura. +- `mode`: `default` oppure `safeguard` (riepilogo suddiviso in blocchi per cronologie lunghe). Vedi [Compaction](/it/concepts/compaction). +- `provider`: id di un plugin provider di Compaction registrato. Quando è impostato, viene chiamato `summarize()` del provider invece del riepilogo LLM integrato. In caso di errore torna al comportamento integrato. Impostare un provider forza `mode: "safeguard"`. Vedi [Compaction](/it/concepts/compaction). +- `timeoutSeconds`: numero massimo di secondi consentiti per una singola operazione di Compaction prima che OpenClaw la interrompa. Predefinito: `900`. +- `identifierPolicy`: `strict` (predefinito), `off` oppure `custom`. `strict` antepone linee guida integrate per la conservazione di identificatori opachi durante il riepilogo della Compaction. +- `identifierInstructions`: testo personalizzato opzionale per la conservazione degli identificatori usato quando `identifierPolicy=custom`. +- `postCompactionSections`: nomi opzionali di sezioni H2/H3 di AGENTS.md da reiniettare dopo la Compaction. Predefinito: `["Session Startup", "Red Lines"]`; imposta `[]` per disabilitare la reiniezione. Quando non è impostato o è impostato esplicitamente su quella coppia predefinita, le intestazioni legacy `Every Session`/`Safety` sono accettate anche come fallback legacy. +- `model`: override opzionale `provider/model-id` solo per il riepilogo della Compaction. Usalo quando la sessione principale deve mantenere un modello ma i riepiloghi di Compaction devono essere eseguiti con un altro; se non impostato, la Compaction usa il modello primario della sessione. +- `notifyUser`: quando `true`, invia un breve avviso all'utente quando inizia la Compaction (ad esempio, "Compattazione del contesto..."). Disabilitato per impostazione predefinita per mantenere silenziosa la Compaction. +- `memoryFlush`: turno agentico silenzioso prima della Compaction automatica per archiviare ricordi durevoli. Viene saltato quando la workspace è in sola lettura. ### `agents.defaults.contextPruning` -Elimina i **vecchi risultati degli strumenti** dal contesto in memoria prima dell'invio all'LLM. **Non** modifica la cronologia della sessione su disco. +Rimuove **i vecchi risultati degli strumenti** dal contesto in memoria prima dell'invio all'LLM. **Non** modifica la cronologia della sessione su disco. ```json5 { @@ -1300,19 +1300,19 @@ Elimina i **vecchi risultati degli strumenti** dal contesto in memoria prima del -- `mode: "cache-ttl"` abilita i passaggi di eliminazione. -- `ttl` controlla con quale frequenza l'eliminazione può essere eseguita di nuovo (dopo l'ultimo accesso alla cache). -- L'eliminazione prima riduce in modo parziale i risultati degli strumenti troppo grandi, poi cancella completamente i risultati più vecchi degli strumenti se necessario. +- `mode: "cache-ttl"` abilita i passaggi di pruning. +- `ttl` controlla ogni quanto il pruning può essere eseguito di nuovo (dopo l'ultimo accesso alla cache). +- Il pruning prima applica il soft-trim ai risultati degli strumenti troppo grandi, poi, se necessario, cancella in modo completo i risultati degli strumenti più vecchi. -**Soft-trim** mantiene l'inizio e la fine e inserisce `...` nel mezzo. +**Soft-trim** conserva l'inizio + la fine e inserisce `...` nel mezzo. **Hard-clear** sostituisce l'intero risultato dello strumento con il segnaposto. Note: -- I blocchi di immagini non vengono mai ridotti né cancellati. +- I blocchi immagine non vengono mai tagliati/cancellati. - I rapporti sono basati sui caratteri (approssimativi), non su conteggi esatti di token. -- Se esistono meno di `keepLastAssistants` messaggi assistant, l'eliminazione viene saltata. +- Se esistono meno di `keepLastAssistants` messaggi dell'assistente, il pruning viene saltato. @@ -1335,10 +1335,10 @@ Vedi [Session Pruning](/it/concepts/session-pruning) per i dettagli sul comporta ``` - I canali non Telegram richiedono `*.blockStreaming: true` esplicito per abilitare le risposte a blocchi. -- Override per canale: `channels..blockStreamingCoalesce` (e varianti per account). Signal/Slack/Discord/Google Chat usano per impostazione predefinita `minChars: 1500`. -- `humanDelay`: pausa casuale tra le risposte a blocchi. `natural` = 800–2500 ms. Override per agente: `agents.list[].humanDelay`. +- Override per canale: `channels..blockStreamingCoalesce` (e varianti per account). Signal/Slack/Discord/Google Chat usano come predefinito `minChars: 1500`. +- `humanDelay`: pausa casuale tra le risposte a blocchi. `natural` = 800–2500ms. Override per agente: `agents.list[].humanDelay`. -Vedi [Streaming](/it/concepts/streaming) per i dettagli su comportamento e suddivisione in blocchi. +Vedi [Streaming](/it/concepts/streaming) per i dettagli su comportamento + suddivisione in blocchi. ### Indicatori di digitazione @@ -1353,7 +1353,7 @@ Vedi [Streaming](/it/concepts/streaming) per i dettagli su comportamento e suddi } ``` -- Valori predefiniti: `instant` per chat dirette/menzioni, `message` per chat di gruppo senza menzione. +- Predefiniti: `instant` per chat dirette/menzioni, `message` per chat di gruppo senza menzione. - Override per sessione: `session.typingMode`, `session.typingIntervalSeconds`. Vedi [Typing Indicators](/it/concepts/typing-indicators). @@ -1362,7 +1362,7 @@ Vedi [Typing Indicators](/it/concepts/typing-indicators). ### `agents.defaults.sandbox` -Sandboxing facoltativo per l'agente incorporato. Vedi [Sandboxing](/it/gateway/sandboxing) per la guida completa. +Sandboxing opzionale per l'agente embedded. Vedi [Sandboxing](/it/gateway/sandboxing) per la guida completa. ```json5 { @@ -1457,48 +1457,48 @@ Sandboxing facoltativo per l'agente incorporato. Vedi [Sandboxing](/it/gateway/s } ``` - + **Backend:** - `docker`: runtime Docker locale (predefinito) -- `ssh`: runtime remoto generico basato su SSH +- `ssh`: runtime remoto generico supportato da SSH - `openshell`: runtime OpenShell -Quando viene selezionato `backend: "openshell"`, le impostazioni specifiche del runtime vengono spostate in +Quando viene selezionato `backend: "openshell"`, le impostazioni specifiche del runtime si spostano in `plugins.entries.openshell.config`. **Configurazione del backend SSH:** -- `target`: destinazione SSH nel formato `user@host[:port]` +- `target`: target SSH nel formato `user@host[:port]` - `command`: comando del client SSH (predefinito: `ssh`) -- `workspaceRoot`: radice remota assoluta usata per workspace per ambito +- `workspaceRoot`: radice remota assoluta usata per le workspace per scope - `identityFile` / `certificateFile` / `knownHostsFile`: file locali esistenti passati a OpenSSH -- `identityData` / `certificateData` / `knownHostsData`: contenuti inline o SecretRef che OpenClaw materializza in file temporanei in fase di esecuzione -- `strictHostKeyChecking` / `updateHostKeys`: opzioni del criterio delle chiavi host di OpenSSH +- `identityData` / `certificateData` / `knownHostsData`: contenuti inline o SecretRef che OpenClaw materializza in file temporanei a runtime +- `strictHostKeyChecking` / `updateHostKeys`: parametri del criterio delle chiavi host di OpenSSH **Precedenza di autenticazione SSH:** -- `identityData` ha priorità su `identityFile` -- `certificateData` ha priorità su `certificateFile` -- `knownHostsData` ha priorità su `knownHostsFile` -- I valori `*Data` basati su SecretRef vengono risolti dall'istantanea attiva del runtime dei segreti prima dell'avvio della sessione sandbox +- `identityData` ha la precedenza su `identityFile` +- `certificateData` ha la precedenza su `certificateFile` +- `knownHostsData` ha la precedenza su `knownHostsFile` +- I valori `*Data` supportati da SecretRef vengono risolti dallo snapshot runtime attivo dei segreti prima dell'avvio della sessione sandbox **Comportamento del backend SSH:** -- inizializza il workspace remoto una volta dopo la creazione o ricreazione -- poi mantiene canonico il workspace SSH remoto -- instrada `exec`, gli strumenti per i file e i percorsi dei contenuti multimediali tramite SSH -- non sincronizza automaticamente sul host le modifiche remote -- non supporta container browser sandbox +- inizializza la workspace remota una sola volta dopo la creazione o ricreazione +- poi mantiene canonica la workspace SSH remota +- instrada `exec`, gli strumenti per i file e i percorsi dei media tramite SSH +- non sincronizza automaticamente di nuovo sull'host le modifiche remote +- non supporta container browser nel sandbox -**Accesso al workspace:** +**Accesso alla workspace:** -- `none`: workspace sandbox per ambito sotto `~/.openclaw/sandboxes` -- `ro`: workspace sandbox in `/workspace`, workspace dell'agente montato in sola lettura in `/agent` -- `rw`: workspace dell'agente montato in lettura/scrittura in `/workspace` +- `none`: workspace sandbox per scope sotto `~/.openclaw/sandboxes` +- `ro`: workspace sandbox in `/workspace`, workspace dell'agente montata in sola lettura in `/agent` +- `rw`: workspace dell'agente montata in lettura/scrittura in `/workspace` -**Ambito:** +**Scope:** - `session`: container + workspace per sessione - `agent`: un container + workspace per agente (predefinito) @@ -1532,32 +1532,32 @@ Quando viene selezionato `backend: "openshell"`, le impostazioni specifiche del **Modalità OpenShell:** -- `mirror`: inizializza il remoto dal locale prima di exec, sincronizza indietro dopo exec; il workspace locale resta canonico -- `remote`: inizializza il remoto una volta quando la sandbox viene creata, poi mantiene canonico il workspace remoto +- `mirror`: inizializza il remoto dal locale prima di exec, sincronizza di ritorno dopo exec; la workspace locale resta canonica +- `remote`: inizializza il remoto una volta quando il sandbox viene creato, poi mantiene canonica la workspace remota -In modalità `remote`, le modifiche locali sull'host effettuate fuori da OpenClaw non vengono sincronizzate automaticamente nella sandbox dopo il passaggio di inizializzazione. -Il trasporto avviene tramite SSH nella sandbox OpenShell, ma il plugin gestisce il ciclo di vita della sandbox e l'eventuale sincronizzazione mirror. +In modalità `remote`, le modifiche locali sull'host effettuate fuori da OpenClaw non vengono sincronizzate automaticamente nel sandbox dopo il passaggio di inizializzazione. +Il trasporto usa SSH verso il sandbox OpenShell, ma il plugin gestisce il ciclo di vita del sandbox e l'eventuale sincronizzazione mirror. **`setupCommand`** viene eseguito una volta dopo la creazione del container (tramite `sh -lc`). Richiede uscita di rete, root scrivibile, utente root. **I container usano per impostazione predefinita `network: "none"`** — imposta `"bridge"` (o una rete bridge personalizzata) se l'agente necessita di accesso in uscita. `"host"` è bloccato. `"container:"` è bloccato per impostazione predefinita a meno che tu non imposti esplicitamente -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (uso di emergenza). +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (break-glass). -**Gli allegati in ingresso** vengono preparati in `media/inbound/*` nel workspace attivo. +**Gli allegati in ingresso** vengono preparati in `media/inbound/*` nella workspace attiva. **`docker.binds`** monta directory host aggiuntive; i bind globali e per agente vengono uniti. -**Browser sandbox** (`sandbox.browser.enabled`): Chromium + CDP in un container. L'URL di noVNC viene inserito nel prompt di sistema. Non richiede `browser.enabled` in `openclaw.json`. -L'accesso osservatore a noVNC usa l'autenticazione VNC per impostazione predefinita e OpenClaw emette un URL con token di breve durata (invece di esporre la password nell'URL condiviso). +**Browser sandboxed** (`sandbox.browser.enabled`): Chromium + CDP in un container. L'URL noVNC viene iniettata nel prompt di sistema. Non richiede `browser.enabled` in `openclaw.json`. +L'accesso osservatore noVNC usa per impostazione predefinita l'autenticazione VNC e OpenClaw emette un URL con token a breve durata (invece di esporre la password nell'URL condiviso). -- `allowHostControl: false` (predefinito) impedisce alle sessioni sandbox di puntare al browser host. -- `network` usa per impostazione predefinita `openclaw-sandbox-browser` (rete bridge dedicata). Imposta `bridge` solo quando vuoi esplicitamente una connettività bridge globale. -- `cdpSourceRange` limita facoltativamente l'ingresso CDP al bordo del container a un intervallo CIDR (per esempio `172.21.0.1/32`). -- `sandbox.browser.binds` monta directory host aggiuntive solo nel container del browser sandbox. Quando impostato (incluso `[]`), sostituisce `docker.binds` per il container del browser. +- `allowHostControl: false` (predefinito) impedisce alle sessioni sandboxed di puntare al browser dell'host. +- `network` ha come predefinito `openclaw-sandbox-browser` (rete bridge dedicata). Imposta `bridge` solo quando vuoi esplicitamente connettività bridge globale. +- `cdpSourceRange` limita facoltativamente l'ingresso CDP al bordo del container a un intervallo CIDR (ad esempio `172.21.0.1/32`). +- `sandbox.browser.binds` monta directory host aggiuntive solo nel container del browser sandboxed. Quando è impostato (incluso `[]`), sostituisce `docker.binds` per il container del browser. - I valori predefiniti di avvio sono definiti in `scripts/sandbox-browser-entrypoint.sh` e ottimizzati per host container: - `--remote-debugging-address=127.0.0.1` - - `--remote-debugging-port=` + - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` - `--no-first-run` - `--no-default-browser-check` @@ -1573,20 +1573,15 @@ L'accesso osservatore a noVNC usa l'autenticazione VNC per impostazione predefin - `--no-zygote` - `--metrics-recording-only` - `--disable-extensions` (abilitato per impostazione predefinita) - - `--disable-3d-apis`, `--disable-software-rasterizer` e `--disable-gpu` sono - abilitati per impostazione predefinita e possono essere disabilitati con - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` se l'uso di WebGL/3D lo richiede. - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` riabilita le estensioni se il tuo flusso di lavoro - dipende da esse. - - `--renderer-process-limit=2` può essere modificato con - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; imposta `0` per usare il - limite di processi predefinito di Chromium. + - `--disable-3d-apis`, `--disable-software-rasterizer` e `--disable-gpu` sono abilitati per impostazione predefinita e possono essere disabilitati con `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` se l'uso di WebGL/3D lo richiede. + - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` riabilita le estensioni se il tuo flusso di lavoro ne dipende. + - `--renderer-process-limit=2` può essere modificato con `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; imposta `0` per usare il limite di processi predefinito di Chromium. - più `--no-sandbox` e `--disable-setuid-sandbox` quando `noSandbox` è abilitato. - - I valori predefiniti sono la baseline dell'immagine container; usa un'immagine browser personalizzata con un entrypoint personalizzato per modificare i valori predefiniti del container. + - I valori predefiniti sono la baseline dell'immagine container; usa un'immagine browser personalizzata con un entrypoint personalizzato per cambiare i valori predefiniti del container. -Il sandboxing del browser e `sandbox.docker.binds` sono disponibili solo con Docker. +Il sandboxing del browser e `sandbox.docker.binds` sono disponibili solo per Docker. Crea le immagini: @@ -1608,11 +1603,11 @@ scripts/sandbox-browser-setup.sh # immagine browser opzionale workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", model: "anthropic/claude-opus-4-6", // oppure { primary, fallbacks } - thinkingDefault: "high", // override del livello di thinking per agente - reasoningDefault: "on", // override della visibilità del ragionamento per agente - fastModeDefault: false, // override della modalità rapida per agente + thinkingDefault: "high", // override per agente del livello di thinking + reasoningDefault: "on", // override per agente della visibilità del reasoning + fastModeDefault: false, // override per agente della modalità veloce embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // sostituisce per chiave i params corrispondenti in defaults.models + params: { cacheRetention: "none" }, // sovrascrive per chiave i params del defaults.models corrispondente skills: ["docs-search"], // sostituisce agents.defaults.skills quando impostato identity: { name: "Samantha", @@ -1644,27 +1639,27 @@ scripts/sandbox-browser-setup.sh # immagine browser opzionale } ``` -- `id`: id agente stabile (obbligatorio). -- `default`: quando ne sono impostati più di uno, vince il primo (viene registrato un avviso). Se non ne è impostato nessuno, la prima voce della lista è quella predefinita. -- `model`: la forma stringa sostituisce solo `primary`; la forma oggetto `{ primary, fallbacks }` sostituisce entrambi (`[]` disabilita i fallback globali). I job cron che sostituiscono solo `primary` continuano a ereditare i fallback predefiniti, a meno che tu non imposti `fallbacks: []`. -- `params`: parametri stream per agente fusi sopra la voce di modello selezionata in `agents.defaults.models`. Usalo per override specifici dell'agente come `cacheRetention`, `temperature` o `maxTokens` senza duplicare l'intero catalogo modelli. -- `skills`: allowlist facoltativa di Skills per agente. Se omesso, l'agente eredita `agents.defaults.skills` quando impostato; una lista esplicita sostituisce i valori predefiniti invece di fonderli, e `[]` significa nessuna Skills. -- `thinkingDefault`: valore predefinito facoltativo del livello di thinking per agente (`off | minimal | low | medium | high | xhigh | adaptive`). Sostituisce `agents.defaults.thinkingDefault` per questo agente quando non è impostato alcun override per messaggio o per sessione. -- `reasoningDefault`: valore predefinito facoltativo della visibilità del ragionamento per agente (`on | off | stream`). Si applica quando non è impostato alcun override del ragionamento per messaggio o per sessione. -- `fastModeDefault`: valore predefinito facoltativo per agente per la modalità rapida (`true | false`). Si applica quando non è impostato alcun override della modalità rapida per messaggio o per sessione. -- `embeddedHarness`: override facoltativo del criterio harness di basso livello per agente. Usa `{ runtime: "codex", fallback: "none" }` per rendere un agente solo Codex mentre gli altri agenti mantengono il fallback PI predefinito. -- `runtime`: descrittore runtime facoltativo per agente. Usa `type: "acp"` con i valori predefiniti di `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) quando l'agente deve usare per impostazione predefinita sessioni harness ACP. -- `identity.avatar`: percorso relativo al workspace, URL `http(s)` o URI `data:`. +- `id`: ID agente stabile (obbligatorio). +- `default`: quando ne sono impostati più di uno, vince il primo (viene registrato un avviso). Se non ne è impostato nessuno, il valore predefinito è la prima voce dell'elenco. +- `model`: la forma stringa sovrascrive solo `primary`; la forma oggetto `{ primary, fallbacks }` sovrascrive entrambi (`[]` disabilita i fallback globali). I job Cron che sovrascrivono solo `primary` continuano a ereditare i fallback predefiniti a meno che tu non imposti `fallbacks: []`. +- `params`: parametri di stream per agente uniti sopra la voce del modello selezionato in `agents.defaults.models`. Usalo per override specifici dell'agente come `cacheRetention`, `temperature` o `maxTokens` senza duplicare l'intero catalogo modelli. +- `skills`: allowlist opzionale di Skills per agente. Se omessa, l'agente eredita `agents.defaults.skills` quando è impostato; un elenco esplicito sostituisce i valori predefiniti invece di unirsi a essi, e `[]` significa nessuna Skills. +- `thinkingDefault`: livello thinking predefinito opzionale per agente (`off | minimal | low | medium | high | xhigh | adaptive`). Sovrascrive `agents.defaults.thinkingDefault` per questo agente quando non è impostato alcun override per messaggio o sessione. +- `reasoningDefault`: visibilità predefinita opzionale del reasoning per agente (`on | off | stream`). Si applica quando non è impostato alcun override del reasoning per messaggio o sessione. +- `fastModeDefault`: valore predefinito opzionale per agente per la modalità veloce (`true | false`). Si applica quando non è impostato alcun override della modalità veloce per messaggio o sessione. +- `embeddedHarness`: override opzionale per agente del criterio dell'harness di basso livello. Usa `{ runtime: "codex", fallback: "none" }` per rendere un agente solo-Codex mentre gli altri agenti mantengono il fallback predefinito a Pi. +- `runtime`: descrittore runtime opzionale per agente. Usa `type: "acp"` con i valori predefiniti di `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) quando l'agente deve usare per impostazione predefinita sessioni harness ACP. +- `identity.avatar`: percorso relativo alla workspace, URL `http(s)` o URI `data:`. - `identity` deriva i valori predefiniti: `ackReaction` da `emoji`, `mentionPatterns` da `name`/`emoji`. -- `subagents.allowAgents`: allowlist di id agente per `sessions_spawn` (`["*"]` = qualsiasi; predefinito: solo lo stesso agente). -- Protezione di ereditarietà sandbox: se la sessione richiedente è in sandbox, `sessions_spawn` rifiuta le destinazioni che verrebbero eseguite senza sandbox. +- `subagents.allowAgents`: allowlist di ID agente per `sessions_spawn` (`["*"]` = qualsiasi; predefinito: solo lo stesso agente). +- Protezione ereditarietà sandbox: se la sessione richiedente è sandboxed, `sessions_spawn` rifiuta i target che verrebbero eseguiti senza sandbox. - `subagents.requireAgentId`: quando è true, blocca le chiamate `sessions_spawn` che omettono `agentId` (forza la selezione esplicita del profilo; predefinito: false). --- ## Routing multi-agente -Esegui più agenti isolati all'interno di un unico Gateway. Vedi [Multi-Agent](/it/concepts/multi-agent). +Esegui più agenti isolati all'interno di un Gateway. Vedi [Multi-Agent](/it/concepts/multi-agent). ```json5 { @@ -1681,14 +1676,14 @@ Esegui più agenti isolati all'interno di un unico Gateway. Vedi [Multi-Agent](/ } ``` -### Campi di corrispondenza del binding +### Campi di corrispondenza dei binding -- `type` (facoltativo): `route` per il routing normale (se manca, il tipo predefinito è route), `acp` per binding persistenti di conversazioni ACP. +- `type` (opzionale): `route` per il routing normale (se manca, il tipo predefinito è route), `acp` per i binding persistenti delle conversazioni ACP. - `match.channel` (obbligatorio) -- `match.accountId` (facoltativo; `*` = qualsiasi account; omesso = account predefinito) -- `match.peer` (facoltativo; `{ kind: direct|group|channel, id }`) -- `match.guildId` / `match.teamId` (facoltativo; specifico del canale) -- `acp` (facoltativo; solo per `type: "acp"`): `{ mode, label, cwd, backend }` +- `match.accountId` (opzionale; `*` = qualsiasi account; omesso = account predefinito) +- `match.peer` (opzionale; `{ kind: direct|group|channel, id }`) +- `match.guildId` / `match.teamId` (opzionale; specifico del canale) +- `acp` (opzionale; solo per voci `type: "acp"`): `{ mode, label, cwd, backend }` **Ordine di corrispondenza deterministico:** @@ -1696,16 +1691,16 @@ Esegui più agenti isolati all'interno di un unico Gateway. Vedi [Multi-Agent](/ 2. `match.guildId` 3. `match.teamId` 4. `match.accountId` (esatto, senza peer/guild/team) -5. `match.accountId: "*"` (esteso all'intero canale) +5. `match.accountId: "*"` (a livello di canale) 6. Agente predefinito -All'interno di ciascun livello, vince la prima voce `bindings` corrispondente. +All'interno di ogni livello, vince la prima voce `bindings` corrispondente. -Per le voci `type: "acp"`, OpenClaw risolve in base all'identità esatta della conversazione (`match.channel` + account + `match.peer.id`) e non usa l'ordine per livelli del route binding descritto sopra. +Per le voci `type: "acp"`, OpenClaw risolve in base all'identità esatta della conversazione (`match.channel` + account + `match.peer.id`) e non usa l'ordine a livelli dei binding di route sopra. ### Profili di accesso per agente - + ```json5 { @@ -1824,19 +1819,19 @@ Vedi [Multi-Agent Sandbox & Tools](/it/tools/multi-agent-sandbox-tools) per i de }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // salta il fork del thread padre sopra questo conteggio di token (0 disabilita) + parentForkMaxTokens: 100000, // salta il fork del thread padre sopra questo numero di token (0 disabilita) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // durata oppure false - maxDiskBytes: "500mb", // budget rigido facoltativo - highWaterBytes: "400mb", // obiettivo di pulizia facoltativo + resetArchiveRetention: "30d", // durata o false + maxDiskBytes: "500mb", // budget rigido opzionale + highWaterBytes: "400mb", // target opzionale per la pulizia }, threadBindings: { enabled: true, - idleHours: 24, // autofocus off predefinito per inattività in ore (`0` disabilita) + idleHours: 24, // auto-unfocus predefinito per inattività in ore (`0` disabilita) maxAgeHours: 0, // età massima rigida predefinita in ore (`0` disabilita) }, mainKey: "main", // legacy (il runtime usa sempre "main") @@ -1851,35 +1846,35 @@ Vedi [Multi-Agent Sandbox & Tools](/it/tools/multi-agent-sandbox-tools) per i de -- **`scope`**: strategia di raggruppamento delle sessioni di base per i contesti di chat di gruppo. - - `per-sender` (predefinito): ogni mittente ottiene una sessione isolata all'interno di un contesto di canale. +- **`scope`**: strategia base di raggruppamento delle sessioni per i contesti di chat di gruppo. + - `per-sender` (predefinito): ogni mittente ottiene una sessione isolata all'interno del contesto del canale. - `global`: tutti i partecipanti in un contesto di canale condividono una singola sessione (usalo solo quando è previsto un contesto condiviso). -- **`dmScope`**: come vengono raggruppati i messaggi diretti. - - `main`: tutti i messaggi diretti condividono la sessione principale. - - `per-peer`: isola per id mittente tra i canali. +- **`dmScope`**: come vengono raggruppati i DM. + - `main`: tutti i DM condividono la sessione principale. + - `per-peer`: isola per ID mittente tra i canali. - `per-channel-peer`: isola per canale + mittente (consigliato per inbox multiutente). - `per-account-channel-peer`: isola per account + canale + mittente (consigliato per multi-account). -- **`identityLinks`**: mappa gli id canonici ai peer con prefisso provider per la condivisione delle sessioni tra canali. -- **`reset`**: criterio di reset principale. `daily` esegue il reset a `atHour` nell'ora locale; `idle` esegue il reset dopo `idleMinutes`. Quando sono configurati entrambi, prevale quello che scade per primo. -- **`resetByType`**: override per tipo (`direct`, `group`, `thread`). Il vecchio `dm` è accettato come alias di `direct`. -- **`parentForkMaxTokens`**: valore massimo di `totalTokens` della sessione padre consentito quando si crea una sessione thread derivata (predefinito `100000`). - - Se `totalTokens` del padre è superiore a questo valore, OpenClaw avvia una nuova sessione thread invece di ereditare la cronologia della trascrizione del padre. - - Imposta `0` per disabilitare questa protezione e consentire sempre il fork dal padre. +- **`identityLinks`**: mappa gli ID canonici ai peer con prefisso provider per la condivisione delle sessioni tra canali. +- **`reset`**: criterio di reset principale. `daily` resetta all'ora locale `atHour`; `idle` resetta dopo `idleMinutes`. Quando sono configurati entrambi, prevale quello che scade per primo. +- **`resetByType`**: override per tipo (`direct`, `group`, `thread`). Il legacy `dm` è accettato come alias di `direct`. +- **`parentForkMaxTokens`**: `totalTokens` massimo consentito per la sessione padre quando si crea una sessione thread derivata (predefinito `100000`). + - Se il `totalTokens` del padre supera questo valore, OpenClaw avvia una nuova sessione thread invece di ereditare la cronologia del transcript padre. + - Imposta `0` per disabilitare questa protezione e consentire sempre il fork del padre. - **`mainKey`**: campo legacy. Il runtime usa sempre `"main"` per il bucket principale delle chat dirette. -- **`agentToAgent.maxPingPongTurns`**: numero massimo di turni di risposta reciproca tra agenti durante gli scambi agente-agente (intero, intervallo: `0`–`5`). `0` disabilita la catena ping-pong. -- **`sendPolicy`**: corrisponde in base a `channel`, `chatType` (`direct|group|channel`, con alias legacy `dm`), `keyPrefix` o `rawKeyPrefix`. La prima regola di rifiuto corrispondente prevale. -- **`maintenance`**: controlli di pulizia e conservazione dell'archivio sessioni. +- **`agentToAgent.maxPingPongTurns`**: numero massimo di turni di risposta reciproca tra agenti durante gli scambi agent-to-agent (intero, intervallo: `0`–`5`). `0` disabilita la catena ping-pong. +- **`sendPolicy`**: corrisponde in base a `channel`, `chatType` (`direct|group|channel`, con alias legacy `dm`), `keyPrefix` o `rawKeyPrefix`. Il primo deny prevale. +- **`maintenance`**: controlli di pulizia + retention dello store delle sessioni. - `mode`: `warn` emette solo avvisi; `enforce` applica la pulizia. - - `pruneAfter`: soglia di età per le voci obsolete (predefinito `30d`). + - `pruneAfter`: soglia temporale per le voci obsolete (predefinito `30d`). - `maxEntries`: numero massimo di voci in `sessions.json` (predefinito `500`). - `rotateBytes`: ruota `sessions.json` quando supera questa dimensione (predefinito `10mb`). - - `resetArchiveRetention`: conservazione per gli archivi di trascrizione `*.reset.`. Per impostazione predefinita usa `pruneAfter`; imposta `false` per disabilitarla. - - `maxDiskBytes`: budget disco facoltativo per la directory delle sessioni. In modalità `warn` registra avvisi; in modalità `enforce` rimuove prima gli artefatti/sessioni più vecchi. - - `highWaterBytes`: obiettivo facoltativo dopo la pulizia del budget. Per impostazione predefinita è l'`80%` di `maxDiskBytes`. -- **`threadBindings`**: valori predefiniti globali per le funzionalità di sessione legate ai thread. - - `enabled`: interruttore predefinito principale (i provider possono fare override; Discord usa `channels.discord.threadBindings.enabled`) - - `idleHours`: autofocus off predefinito per inattività in ore (`0` disabilita; i provider possono fare override) - - `maxAgeHours`: età massima rigida predefinita in ore (`0` disabilita; i provider possono fare override) + - `resetArchiveRetention`: retention per gli archivi di transcript `*.reset.`. Il valore predefinito è `pruneAfter`; imposta `false` per disabilitare. + - `maxDiskBytes`: budget disco opzionale della directory delle sessioni. In modalità `warn` registra avvisi; in modalità `enforce` rimuove prima gli artefatti/sessioni più vecchi. + - `highWaterBytes`: target opzionale dopo la pulizia del budget. Il valore predefinito è `80%` di `maxDiskBytes`. +- **`threadBindings`**: valori predefiniti globali per le funzionalità di sessione associate ai thread. + - `enabled`: interruttore predefinito principale (i provider possono sovrascriverlo; Discord usa `channels.discord.threadBindings.enabled`) + - `idleHours`: auto-unfocus predefinito per inattività in ore (`0` disabilita; i provider possono sovrascrivere) + - `maxAgeHours`: età massima rigida predefinita in ore (`0` disabilita; i provider possono sovrascrivere) @@ -1915,21 +1910,21 @@ Vedi [Multi-Agent Sandbox & Tools](/it/tools/multi-agent-sandbox-tools) per i de } ``` -### Prefisso della risposta +### Prefisso di risposta Override per canale/account: `channels..responsePrefix`, `channels..accounts..responsePrefix`. Risoluzione (vince il più specifico): account → canale → globale. `""` disabilita e interrompe la cascata. `"auto"` deriva `[{identity.name}]`. -**Variabili del template:** +**Variabili di template:** -| Variabile | Descrizione | Esempio | -| ----------------- | ---------------------------- | --------------------------- | -| `{model}` | Nome breve del modello | `claude-opus-4-6` | +| Variabile | Descrizione | Esempio | +| ----------------- | ------------------------- | --------------------------- | +| `{model}` | Nome breve del modello | `claude-opus-4-6` | | `{modelFull}` | Identificatore completo del modello | `anthropic/claude-opus-4-6` | -| `{provider}` | Nome del provider | `anthropic` | -| `{thinkingLevel}` | Livello di thinking corrente | `high`, `low`, `off` | -| `{identity.name}` | Nome dell'identità agente | (uguale a `"auto"`) | +| `{provider}` | Nome del provider | `anthropic` | +| `{thinkingLevel}` | Livello thinking corrente | `high`, `low`, `off` | +| `{identity.name}` | Nome dell'identità agente | (uguale a `"auto"`) | Le variabili non distinguono tra maiuscole e minuscole. `{think}` è un alias di `{thinkingLevel}`. @@ -1937,8 +1932,8 @@ Le variabili non distinguono tra maiuscole e minuscole. `{think}` è un alias di - Per impostazione predefinita usa `identity.emoji` dell'agente attivo, altrimenti `"👀"`. Imposta `""` per disabilitare. - Override per canale: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Ordine di risoluzione: account → canale → `messages.ackReaction` → fallback identity. -- Ambito: `group-mentions` (predefinito), `group-all`, `direct`, `all`. +- Ordine di risoluzione: account → canale → `messages.ackReaction` → fallback dell'identità. +- Scope: `group-mentions` (predefinito), `group-all`, `direct`, `all`. - `removeAckAfterReply`: rimuove la conferma dopo la risposta su Slack, Discord e Telegram. - `messages.statusReactions.enabled`: abilita le reazioni di stato del ciclo di vita su Slack, Discord e Telegram. Su Slack e Discord, se non impostato mantiene abilitate le reazioni di stato quando le reazioni di conferma sono attive. @@ -1946,9 +1941,9 @@ Le variabili non distinguono tra maiuscole e minuscole. `{think}` è un alias di ### Debounce in ingresso -Raggruppa rapidi messaggi di solo testo dello stesso mittente in un singolo turno dell'agente. I media/allegati scaricano immediatamente. I comandi di controllo ignorano il debounce. +Raggruppa i messaggi testuali rapidi dello stesso mittente in un singolo turno dell'agente. I media/gli allegati vengono scaricati subito. I comandi di controllo bypassano il debounce. -### TTS (sintesi vocale) +### TTS (text-to-speech) ```json5 { @@ -1989,11 +1984,11 @@ Raggruppa rapidi messaggi di solo testo dello stesso mittente in un singolo turn } ``` -- `auto` controlla la modalità predefinita di auto-TTS: `off`, `always`, `inbound` o `tagged`. `/tts on|off` può sostituire le preferenze locali e `/tts status` mostra lo stato effettivo. -- `summaryModel` sostituisce `agents.defaults.model.primary` per il riepilogo automatico. -- `modelOverrides` è abilitato per impostazione predefinita; `modelOverrides.allowProvider` è `false` per impostazione predefinita (attivazione esplicita). +- `auto` controlla la modalità auto-TTS predefinita: `off`, `always`, `inbound` oppure `tagged`. `/tts on|off` può sovrascrivere le preferenze locali e `/tts status` mostra lo stato effettivo. +- `summaryModel` sovrascrive `agents.defaults.model.primary` per il riepilogo automatico. +- `modelOverrides` è abilitato per impostazione predefinita; `modelOverrides.allowProvider` ha come predefinito `false` (opt-in). - Le chiavi API usano come fallback `ELEVENLABS_API_KEY`/`XI_API_KEY` e `OPENAI_API_KEY`. -- `openai.baseUrl` sostituisce l'endpoint TTS di OpenAI. L'ordine di risoluzione è configurazione, poi `OPENAI_TTS_BASE_URL`, poi `https://api.openai.com/v1`. +- `openai.baseUrl` sovrascrive l'endpoint TTS di OpenAI. L'ordine di risoluzione è config, poi `OPENAI_TTS_BASE_URL`, poi `https://api.openai.com/v1`. - Quando `openai.baseUrl` punta a un endpoint non OpenAI, OpenClaw lo tratta come un server TTS compatibile con OpenAI e allenta la convalida di modello/voce. --- @@ -2025,12 +2020,12 @@ Valori predefiniti per la modalità Talk (macOS/iOS/Android). ``` - `talk.provider` deve corrispondere a una chiave in `talk.providers` quando sono configurati più provider Talk. -- Le vecchie chiavi flat di Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) sono solo per compatibilità e vengono migrate automaticamente in `talk.providers.`. +- Le chiavi Talk flat legacy (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) sono solo per compatibilità e vengono migrate automaticamente in `talk.providers.`. - Gli ID voce usano come fallback `ELEVENLABS_VOICE_ID` o `SAG_VOICE_ID`. - `providers.*.apiKey` accetta stringhe in chiaro o oggetti SecretRef. - Il fallback `ELEVENLABS_API_KEY` si applica solo quando non è configurata alcuna chiave API Talk. -- `providers.*.voiceAliases` consente alle direttive Talk di usare nomi intuitivi. -- `silenceTimeoutMs` controlla per quanto tempo la modalità Talk attende dopo il silenzio dell'utente prima di inviare la trascrizione. Se non impostato, mantiene la finestra di pausa predefinita della piattaforma (`700 ms su macOS e Android, 900 ms su iOS`). +- `providers.*.voiceAliases` consente alle direttive Talk di usare nomi amichevoli. +- `silenceTimeoutMs` controlla quanto tempo la modalità Talk attende dopo il silenzio dell'utente prima di inviare la trascrizione. Se non impostato, mantiene la finestra di pausa predefinita della piattaforma (`700 ms su macOS e Android, 900 ms su iOS`). --- @@ -2038,9 +2033,9 @@ Valori predefiniti per la modalità Talk (macOS/iOS/Android). ### Profili degli strumenti -`tools.profile` imposta una allowlist di base prima di `tools.allow`/`tools.deny`: +`tools.profile` imposta un'allowlist di base prima di `tools.allow`/`tools.deny`: -L'onboarding locale imposta per impostazione predefinita le nuove configurazioni locali su `tools.profile: "coding"` quando non è impostato (i profili espliciti esistenti vengono mantenuti). +L'onboarding locale imposta per le nuove configurazioni locali `tools.profile: "coding"` quando non è definito (i profili espliciti esistenti vengono preservati). | Profilo | Include | | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | @@ -2051,24 +2046,24 @@ L'onboarding locale imposta per impostazione predefinita le nuove configurazioni ### Gruppi di strumenti -| Gruppo | Strumenti | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` è accettato come alias di `exec`) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| Gruppo | Strumenti | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash` è accettato come alias di `exec`) | +| `group:fs` | `read`, `write`, `edit`, `apply_patch` | | `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | -| `group:memory` | `memory_search`, `memory_get` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation` | `cron`, `gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Tutti gli strumenti integrati (esclude i plugin provider) | +| `group:memory` | `memory_search`, `memory_get` | +| `group:web` | `web_search`, `x_search`, `web_fetch` | +| `group:ui` | `browser`, `canvas` | +| `group:automation` | `cron`, `gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | +| `group:openclaw` | Tutti gli strumenti integrati (esclude i plugin provider) | ### `tools.allow` / `tools.deny` -Criterio globale di autorizzazione/rifiuto degli strumenti (il rifiuto prevale). Non distingue tra maiuscole e minuscole, supporta wildcard `*`. Applicato anche quando la sandbox Docker è disattivata. +Criterio globale di allow/deny degli strumenti (deny prevale). Non distingue tra maiuscole e minuscole, supporta i caratteri jolly `*`. Applicato anche quando il sandbox Docker è disattivato. ```json5 { @@ -2078,7 +2073,7 @@ Criterio globale di autorizzazione/rifiuto degli strumenti (il rifiuto prevale). ### `tools.byProvider` -Limita ulteriormente gli strumenti per provider o modelli specifici. Ordine: profilo di base → profilo provider → allow/deny. +Limita ulteriormente gli strumenti per provider o modelli specifici. Ordine: profilo base → profilo provider → allow/deny. ```json5 { @@ -2094,7 +2089,7 @@ Limita ulteriormente gli strumenti per provider o modelli specifici. Ordine: pro ### `tools.elevated` -Controlla l'accesso `exec` elevato fuori dalla sandbox: +Controlla l'accesso exec elevato fuori dal sandbox: ```json5 { @@ -2110,9 +2105,9 @@ Controlla l'accesso `exec` elevato fuori dalla sandbox: } ``` -- L'override per agente (`agents.list[].tools.elevated`) può solo limitare ulteriormente. +- L'override per agente (`agents.list[].tools.elevated`) può solo restringere ulteriormente. - `/elevated on|off|ask|full` memorizza lo stato per sessione; le direttive inline si applicano a un singolo messaggio. -- `exec` elevato bypassa la sandbox e usa il percorso di escape configurato (`gateway` per impostazione predefinita, oppure `node` quando la destinazione exec è `node`). +- `exec` elevato bypassa il sandbox e usa il percorso di escape configurato (`gateway` per impostazione predefinita, oppure `node` quando il target exec è `node`). ### `tools.exec` @@ -2136,8 +2131,8 @@ Controlla l'accesso `exec` elevato fuori dalla sandbox: ### `tools.loopDetection` -I controlli di sicurezza per i loop degli strumenti sono **disabilitati per impostazione predefinita**. Imposta `enabled: true` per attivare il rilevamento. -Le impostazioni possono essere definite globalmente in `tools.loopDetection` e sostituite per agente in `agents.list[].tools.loopDetection`. +I controlli di sicurezza sui loop degli strumenti sono **disabilitati per impostazione predefinita**. Imposta `enabled: true` per attivare il rilevamento. +Le impostazioni possono essere definite globalmente in `tools.loopDetection` e sovrascritte per agente in `agents.list[].tools.loopDetection`. ```json5 { @@ -2159,12 +2154,12 @@ Le impostazioni possono essere definite globalmente in `tools.loopDetection` e s ``` - `historySize`: cronologia massima delle chiamate agli strumenti conservata per l'analisi dei loop. -- `warningThreshold`: soglia di pattern ripetuti senza avanzamento per gli avvisi. -- `criticalThreshold`: soglia ripetuta più alta per bloccare i loop critici. -- `globalCircuitBreakerThreshold`: soglia di arresto rigido per qualsiasi esecuzione senza avanzamento. -- `detectors.genericRepeat`: avvisa in caso di chiamate ripetute con stesso strumento/stessi argomenti. -- `detectors.knownPollNoProgress`: avvisa/blocca gli strumenti di polling noti (`process.poll`, `command_status`, ecc.) senza avanzamento. -- `detectors.pingPong`: avvisa/blocca pattern alternati a coppie senza avanzamento. +- `warningThreshold`: soglia del pattern ripetuto senza progresso per gli avvisi. +- `criticalThreshold`: soglia di ripetizione più alta per bloccare i loop critici. +- `globalCircuitBreakerThreshold`: soglia di arresto rigido per qualsiasi esecuzione senza progresso. +- `detectors.genericRepeat`: avvisa su chiamate ripetute allo stesso strumento/con gli stessi argomenti. +- `detectors.knownPollNoProgress`: avvisa/blocca sui noti strumenti di polling (`process.poll`, `command_status`, ecc.). +- `detectors.pingPong`: avvisa/blocca sui pattern a coppie alternate senza progresso. - Se `warningThreshold >= criticalThreshold` o `criticalThreshold >= globalCircuitBreakerThreshold`, la convalida fallisce. ### `tools.web` @@ -2182,7 +2177,7 @@ Le impostazioni possono essere definite globalmente in `tools.loopDetection` e s }, fetch: { enabled: true, - provider: "firecrawl", // facoltativo; ometti per il rilevamento automatico + provider: "firecrawl", // opzionale; ometti per auto-rilevamento maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2207,7 +2202,7 @@ Configura la comprensione dei media in ingresso (immagine/audio/video): media: { concurrency: 2, asyncCompletion: { - directSend: false, // attivazione esplicita: invia musica/video asincroni completati direttamente al canale + directSend: false, // opt-in: invia direttamente al canale i task music/video asincroni completati }, audio: { enabled: true, @@ -2231,32 +2226,32 @@ Configura la comprensione dei media in ingresso (immagine/audio/video): } ``` - + **Voce provider** (`type: "provider"` o omesso): -- `provider`: id del provider API (`openai`, `anthropic`, `google`/`gemini`, `groq`, ecc.) +- `provider`: id provider API (`openai`, `anthropic`, `google`/`gemini`, `groq`, ecc.) - `model`: override dell'id modello - `profile` / `preferredProfile`: selezione del profilo `auth-profiles.json` **Voce CLI** (`type: "cli"`): -- `command`: eseguibile da avviare -- `args`: argomenti templati (supporta `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, ecc.) +- `command`: eseguibile da lanciare +- `args`: argomenti con template (supporta `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, ecc.) **Campi comuni:** -- `capabilities`: elenco facoltativo (`image`, `audio`, `video`). Valori predefiniti: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. +- `capabilities`: elenco opzionale (`image`, `audio`, `video`). Predefiniti: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. - `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: override per voce. -- In caso di errore, passa alla voce successiva. +- In caso di errore si passa alla voce successiva. -L'autenticazione del provider segue l'ordine standard: `auth-profiles.json` → variabili d'ambiente → `models.providers.*.apiKey`. +L'autenticazione del provider segue l'ordine standard: `auth-profiles.json` → variabili env → `models.providers.*.apiKey`. **Campi di completamento asincrono:** -- `asyncCompletion.directSend`: quando `true`, i task asincroni completati `music_generate` - e `video_generate` provano prima la consegna diretta al canale. Valore predefinito: `false` - (vecchio percorso di attivazione della sessione richiedente/consegna modello). +- `asyncCompletion.directSend`: quando `true`, i task `music_generate` + e `video_generate` asincroni completati provano prima la consegna diretta sul canale. Predefinito: `false` + (percorso legacy requester-session wake/model-delivery). @@ -2275,9 +2270,9 @@ L'autenticazione del provider segue l'ordine standard: `auth-profiles.json` → ### `tools.sessions` -Controlla quali sessioni possono essere usate come destinazione dagli strumenti di sessione (`sessions_list`, `sessions_history`, `sessions_send`). +Controlla quali sessioni possono essere usate come target dagli strumenti di sessione (`sessions_list`, `sessions_history`, `sessions_send`). -Predefinito: `tree` (sessione corrente + sessioni generate da essa, come i subagent). +Predefinito: `tree` (sessione corrente + sessioni generate da essa, come i subagenti). ```json5 { @@ -2293,10 +2288,10 @@ Predefinito: `tree` (sessione corrente + sessioni generate da essa, come i subag Note: - `self`: solo la chiave della sessione corrente. -- `tree`: sessione corrente + sessioni generate dalla sessione corrente (subagent). -- `agent`: qualsiasi sessione appartenente all'id agente corrente (può includere altri utenti se esegui sessioni per mittente sotto lo stesso id agente). -- `all`: qualsiasi sessione. Il targeting tra agenti richiede comunque `tools.agentToAgent`. -- Limite sandbox: quando la sessione corrente è in sandbox e `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, la visibilità viene forzata a `tree` anche se `tools.sessions.visibility="all"`. +- `tree`: sessione corrente + sessioni generate dalla sessione corrente (subagenti). +- `agent`: qualsiasi sessione appartenente all'ID agente corrente (può includere altri utenti se esegui sessioni per-mittente sotto lo stesso ID agente). +- `all`: qualsiasi sessione. Il targeting cross-agent richiede comunque `tools.agentToAgent`. +- Limitazione sandbox: quando la sessione corrente è sandboxed e `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, la visibilità viene forzata a `tree` anche se `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` @@ -2307,11 +2302,11 @@ Controlla il supporto agli allegati inline per `sessions_spawn`. tools: { sessions_spawn: { attachments: { - enabled: false, // attivazione esplicita: imposta true per consentire allegati file inline + enabled: false, // opt-in: imposta true per consentire allegati file inline maxTotalBytes: 5242880, // 5 MB totali su tutti i file maxFiles: 50, maxFileBytes: 1048576, // 1 MB per file - retainOnSessionKeep: false, // conserva gli allegati quando cleanup="keep" + retainOnSessionKeep: false, // mantiene gli allegati quando cleanup="keep" }, }, }, @@ -2321,21 +2316,21 @@ Controlla il supporto agli allegati inline per `sessions_spawn`. Note: - Gli allegati sono supportati solo per `runtime: "subagent"`. Il runtime ACP li rifiuta. -- I file vengono materializzati nel workspace figlio in `.openclaw/attachments//` con un `.manifest.json`. -- Il contenuto degli allegati viene automaticamente oscurato nella persistenza della trascrizione. -- Gli input Base64 vengono convalidati con controlli rigorosi su alfabeto/padding e una protezione sulla dimensione prima della decodifica. +- I file vengono materializzati nella workspace figlia in `.openclaw/attachments//` con un `.manifest.json`. +- Il contenuto degli allegati viene automaticamente redatto dalla persistenza del transcript. +- Gli input base64 vengono convalidati con controlli rigorosi su alfabeto/padding e una protezione sulla dimensione prima della decodifica. - I permessi dei file sono `0700` per le directory e `0600` per i file. - La pulizia segue il criterio `cleanup`: `delete` rimuove sempre gli allegati; `keep` li conserva solo quando `retainOnSessionKeep: true`. ### `tools.experimental` -Flag sperimentali degli strumenti integrati. Disattivati per impostazione predefinita, salvo quando si applica una regola di auto-attivazione strict-agentic GPT-5. +Flag sperimentali per gli strumenti integrati. Disattivati per impostazione predefinita, salvo quando si applica una regola di auto-abilitazione strict-agentic GPT-5. ```json5 { tools: { experimental: { - planTool: true, // abilita `update_plan` sperimentale + planTool: true, // abilita l'update_plan sperimentale }, }, } @@ -2343,9 +2338,9 @@ Flag sperimentali degli strumenti integrati. Disattivati per impostazione predef Note: -- `planTool`: abilita lo strumento strutturato `update_plan` per il tracciamento di lavori non banali in più passaggi. -- Predefinito: `false` a meno che `agents.defaults.embeddedPi.executionContract` (o un override per agente) non sia impostato su `"strict-agentic"` per un'esecuzione OpenAI o OpenAI Codex della famiglia GPT-5. Imposta `true` per forzare l'attivazione dello strumento fuori da tale ambito, oppure `false` per mantenerlo disattivato anche per esecuzioni strict-agentic GPT-5. -- Quando abilitato, il prompt di sistema aggiunge anche linee guida d'uso così che il modello lo usi solo per lavori sostanziali e mantenga al massimo un solo passaggio `in_progress`. +- `planTool`: abilita lo strumento strutturato `update_plan` per il tracciamento di lavori multi-step non banali. +- Predefinito: `false` a meno che `agents.defaults.embeddedPi.executionContract` (o un override per agente) non sia impostato su `"strict-agentic"` per un'esecuzione OpenAI o OpenAI Codex della famiglia GPT-5. Imposta `true` per forzare l'attivazione dello strumento fuori da quel contesto, oppure `false` per mantenerlo disattivato anche per le esecuzioni strict-agentic GPT-5. +- Quando è abilitato, il prompt di sistema aggiunge anche linee guida d'uso così che il modello lo usi solo per lavori sostanziali e mantenga al massimo un passo `in_progress`. ### `agents.defaults.subagents` @@ -2365,16 +2360,16 @@ Note: } ``` -- `model`: modello predefinito per i subagent generati. Se omesso, i subagent ereditano il modello del chiamante. -- `allowAgents`: allowlist predefinita degli id agente di destinazione per `sessions_spawn` quando l'agente richiedente non imposta il proprio `subagents.allowAgents` (`["*"]` = qualsiasi; predefinito: solo lo stesso agente). +- `model`: modello predefinito per i subagenti generati. Se omesso, i subagenti ereditano il modello del chiamante. +- `allowAgents`: allowlist predefinita degli ID agente target per `sessions_spawn` quando l'agente richiedente non imposta il proprio `subagents.allowAgents` (`["*"]` = qualsiasi; predefinito: solo lo stesso agente). - `runTimeoutSeconds`: timeout predefinito (secondi) per `sessions_spawn` quando la chiamata allo strumento omette `runTimeoutSeconds`. `0` significa nessun timeout. -- Criterio strumenti per subagent: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. +- Criterio degli strumenti per subagente: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- -## Provider personalizzati e URL di base +## Provider personalizzati e URL base -OpenClaw usa il catalogo modelli integrato. Aggiungi provider personalizzati tramite `models.providers` nella configurazione o `~/.openclaw/agents//agent/models.json`. +OpenClaw usa il catalogo di modelli integrato. Aggiungi provider personalizzati tramite `models.providers` nella configurazione o `~/.openclaw/agents//agent/models.json`. ```json5 { @@ -2404,47 +2399,47 @@ OpenClaw usa il catalogo modelli integrato. Aggiungi provider personalizzati tra ``` - Usa `authHeader: true` + `headers` per esigenze di autenticazione personalizzate. -- Sostituisci la radice di configurazione dell'agente con `OPENCLAW_AGENT_DIR` (o `PI_CODING_AGENT_DIR`, alias legacy della variabile d'ambiente). -- Precedenza di unione per id provider corrispondenti: - - I valori `baseUrl` non vuoti di `models.json` dell'agente prevalgono. - - I valori `apiKey` non vuoti dell'agente prevalgono solo quando quel provider non è gestito da SecretRef nel contesto attuale di configurazione/profilo auth. - - I valori `apiKey` del provider gestiti da SecretRef vengono aggiornati dai marcatori sorgente (`ENV_VAR_NAME` per riferimenti env, `secretref-managed` per riferimenti file/exec) invece di mantenere i segreti risolti. - - I valori header del provider gestiti da SecretRef vengono aggiornati dai marcatori sorgente (`secretref-env:ENV_VAR_NAME` per riferimenti env, `secretref-managed` per riferimenti file/exec). +- Sovrascrivi la radice di configurazione dell'agente con `OPENCLAW_AGENT_DIR` (o `PI_CODING_AGENT_DIR`, alias legacy della variabile d'ambiente). +- Precedenza di unione per ID provider corrispondenti: + - I valori `baseUrl` non vuoti del `models.json` dell'agente hanno la precedenza. + - I valori `apiKey` non vuoti dell'agente hanno la precedenza solo quando quel provider non è gestito da SecretRef nel contesto attuale di config/profilo auth. + - I valori `apiKey` del provider gestiti da SecretRef vengono aggiornati dai marker di origine (`ENV_VAR_NAME` per i riferimenti env, `secretref-managed` per i riferimenti file/exec) invece di persistere i segreti risolti. + - I valori header del provider gestiti da SecretRef vengono aggiornati dai marker di origine (`secretref-env:ENV_VAR_NAME` per i riferimenti env, `secretref-managed` per i riferimenti file/exec). - `apiKey`/`baseUrl` dell'agente vuoti o mancanti usano come fallback `models.providers` nella configurazione. - - `contextWindow`/`maxTokens` del modello corrispondente usano il valore più alto tra configurazione esplicita e valori impliciti del catalogo. - - `contextTokens` del modello corrispondente conserva un limite runtime esplicito quando presente; usalo per limitare il contesto effettivo senza modificare i metadati nativi del modello. + - `contextWindow`/`maxTokens` del modello corrispondente usano il valore più alto tra config esplicita e valori impliciti del catalogo. + - `contextTokens` del modello corrispondente preserva un limite runtime esplicito quando presente; usalo per limitare il contesto effettivo senza cambiare i metadati nativi del modello. - Usa `models.mode: "replace"` quando vuoi che la configurazione riscriva completamente `models.json`. - - La persistenza dei marcatori è autorevole rispetto alla sorgente: i marcatori vengono scritti dall'istantanea di configurazione sorgente attiva (prima della risoluzione), non dai valori segreti runtime risolti. + - La persistenza dei marker è autorevole rispetto alla sorgente: i marker vengono scritti dallo snapshot della configurazione sorgente attiva (pre-risoluzione), non dai valori segreti runtime risolti. ### Dettagli dei campi del provider - `models.mode`: comportamento del catalogo provider (`merge` o `replace`). -- `models.providers`: mappa dei provider personalizzati indicizzata per id provider. -- `models.providers.*.api`: adattatore di richiesta (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai`, ecc.). +- `models.providers`: mappa dei provider personalizzati con chiave per ID provider. +- `models.providers.*.api`: adattatore di richiesta (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai`, ecc). - `models.providers.*.apiKey`: credenziale del provider (preferisci SecretRef/sostituzione env). - `models.providers.*.auth`: strategia di autenticazione (`api-key`, `token`, `oauth`, `aws-sdk`). -- `models.providers.*.injectNumCtxForOpenAICompat`: per Ollama + `openai-completions`, inserisce `options.num_ctx` nelle richieste (predefinito: `true`). -- `models.providers.*.authHeader`: forza il trasporto della credenziale nell'header `Authorization` quando richiesto. -- `models.providers.*.baseUrl`: URL di base dell'API upstream. -- `models.providers.*.headers`: header statici aggiuntivi per il routing proxy/tenant. -- `models.providers.*.request`: override di trasporto per le richieste HTTP del model provider. - - `request.headers`: header aggiuntivi (fusi con i valori predefiniti del provider). I valori accettano SecretRef. - - `request.auth`: override della strategia di autenticazione. Modalità: `"provider-default"` (usa l'autenticazione integrata del provider), `"authorization-bearer"` (con `token`), `"header"` (con `headerName`, `value`, `prefix` facoltativo). - - `request.proxy`: override del proxy HTTP. Modalità: `"env-proxy"` (usa le variabili d'ambiente `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (con `url`). Entrambe le modalità accettano un sotto-oggetto `tls` facoltativo. - - `request.tls`: override TLS per connessioni dirette. Campi: `ca`, `cert`, `key`, `passphrase` (tutti accettano SecretRef), `serverName`, `insecureSkipVerify`. - - `request.allowPrivateNetwork`: quando `true`, consente HTTPS verso `baseUrl` quando il DNS si risolve in intervalli privati, CGNAT o simili, tramite la protezione fetch HTTP del provider (attivazione esplicita dell'operatore per endpoint OpenAI-compatibili self-hosted attendibili). WebSocket usa la stessa `request` per header/TLS ma non quella protezione SSRF di fetch. Predefinito `false`. +- `models.providers.*.injectNumCtxForOpenAICompat`: per Ollama + `openai-completions`, inietta `options.num_ctx` nelle richieste (predefinito: `true`). +- `models.providers.*.authHeader`: forza il trasporto delle credenziali nell'header `Authorization` quando richiesto. +- `models.providers.*.baseUrl`: URL base dell'API upstream. +- `models.providers.*.headers`: header statici extra per routing proxy/tenant. +- `models.providers.*.request`: override del trasporto per le richieste HTTP del model-provider. + - `request.headers`: header extra (uniti ai valori predefiniti del provider). I valori accettano SecretRef. + - `request.auth`: override della strategia di autenticazione. Modalità: `"provider-default"` (usa l'autenticazione integrata del provider), `"authorization-bearer"` (con `token`), `"header"` (con `headerName`, `value`, `prefix` opzionale). + - `request.proxy`: override del proxy HTTP. Modalità: `"env-proxy"` (usa le variabili env `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (con `url`). Entrambe le modalità accettano un sotto-oggetto `tls` opzionale. + - `request.tls`: override TLS per le connessioni dirette. Campi: `ca`, `cert`, `key`, `passphrase` (tutti accettano SecretRef), `serverName`, `insecureSkipVerify`. + - `request.allowPrivateNetwork`: quando `true`, consente HTTPS verso `baseUrl` quando il DNS si risolve in intervalli privati, CGNAT o simili, tramite la protezione HTTP fetch SSRF del provider (opt-in dell'operatore per endpoint OpenAI-compatibili self-hosted attendibili). WebSocket usa la stessa `request` per header/TLS ma non quel controllo SSRF fetch. Predefinito `false`. - `models.providers.*.models`: voci esplicite del catalogo modelli del provider. - `models.providers.*.models.*.contextWindow`: metadati della finestra di contesto nativa del modello. -- `models.providers.*.models.*.contextTokens`: limite di contesto runtime facoltativo. Usalo quando vuoi un budget di contesto effettivo più piccolo di `contextWindow` nativo del modello. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: suggerimento facoltativo di compatibilità. Per `api: "openai-completions"` con un `baseUrl` non nativo non vuoto (host diverso da `api.openai.com`), OpenClaw lo forza a `false` in fase di esecuzione. Un `baseUrl` vuoto/omesso mantiene il comportamento OpenAI predefinito. -- `models.providers.*.models.*.compat.requiresStringContent`: suggerimento facoltativo di compatibilità per endpoint chat OpenAI-compatibili che accettano solo stringhe. Quando `true`, OpenClaw appiattisce gli array `messages[].content` di puro testo in stringhe semplici prima di inviare la richiesta. -- `plugins.entries.amazon-bedrock.config.discovery`: radice delle impostazioni di auto-discovery Bedrock. -- `plugins.entries.amazon-bedrock.config.discovery.enabled`: attiva/disattiva la discovery implicita. -- `plugins.entries.amazon-bedrock.config.discovery.region`: regione AWS per la discovery. -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: filtro facoltativo dell'id provider per discovery mirata. -- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: intervallo di polling per l'aggiornamento della discovery. -- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: finestra di contesto di fallback per i modelli individuati. -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: numero massimo di token in output di fallback per i modelli individuati. +- `models.providers.*.models.*.contextTokens`: limite runtime opzionale del contesto. Usalo quando vuoi un budget di contesto effettivo più piccolo della `contextWindow` nativa del modello. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: suggerimento di compatibilità opzionale. Per `api: "openai-completions"` con un `baseUrl` non vuoto e non nativo (host diverso da `api.openai.com`), OpenClaw forza questo valore a `false` a runtime. `baseUrl` vuoto/omesso mantiene il comportamento OpenAI predefinito. +- `models.providers.*.models.*.compat.requiresStringContent`: suggerimento di compatibilità opzionale per endpoint chat OpenAI-compatibili che accettano solo stringhe. Quando `true`, OpenClaw appiattisce gli array `messages[].content` di puro testo in stringhe semplici prima di inviare la richiesta. +- `plugins.entries.amazon-bedrock.config.discovery`: radice delle impostazioni di auto-rilevamento di Bedrock. +- `plugins.entries.amazon-bedrock.config.discovery.enabled`: attiva/disattiva il rilevamento implicito. +- `plugins.entries.amazon-bedrock.config.discovery.region`: regione AWS per il rilevamento. +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: filtro facoltativo per provider-id per un rilevamento mirato. +- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: intervallo di polling per l'aggiornamento del rilevamento. +- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: finestra di contesto di fallback per i modelli rilevati. +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: token massimi di output di fallback per i modelli rilevati. ### Esempi di provider @@ -2499,7 +2494,7 @@ Usa `cerebras/zai-glm-4.7` per Cerebras; `zai/glm-4.7` per Z.AI diretto. } ``` -Imposta `OPENCODE_API_KEY` (o `OPENCODE_ZEN_API_KEY`). Usa riferimenti `opencode/...` per il catalogo Zen o riferimenti `opencode-go/...` per il catalogo Go. Scorciatoia: `openclaw onboard --auth-choice opencode-zen` o `openclaw onboard --auth-choice opencode-go`. +Imposta `OPENCODE_API_KEY` (o `OPENCODE_ZEN_API_KEY`). Usa riferimenti `opencode/...` per il catalogo Zen oppure riferimenti `opencode-go/...` per il catalogo Go. Scorciatoia: `openclaw onboard --auth-choice opencode-zen` oppure `openclaw onboard --auth-choice opencode-go`. @@ -2561,9 +2556,7 @@ Imposta `ZAI_API_KEY`. `z.ai/*` e `z-ai/*` sono alias accettati. Scorciatoia: `o Per l'endpoint Cina: `baseUrl: "https://api.moonshot.cn/v1"` oppure `openclaw onboard --auth-choice moonshot-api-key-cn`. -Gli endpoint Moonshot nativi dichiarano la compatibilità d'uso dello streaming sul trasporto condiviso -`openai-completions`, e OpenClaw la determina in base alle capacità dell'endpoint -piuttosto che solo all'id provider integrato. +Gli endpoint Moonshot nativi dichiarano la compatibilità d'uso dello streaming sul trasporto condiviso `openai-completions`, e OpenClaw basa questo comportamento sulle capability dell'endpoint invece che solo sull'ID provider integrato. @@ -2663,17 +2656,14 @@ Il base URL deve omettere `/v1` (il client Anthropic lo aggiunge). Scorciatoia: Imposta `MINIMAX_API_KEY`. Scorciatoie: `openclaw onboard --auth-choice minimax-global-api` oppure `openclaw onboard --auth-choice minimax-cn-api`. -Il catalogo modelli usa per impostazione predefinita solo M2.7. -Nel percorso di streaming compatibile con Anthropic, OpenClaw disabilita il thinking di MiniMax -per impostazione predefinita a meno che tu non imposti esplicitamente `thinking`. `/fast on` o -`params.fastMode: true` riscrivono `MiniMax-M2.7` in -`MiniMax-M2.7-highspeed`. +Il catalogo dei modelli usa come predefinito solo M2.7. +Nel percorso di streaming compatibile con Anthropic, OpenClaw disabilita per impostazione predefinita il thinking di MiniMax a meno che tu non imposti esplicitamente `thinking`. `/fast on` o `params.fastMode: true` riscrivono `MiniMax-M2.7` in `MiniMax-M2.7-highspeed`. -Vedi [Local Models](/it/gateway/local-models). In breve: esegui un grande modello locale tramite LM Studio Responses API su hardware serio; mantieni uniti i modelli ospitati per il fallback. +Vedi [Local Models](/it/gateway/local-models). In breve: esegui un grande modello locale tramite LM Studio Responses API su hardware serio; mantieni uniti i modelli hosted come fallback. @@ -2704,18 +2694,17 @@ Vedi [Local Models](/it/gateway/local-models). In breve: esegui un grande modell } ``` -- `allowBundled`: allowlist facoltativa solo per le Skills integrate (le Skills gestite/workspace non sono interessate). -- `load.extraDirs`: radici aggiuntive di Skills condivise (precedenza più bassa). -- `install.preferBrew`: quando è true, preferisce gli installer Homebrew quando `brew` è - disponibile, prima di passare ad altri tipi di installer. -- `install.nodeManager`: preferenza dell'installer Node per le specifiche - `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` disabilita una Skills anche se è integrata/installata. -- `entries..apiKey`: scorciatoia per le Skills che dichiarano una variabile env primaria (stringa in chiaro o oggetto SecretRef). +- `allowBundled`: allowlist opzionale solo per le Skills bundled (le Skills managed/workspace non sono interessate). +- `load.extraDirs`: radici extra di Skills condivise (precedenza più bassa). +- `install.preferBrew`: quando è true, preferisce gli installer Homebrew quando `brew` è disponibile prima di ripiegare su altri tipi di installer. +- `install.nodeManager`: preferenza del gestore Node per le specifiche `metadata.openclaw.install` + (`npm` | `pnpm` | `yarn` | `bun`). +- `entries..enabled: false` disabilita una Skills anche se bundled/installata. +- `entries..apiKey`: comodità per le Skills che dichiarano una variabile env primaria (stringa in chiaro o oggetto SecretRef). --- -## Plugins +## Plugin ```json5 { @@ -2740,37 +2729,37 @@ Vedi [Local Models](/it/gateway/local-models). In breve: esegui un grande modell ``` - Caricati da `~/.openclaw/extensions`, `/.openclaw/extensions`, più `plugins.load.paths`. -- La discovery accetta plugin OpenClaw nativi più bundle Codex compatibili e bundle Claude, inclusi bundle Claude senza manifest con layout predefinito. +- Il rilevamento accetta plugin OpenClaw nativi più bundle Codex compatibili e bundle Claude, inclusi i bundle Claude senza manifest con layout predefinito. - **Le modifiche alla configurazione richiedono un riavvio del gateway.** -- `allow`: allowlist facoltativa (vengono caricati solo i plugin elencati). `deny` prevale. -- `plugins.entries..apiKey`: campo di comodità per la chiave API a livello di plugin (quando supportato dal plugin). -- `plugins.entries..env`: mappa di variabili d'ambiente con ambito plugin. -- `plugins.entries..hooks.allowPromptInjection`: quando `false`, il core blocca `before_prompt_build` e ignora i campi che modificano il prompt dal vecchio `before_agent_start`, preservando però i vecchi `modelOverride` e `providerOverride`. Si applica agli hook dei plugin nativi e alle directory hook fornite dai bundle supportati. -- `plugins.entries..subagent.allowModelOverride`: considera esplicitamente attendibile questo plugin per richiedere override per esecuzione di `provider` e `model` per esecuzioni di subagent in background. -- `plugins.entries..subagent.allowedModels`: allowlist facoltativa di destinazioni canoniche `provider/model` per override attendibili dei subagent. Usa `"*"` solo quando vuoi intenzionalmente consentire qualsiasi modello. +- `allow`: allowlist opzionale (vengono caricati solo i plugin elencati). `deny` prevale. +- `plugins.entries..apiKey`: campo di utilità per API key a livello plugin (quando supportato dal plugin). +- `plugins.entries..env`: mappa di variabili env con scope del plugin. +- `plugins.entries..hooks.allowPromptInjection`: quando `false`, il core blocca `before_prompt_build` e ignora i campi legacy che mutano il prompt da `before_agent_start`, preservando però i legacy `modelOverride` e `providerOverride`. Si applica agli hook plugin nativi e alle directory hook fornite dai bundle supportati. +- `plugins.entries..subagent.allowModelOverride`: considera esplicitamente attendibile questo plugin per richiedere override `provider` e `model` per esecuzione nei run in background dei subagenti. +- `plugins.entries..subagent.allowedModels`: allowlist opzionale di target canonici `provider/model` per gli override attendibili dei subagenti. Usa `"*"` solo quando intendi consentire qualsiasi modello. - `plugins.entries..config`: oggetto di configurazione definito dal plugin (convalidato dallo schema del plugin OpenClaw nativo quando disponibile). -- `plugins.entries.firecrawl.config.webFetch`: impostazioni del provider Firecrawl per web fetch. - - `apiKey`: chiave API Firecrawl (accetta SecretRef). Usa come fallback `plugins.entries.firecrawl.config.webSearch.apiKey`, il vecchio `tools.web.fetch.firecrawl.apiKey` o la variabile d'ambiente `FIRECRAWL_API_KEY`. - - `baseUrl`: URL di base dell'API Firecrawl (predefinito: `https://api.firecrawl.dev`). +- `plugins.entries.firecrawl.config.webFetch`: impostazioni del provider Firecrawl web-fetch. + - `apiKey`: chiave API Firecrawl (accetta SecretRef). Usa come fallback `plugins.entries.firecrawl.config.webSearch.apiKey`, il legacy `tools.web.fetch.firecrawl.apiKey` o la variabile env `FIRECRAWL_API_KEY`. + - `baseUrl`: URL base dell'API Firecrawl (predefinito: `https://api.firecrawl.dev`). - `onlyMainContent`: estrae solo il contenuto principale dalle pagine (predefinito: `true`). - `maxAgeMs`: età massima della cache in millisecondi (predefinito: `172800000` / 2 giorni). - `timeoutSeconds`: timeout della richiesta di scraping in secondi (predefinito: `60`). -- `plugins.entries.xai.config.xSearch`: impostazioni xAI X Search (ricerca web Grok). +- `plugins.entries.xai.config.xSearch`: impostazioni di xAI X Search (ricerca web Grok). - `enabled`: abilita il provider X Search. - `model`: modello Grok da usare per la ricerca (ad esempio `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: impostazioni del dreaming della memoria (sperimentale). Vedi [Dreaming](/it/concepts/dreaming) per fasi e soglie. - - `enabled`: interruttore principale del dreaming (predefinito `false`). - - `frequency`: cadenza cron per ogni passaggio completo di dreaming (predefinita `"0 3 * * *"`). - - i criteri di fase e le soglie sono dettagli implementativi (non chiavi di configurazione rivolte all'utente). -- La configurazione completa della memoria si trova in [Memory configuration reference](/it/reference/memory-config): +- `plugins.entries.memory-core.config.dreaming`: impostazioni del dreaming della memoria. Vedi [Dreaming](/it/concepts/dreaming) per fasi e soglie. + - `enabled`: interruttore principale di Dreaming (predefinito `false`). + - `frequency`: cadenza Cron per ogni ciclo completo di Dreaming (predefinito `"0 3 * * *"`). + - il criterio di fase e le soglie sono dettagli di implementazione (non chiavi di configurazione rivolte all'utente). +- La configurazione completa della memoria si trova in [Riferimento della configurazione della memoria](/it/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- I plugin bundle Claude abilitati possono anche contribuire con valori predefiniti di Pi incorporati da `settings.json`; OpenClaw li applica come impostazioni dell'agente sanificate, non come patch grezze della configurazione OpenClaw. +- I plugin bundle Claude abilitati possono anche contribuire ai valori predefiniti embedded di Pi da `settings.json`; OpenClaw li applica come impostazioni dell'agente sanificate, non come patch raw della configurazione OpenClaw. - `plugins.slots.memory`: scegli l'id del plugin memoria attivo, oppure `"none"` per disabilitare i plugin memoria. -- `plugins.slots.contextEngine`: scegli l'id del plugin motore di contesto attivo; il valore predefinito è `"legacy"` a meno che tu non installi e selezioni un altro motore. +- `plugins.slots.contextEngine`: scegli l'id del plugin context engine attivo; il valore predefinito è `"legacy"` finché non installi e selezioni un altro engine. - `plugins.installs`: metadati di installazione gestiti dalla CLI usati da `openclaw plugins update`. - Include `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. - Tratta `plugins.installs.*` come stato gestito; preferisci i comandi CLI alle modifiche manuali. @@ -2788,7 +2777,7 @@ Vedi [Plugins](/it/tools/plugin). evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // attiva solo per accesso attendibile a reti private + // dangerouslyAllowPrivateNetwork: true, // opt-in solo per accesso attendibile alla rete privata // allowPrivateNetwork: true, // alias legacy // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], @@ -2816,28 +2805,23 @@ Vedi [Plugins](/it/tools/plugin). ``` - `evaluateEnabled: false` disabilita `act:evaluate` e `wait --fn`. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` è disabilitato quando non impostato, quindi la navigazione del browser resta rigorosa per impostazione predefinita. -- Imposta `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` solo quando ti fidi intenzionalmente della navigazione del browser su reti private. -- In modalità rigorosa, gli endpoint dei profili CDP remoti (`profiles.*.cdpUrl`) sono soggetti allo stesso blocco delle reti private durante i controlli di raggiungibilità/discovery. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` è disabilitato quando non è impostato, quindi la navigazione del browser resta rigorosa per impostazione predefinita. +- Imposta `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` solo quando intendi fidarti esplicitamente della navigazione browser sulla rete privata. +- In modalità rigorosa, gli endpoint remoti del profilo CDP (`profiles.*.cdpUrl`) sono soggetti allo stesso blocco della rete privata durante i controlli di raggiungibilità/rilevamento. - `ssrfPolicy.allowPrivateNetwork` resta supportato come alias legacy. - In modalità rigorosa, usa `ssrfPolicy.hostnameAllowlist` e `ssrfPolicy.allowedHostnames` per eccezioni esplicite. -- I profili remoti sono solo attach-only (avvio/arresto/reset disabilitati). +- I profili remoti sono solo attach-only (start/stop/reset disabilitati). - `profiles.*.cdpUrl` accetta `http://`, `https://`, `ws://` e `wss://`. Usa HTTP(S) quando vuoi che OpenClaw rilevi `/json/version`; usa WS(S) - quando il tuo provider ti fornisce un URL WebSocket DevTools diretto. + quando il provider ti fornisce un URL WebSocket DevTools diretto. - I profili `existing-session` sono solo host e usano Chrome MCP invece di CDP. -- I profili `existing-session` possono impostare `userDataDir` per puntare a un profilo specifico - di browser basato su Chromium come Brave o Edge. +- I profili `existing-session` possono impostare `userDataDir` per puntare a un profilo specifico di browser basato su Chromium, come Brave o Edge. - I profili `existing-session` mantengono gli attuali limiti del percorso Chrome MCP: - azioni basate su snapshot/riferimenti invece del targeting con selettori CSS, hook di upload - di un solo file, nessun override del timeout delle finestre di dialogo, nessun `wait --load networkidle`, e nessun - `responsebody`, esportazione PDF, intercettazione dei download o azioni batch. -- I profili `openclaw` gestiti localmente assegnano automaticamente `cdpPort` e `cdpUrl`; imposta - `cdpUrl` esplicitamente solo per CDP remoto. -- Ordine di rilevamento automatico: browser predefinito se basato su Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. + azioni basate su snapshot/ref invece del targeting tramite selettori CSS, hook per upload di un solo file, nessun override del timeout dei dialoghi, nessun `wait --load networkidle` e nessun `responsebody`, esportazione PDF, intercettazione dei download o azioni batch. +- I profili locali gestiti `openclaw` assegnano automaticamente `cdpPort` e `cdpUrl`; imposta `cdpUrl` esplicitamente solo per CDP remoto. +- Ordine di auto-rilevamento: browser predefinito se basato su Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. - Servizio di controllo: solo loopback (porta derivata da `gateway.port`, predefinita `18791`). -- `extraArgs` aggiunge flag di avvio extra all'avvio locale di Chromium (per esempio - `--disable-gpu`, dimensionamento finestra o flag di debug). +- `extraArgs` aggiunge flag di avvio extra all'avvio locale di Chromium (ad esempio `--disable-gpu`, dimensionamento della finestra o flag di debug). --- @@ -2855,7 +2839,7 @@ Vedi [Plugins](/it/tools/plugin). } ``` -- `seamColor`: colore di accento per il chrome della UI dell'app nativa (tinta del fumetto della modalità Talk, ecc.). +- `seamColor`: colore d'accento per la chrome della UI dell'app nativa (tinta della bolla Talk Mode, ecc.). - `assistant`: override dell'identità della Control UI. Usa come fallback l'identità dell'agente attivo. --- @@ -2890,9 +2874,9 @@ Vedi [Plugins](/it/tools/plugin). basePath: "/openclaw", // root: "dist/control-ui", // embedSandbox: "scripts", // strict | scripts | trusted - // allowExternalEmbedUrls: false, // pericoloso: consenti URL embed http(s) esterni assoluti + // allowExternalEmbedUrls: false, // pericoloso: consente URL embed esterni assoluti http(s) // allowedOrigins: ["https://control.example.com"], // richiesto per Control UI non loopback - // dangerouslyAllowHostHeaderOriginFallback: false, // modalità pericolosa di fallback origine Host-header + // dangerouslyAllowHostHeaderOriginFallback: false, // modalità pericolosa di fallback dell'origine Host-header // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -2903,12 +2887,12 @@ Vedi [Plugins](/it/tools/plugin). // password: "your-password", }, trustedProxies: ["10.0.0.1"], - // Facoltativo. Predefinito false. + // Opzionale. Predefinito false. allowRealIpFallback: false, tools: { - // Ulteriori rifiuti HTTP per /tools/invoke + // deny HTTP aggiuntivi per /tools/invoke deny: ["browser"], - // Rimuove strumenti dalla deny list HTTP predefinita + // Rimuove strumenti dall'elenco deny HTTP predefinito allow: ["gateway"], }, push: { @@ -2923,66 +2907,65 @@ Vedi [Plugins](/it/tools/plugin). } ``` - + -- `mode`: `local` (esegue il gateway) o `remote` (si connette a un gateway remoto). Il gateway rifiuta di avviarsi a meno che non sia `local`. -- `port`: porta singola multiplexata per WS + HTTP. Precedenza: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. -- `bind`: `auto`, `loopback` (predefinito), `lan` (`0.0.0.0`), `tailnet` (solo IP Tailscale) o `custom`. +- `mode`: `local` (esegui il gateway) oppure `remote` (connettiti a un gateway remoto). Il Gateway rifiuta di avviarsi a meno che non sia `local`. +- `port`: singola porta multiplexata per WS + HTTP. Precedenza: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. +- `bind`: `auto`, `loopback` (predefinito), `lan` (`0.0.0.0`), `tailnet` (solo IP Tailscale) oppure `custom`. - **Alias bind legacy**: usa i valori della modalità bind in `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), non gli alias host (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Nota Docker**: il bind predefinito `loopback` ascolta su `127.0.0.1` dentro il container. Con il networking bridge Docker (`-p 18789:18789`), il traffico arriva su `eth0`, quindi il gateway non è raggiungibile. Usa `--network host`, oppure imposta `bind: "lan"` (o `bind: "custom"` con `customBindHost: "0.0.0.0"`) per ascoltare su tutte le interfacce. -- **Auth**: richiesta per impostazione predefinita. I bind non loopback richiedono l'autenticazione del gateway. In pratica ciò significa un token/password condiviso oppure un reverse proxy identity-aware con `gateway.auth.mode: "trusted-proxy"`. La procedura guidata di onboarding genera un token per impostazione predefinita. +- **Nota Docker**: il bind predefinito `loopback` ascolta su `127.0.0.1` all'interno del container. Con il networking bridge di Docker (`-p 18789:18789`), il traffico arriva su `eth0`, quindi il gateway non è raggiungibile. Usa `--network host`, oppure imposta `bind: "lan"` (o `bind: "custom"` con `customBindHost: "0.0.0.0"`) per ascoltare su tutte le interfacce. +- **Auth**: richiesta per impostazione predefinita. I bind non loopback richiedono l'autenticazione del gateway. In pratica questo significa un token/password condiviso oppure un reverse proxy identity-aware con `gateway.auth.mode: "trusted-proxy"`. La procedura guidata di onboarding genera un token per impostazione predefinita. - Se sono configurati sia `gateway.auth.token` sia `gateway.auth.password` (inclusi SecretRef), imposta esplicitamente `gateway.auth.mode` su `token` o `password`. L'avvio e i flussi di installazione/riparazione del servizio falliscono quando entrambi sono configurati e la modalità non è impostata. -- `gateway.auth.mode: "none"`: modalità esplicita senza autenticazione. Usala solo per configurazioni attendibili su local loopback; intenzionalmente questa opzione non viene proposta dai prompt di onboarding. -- `gateway.auth.mode: "trusted-proxy"`: delega l'autenticazione a un reverse proxy identity-aware e si fida degli header di identità da `gateway.trustedProxies` (vedi [Trusted Proxy Auth](/it/gateway/trusted-proxy-auth)). Questa modalità si aspetta una sorgente proxy **non loopback**; i reverse proxy loopback sullo stesso host non soddisfano l'autenticazione trusted-proxy. -- `gateway.auth.allowTailscale`: quando `true`, gli header di identità di Tailscale Serve possono soddisfare l'autenticazione di Control UI/WebSocket (verificata tramite `tailscale whois`). Gli endpoint API HTTP **non** usano quell'autenticazione tramite header Tailscale; seguono invece la normale modalità HTTP auth del gateway. Questo flusso senza token presuppone che l'host del gateway sia attendibile. Il valore predefinito è `true` quando `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: limitatore facoltativo per autenticazioni fallite. Si applica per IP client e per ambito auth (segreto condiviso e token dispositivo vengono tracciati indipendentemente). I tentativi bloccati restituiscono `429` + `Retry-After`. - - Sul percorso asincrono Tailscale Serve Control UI, i tentativi falliti per lo stesso `{scope, clientIp}` vengono serializzati prima della scrittura del fallimento. Tentativi errati concorrenti dello stesso client possono quindi attivare il limitatore alla seconda richiesta invece di passare entrambi come semplici mancati match. - - `gateway.auth.rateLimit.exemptLoopback` è `true` per impostazione predefinita; imposta `false` quando vuoi intenzionalmente limitare anche il traffico localhost (per setup di test o deployment proxy rigorosi). -- I tentativi di autenticazione WS con origine browser vengono sempre limitati con l'esenzione loopback disabilitata (difesa in profondità contro brute force localhost basato su browser). -- Su loopback, quei blocchi di origine browser sono isolati per valore `Origin` - normalizzato, così fallimenti ripetuti da un'origine localhost non bloccano automaticamente - un'origine diversa. -- `tailscale.mode`: `serve` (solo tailnet, bind loopback) o `funnel` (pubblico, richiede auth). -- `controlUi.allowedOrigins`: allowlist esplicita delle origini browser per le connessioni WebSocket al Gateway. Richiesta quando ci si aspettano client browser da origini non loopback. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: modalità pericolosa che abilita il fallback dell'origine dall'header Host per deployment che si basano intenzionalmente su una policy di origine basata su Host-header. -- `remote.transport`: `ssh` (predefinito) o `direct` (ws/wss). Per `direct`, `remote.url` deve essere `ws://` o `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: override break-glass lato client che consente `ws://` in chiaro verso IP attendibili di rete privata; il valore predefinito resta solo loopback per il traffico in chiaro. +- `gateway.auth.mode: "none"`: modalità esplicita senza autenticazione. Usala solo per configurazioni trusted local loopback; intenzionalmente non viene proposta dai prompt di onboarding. +- `gateway.auth.mode: "trusted-proxy"`: delega l'autenticazione a un reverse proxy identity-aware e considera attendibili gli header di identità da `gateway.trustedProxies` (vedi [Trusted Proxy Auth](/it/gateway/trusted-proxy-auth)). Questa modalità si aspetta una sorgente proxy **non loopback**; i reverse proxy loopback sullo stesso host non soddisfano l'autenticazione trusted-proxy. +- `gateway.auth.allowTailscale`: quando `true`, gli header di identità Tailscale Serve possono soddisfare l'autenticazione di Control UI/WebSocket (verificata tramite `tailscale whois`). Gli endpoint API HTTP **non** usano quell'autenticazione tramite header Tailscale; seguono invece la normale modalità di autenticazione HTTP del gateway. Questo flusso senza token presume che l'host del gateway sia attendibile. Il valore predefinito è `true` quando `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: limitatore opzionale dei tentativi di autenticazione falliti. Si applica per IP client e per ambito auth (shared-secret e device-token vengono tracciati in modo indipendente). I tentativi bloccati restituiscono `429` + `Retry-After`. + - Sul percorso asincrono di Tailscale Serve Control UI, i tentativi falliti per lo stesso `{scope, clientIp}` vengono serializzati prima della scrittura del fallimento. Tentativi concorrenti non validi dallo stesso client possono quindi attivare il limitatore sulla seconda richiesta invece di passare entrambi come semplici mismatch. + - `gateway.auth.rateLimit.exemptLoopback` ha come predefinito `true`; impostalo su `false` quando vuoi intenzionalmente applicare il rate limit anche al traffico localhost (per configurazioni di test o deployment proxy rigorosi). +- I tentativi di autenticazione WS da origine browser vengono sempre limitati con l'esenzione loopback disabilitata (defense-in-depth contro la forza bruta localhost basata su browser). +- Su loopback, quei lockout da origine browser sono isolati per valore `Origin` + normalizzato, così fallimenti ripetuti da un'origine localhost non bloccano automaticamente un'origine diversa. +- `tailscale.mode`: `serve` (solo tailnet, bind loopback) oppure `funnel` (pubblico, richiede auth). +- `controlUi.allowedOrigins`: allowlist esplicita delle origini browser per le connessioni WebSocket del Gateway. Richiesta quando si prevedono client browser da origini non loopback. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: modalità pericolosa che abilita il fallback dell'origine basato sull'header Host per deployment che dipendono intenzionalmente da una policy di origine basata su Host-header. +- `remote.transport`: `ssh` (predefinito) oppure `direct` (ws/wss). Per `direct`, `remote.url` deve essere `ws://` oppure `wss://`. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: override break-glass lato client che consente `ws://` in chiaro verso IP attendibili di rete privata; il comportamento predefinito resta solo-loopback per il traffico in chiaro. - `gateway.remote.token` / `.password` sono campi credenziali del client remoto. Non configurano da soli l'autenticazione del gateway. -- `gateway.push.apns.relay.baseUrl`: URL HTTPS di base per il relay APNs esterno usato dalle build iOS ufficiali/TestFlight dopo che pubblicano registrazioni relay-backed sul gateway. Questo URL deve corrispondere all'URL relay compilato nella build iOS. -- `gateway.push.apns.relay.timeoutMs`: timeout in millisecondi per l'invio dal gateway al relay. Predefinito `10000`. -- Le registrazioni relay-backed sono delegate a una specifica identità gateway. L'app iOS associata recupera `gateway.identity.get`, include quell'identità nella registrazione relay e inoltra al gateway una concessione di invio con ambito di registrazione. Un altro gateway non può riutilizzare quella registrazione memorizzata. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: override env temporanei per la configurazione relay sopra indicata. +- `gateway.push.apns.relay.baseUrl`: URL HTTPS base per il relay APNs esterno usato dalle build iOS ufficiali/TestFlight dopo che pubblicano al gateway registrazioni supportate da relay. Questo URL deve corrispondere all'URL relay compilato nella build iOS. +- `gateway.push.apns.relay.timeoutMs`: timeout in millisecondi per l'invio dal gateway al relay. Predefinito: `10000`. +- Le registrazioni supportate da relay vengono delegate a una specifica identità del gateway. L'app iOS associata recupera `gateway.identity.get`, include quell'identità nella registrazione relay e inoltra al gateway una send grant con scope della registrazione. Un altro gateway non può riutilizzare quella registrazione memorizzata. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: override temporanei via env per la configurazione relay sopra. - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: escape hatch solo per sviluppo per URL relay HTTP loopback. Gli URL relay di produzione devono restare su HTTPS. - `gateway.channelHealthCheckMinutes`: intervallo in minuti del monitor di salute dei canali. Imposta `0` per disabilitare globalmente i riavvii del monitor di salute. Predefinito: `5`. - `gateway.channelStaleEventThresholdMinutes`: soglia in minuti per socket obsoleti. Mantienila maggiore o uguale a `gateway.channelHealthCheckMinutes`. Predefinito: `30`. - `gateway.channelMaxRestartsPerHour`: numero massimo di riavvii del monitor di salute per canale/account in un'ora mobile. Predefinito: `10`. -- `channels..healthMonitor.enabled`: opt-out per canale dei riavvii del monitor di salute mantenendo attivo il monitor globale. -- `channels..accounts..healthMonitor.enabled`: override per account per canali multi-account. Quando impostato, ha precedenza sull'override a livello canale. +- `channels..healthMonitor.enabled`: opt-out per canale dei riavvii del monitor di salute mantenendo comunque abilitato il monitor globale. +- `channels..accounts..healthMonitor.enabled`: override per account per i canali multi-account. Quando è impostato, ha la precedenza sull'override a livello di canale. - I percorsi di chiamata del gateway locale possono usare `gateway.remote.*` come fallback solo quando `gateway.auth.*` non è impostato. -- Se `gateway.auth.token` / `gateway.auth.password` è configurato esplicitamente tramite SecretRef e non risolto, la risoluzione fallisce in modalità chiusa (nessun fallback remoto che mascheri il problema). -- `trustedProxies`: IP dei reverse proxy che terminano TLS o inseriscono header del client inoltrato. Elenca solo proxy che controlli. Le voci loopback restano valide per setup con proxy sullo stesso host/rilevamento locale (per esempio Tailscale Serve o un reverse proxy locale), ma **non** rendono le richieste loopback idonee a `gateway.auth.mode: "trusted-proxy"`. -- `allowRealIpFallback`: quando `true`, il gateway accetta `X-Real-IP` se manca `X-Forwarded-For`. Predefinito `false` per comportamento fail-closed. -- `gateway.tools.deny`: nomi di strumenti aggiuntivi bloccati per HTTP `POST /tools/invoke` (estende la deny list predefinita). -- `gateway.tools.allow`: rimuove nomi di strumenti dalla deny list HTTP predefinita. +- Se `gateway.auth.token` / `gateway.auth.password` è configurato esplicitamente tramite SecretRef e non viene risolto, la risoluzione fallisce in modalità fail-closed (nessun fallback remoto che mascheri il problema). +- `trustedProxies`: IP di reverse proxy che terminano TLS o iniettano header del client inoltrato. Elenca solo proxy che controlli. Le voci loopback restano valide per configurazioni di rilevamento stesso-host/proxy locale (ad esempio Tailscale Serve o un reverse proxy locale), ma **non** rendono idonee le richieste loopback a `gateway.auth.mode: "trusted-proxy"`. +- `allowRealIpFallback`: quando `true`, il gateway accetta `X-Real-IP` se `X-Forwarded-For` manca. Predefinito `false` per comportamento fail-closed. +- `gateway.tools.deny`: nomi di strumenti extra bloccati per HTTP `POST /tools/invoke` (estende l'elenco deny predefinito). +- `gateway.tools.allow`: rimuove nomi di strumenti dall'elenco deny HTTP predefinito. ### Endpoint compatibili con OpenAI - Chat Completions: disabilitato per impostazione predefinita. Abilitalo con `gateway.http.endpoints.chatCompletions.enabled: true`. -- API Responses: `gateway.http.endpoints.responses.enabled`. -- Hardened URL-input per Responses: +- Responses API: `gateway.http.endpoints.responses.enabled`. +- Hardening dell'input URL di Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` Le allowlist vuote vengono trattate come non impostate; usa `gateway.http.endpoints.responses.files.allowUrl=false` e/o `gateway.http.endpoints.responses.images.allowUrl=false` per disabilitare il recupero tramite URL. -- Header facoltativo di hardening della risposta: +- Header opzionale di hardening della risposta: - `gateway.http.securityHeaders.strictTransportSecurity` (impostalo solo per origini HTTPS che controlli; vedi [Trusted Proxy Auth](/it/gateway/trusted-proxy-auth#tls-termination-and-hsts)) -### Isolamento multiistanza +### Isolamento multi-istanza -Esegui più gateway su un host con porte e directory di stato uniche: +Esegui più gateway su un unico host con porte e directory di stato univoche: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -2990,7 +2973,7 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \ openclaw gateway --port 19001 ``` -Flag di comodità: `--dev` (usa `~/.openclaw-dev` + porta `19001`), `--profile ` (usa `~/.openclaw-`). +Flag di utilità: `--dev` (usa `~/.openclaw-dev` + porta `19001`), `--profile ` (usa `~/.openclaw-`). Vedi [Multiple Gateways](/it/gateway/multiple-gateways). @@ -3010,11 +2993,11 @@ Vedi [Multiple Gateways](/it/gateway/multiple-gateways). } ``` -- `enabled`: abilita la terminazione TLS sul listener gateway (HTTPS/WSS) (predefinito: `false`). -- `autoGenerate`: genera automaticamente una coppia locale certificato/chiave self-signed quando non sono configurati file espliciti; solo per uso locale/dev. -- `certPath`: percorso filesystem del file certificato TLS. -- `keyPath`: percorso filesystem del file chiave privata TLS; mantienilo con permessi limitati. -- `caPath`: percorso facoltativo del bundle CA per verifica client o catene di trust personalizzate. +- `enabled`: abilita la terminazione TLS sul listener del gateway (HTTPS/WSS) (predefinito: `false`). +- `autoGenerate`: genera automaticamente una coppia locale certificato/chiave autofirmata quando non sono configurati file espliciti; solo per uso locale/dev. +- `certPath`: percorso filesystem del file del certificato TLS. +- `keyPath`: percorso filesystem della chiave privata TLS; mantienilo con permessi limitati. +- `caPath`: percorso opzionale del bundle CA per la verifica del client o catene di trust personalizzate. ### `gateway.reload` @@ -3030,13 +3013,13 @@ Vedi [Multiple Gateways](/it/gateway/multiple-gateways). } ``` -- `mode`: controlla come vengono applicate in fase di esecuzione le modifiche alla configurazione. +- `mode`: controlla come vengono applicate a runtime le modifiche alla configurazione. - `"off"`: ignora le modifiche live; i cambiamenti richiedono un riavvio esplicito. - - `"restart"`: riavvia sempre il processo gateway in caso di modifica della configurazione. - - `"hot"`: applica le modifiche nel processo senza riavvio. - - `"hybrid"` (predefinito): prova prima l'hot reload; se necessario, passa al riavvio. -- `debounceMs`: finestra di debounce in ms prima che le modifiche alla configurazione vengano applicate (intero non negativo). -- `deferralTimeoutMs`: tempo massimo in ms di attesa per le operazioni in corso prima di forzare un riavvio (predefinito: `300000` = 5 minuti). + - `"restart"`: riavvia sempre il processo del gateway in caso di modifica della configurazione. + - `"hot"`: applica i cambiamenti nel processo senza riavviare. + - `"hybrid"` (predefinito): prova prima l'hot reload; se necessario torna al riavvio. +- `debounceMs`: finestra di debounce in ms prima che le modifiche di configurazione vengano applicate (intero non negativo). +- `deferralTimeoutMs`: tempo massimo in ms per attendere le operazioni in corso prima di forzare un riavvio (predefinito: `300000` = 5 minuti). --- @@ -3074,14 +3057,14 @@ Vedi [Multiple Gateways](/it/gateway/multiple-gateways). ``` Auth: `Authorization: Bearer ` oppure `x-openclaw-token: `. -I token hook nella query string vengono rifiutati. +I token degli hook nella query string vengono rifiutati. Note su convalida e sicurezza: - `hooks.enabled=true` richiede un `hooks.token` non vuoto. -- `hooks.token` deve essere **distinto** da `gateway.auth.token`; il riutilizzo del token Gateway viene rifiutato. +- `hooks.token` deve essere **distinto** da `gateway.auth.token`; il riuso del token del Gateway viene rifiutato. - `hooks.path` non può essere `/`; usa un sottopercorso dedicato come `/hooks`. -- Se `hooks.allowRequestSessionKey=true`, limita `hooks.allowedSessionKeyPrefixes` (per esempio `["hook:"]`). +- Se `hooks.allowRequestSessionKey=true`, limita `hooks.allowedSessionKeyPrefixes` (ad esempio `["hook:"]`). **Endpoint:** @@ -3092,18 +3075,18 @@ Note su convalida e sicurezza: -- `match.path` corrisponde al sottopercorso dopo `/hooks` (ad esempio `/hooks/gmail` → `gmail`). -- `match.source` corrisponde a un campo del payload per percorsi generici. +- `match.path` corrisponde al sotto-percorso dopo `/hooks` (ad es. `/hooks/gmail` → `gmail`). +- `match.source` corrisponde a un campo del payload per i percorsi generici. - I template come `{{messages[0].subject}}` leggono dal payload. - `transform` può puntare a un modulo JS/TS che restituisce un'azione hook. - - `transform.module` deve essere un percorso relativo e restare entro `hooks.transformsDir` (i percorsi assoluti e l'attraversamento vengono rifiutati). -- `agentId` instrada a un agente specifico; gli ID sconosciuti usano come fallback il predefinito. -- `allowedAgentIds`: limita l'instradamento esplicito (`*` o omesso = consenti tutti, `[]` = nega tutti). -- `defaultSessionKey`: chiave sessione fissa facoltativa per esecuzioni dell'agente hook senza `sessionKey` esplicito. + - `transform.module` deve essere un percorso relativo e rimanere entro `hooks.transformsDir` (i percorsi assoluti e il traversal vengono rifiutati). +- `agentId` instrada verso un agente specifico; gli ID sconosciuti usano come fallback il predefinito. +- `allowedAgentIds`: limita il routing esplicito (`*` o omesso = consenti tutti, `[]` = nega tutti). +- `defaultSessionKey`: chiave di sessione fissa opzionale per le esecuzioni dell'agente hook senza `sessionKey` esplicito. - `allowRequestSessionKey`: consente ai chiamanti di `/hooks/agent` di impostare `sessionKey` (predefinito: `false`). -- `allowedSessionKeyPrefixes`: allowlist facoltativa di prefissi per valori `sessionKey` espliciti (richiesta + mappatura), ad esempio `["hook:"]`. -- `deliver: true` invia la risposta finale a un canale; `channel` usa come predefinito `last`. -- `model` sostituisce l'LLM per questa esecuzione hook (deve essere consentito se è impostato il catalogo modelli). +- `allowedSessionKeyPrefixes`: allowlist opzionale di prefissi per valori espliciti di `sessionKey` (richiesta + mappatura), ad es. `["hook:"]`. +- `deliver: true` invia la risposta finale a un canale; `channel` ha come predefinito `last`. +- `model` sovrascrive l'LLM per questa esecuzione hook (deve essere consentito se è impostato il catalogo modelli). @@ -3130,12 +3113,12 @@ Note su convalida e sicurezza: } ``` -- Il gateway avvia automaticamente `gog gmail watch serve` all'avvio quando è configurato. Imposta `OPENCLAW_SKIP_GMAIL_WATCHER=1` per disabilitarlo. +- Il Gateway avvia automaticamente `gog gmail watch serve` all'avvio quando è configurato. Imposta `OPENCLAW_SKIP_GMAIL_WATCHER=1` per disabilitarlo. - Non eseguire un `gog gmail watch serve` separato insieme al Gateway. --- -## Host canvas +## Canvas host ```json5 { @@ -3147,18 +3130,18 @@ Note su convalida e sicurezza: } ``` -- Serve HTML/CSS/JS modificabili dall'agente e A2UI tramite HTTP sotto la porta del Gateway: +- Serve HTML/CSS/JS modificabili dall'agente e A2UI via HTTP sotto la porta del Gateway: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` - Solo locale: mantieni `gateway.bind: "loopback"` (predefinito). -- Bind non loopback: le route canvas richiedono l'autenticazione Gateway (token/password/trusted-proxy), come le altre superfici HTTP del Gateway. -- I WebView Node in genere non inviano header di autenticazione; dopo che un node è associato e connesso, il Gateway pubblicizza URL di capability con ambito node per l'accesso a canvas/A2UI. -- Gli URL di capability sono associati alla sessione WS attiva del node e scadono rapidamente. Non viene usato alcun fallback basato su IP. -- Inserisce il client di live reload nell'HTML servito. -- Crea automaticamente un `index.html` iniziale quando è vuoto. -- Serve anche A2UI in `/__openclaw__/a2ui/`. +- Bind non loopback: le route canvas richiedono l'autenticazione del Gateway (token/password/trusted-proxy), come le altre superfici HTTP del Gateway. +- I Node WebView di solito non inviano header di autenticazione; dopo che un node è associato e connesso, il Gateway pubblicizza URL capability con scope del node per l'accesso a canvas/A2UI. +- Gli URL capability sono associati alla sessione WS attiva del node e scadono rapidamente. Non viene usato un fallback basato su IP. +- Inietta il client live-reload nell'HTML servito. +- Crea automaticamente un `index.html` iniziale quando vuoto. +- Serve anche A2UI su `/__openclaw__/a2ui/`. - Le modifiche richiedono un riavvio del gateway. -- Disabilita il live reload per directory grandi o errori `EMFILE`. +- Disabilita il live reload per directory grandi o in caso di errori `EMFILE`. --- @@ -3178,7 +3161,7 @@ Note su convalida e sicurezza: - `minimal` (predefinito): omette `cliPath` + `sshPort` dai record TXT. - `full`: include `cliPath` + `sshPort`. -- L'hostname usa come predefinito `openclaw`. Sostituiscilo con `OPENCLAW_MDNS_HOSTNAME`. +- L'hostname predefinito è `openclaw`. Sovrascrivilo con `OPENCLAW_MDNS_HOSTNAME`. ### Wide-area (DNS-SD) @@ -3190,7 +3173,7 @@ Note su convalida e sicurezza: } ``` -Scrive una zona DNS-SD unicast sotto `~/.openclaw/dns/`. Per la discovery tra reti, abbinalo a un server DNS (CoreDNS consigliato) + split DNS Tailscale. +Scrive una zona DNS-SD unicast sotto `~/.openclaw/dns/`. Per il rilevamento cross-network, abbinala a un server DNS (CoreDNS consigliato) + split DNS Tailscale. Configurazione: `openclaw dns setup --apply`. @@ -3215,9 +3198,9 @@ Configurazione: `openclaw dns setup --apply`. } ``` -- Le variabili env inline vengono applicate solo se nell'env del processo manca la chiave. -- File `.env`: `.env` della CWD + `~/.openclaw/.env` (nessuno dei due sostituisce variabili esistenti). -- `shellEnv`: importa le chiavi previste mancanti dal profilo della tua shell di login. +- Le variabili env inline vengono applicate solo se l'env del processo non contiene la chiave. +- File `.env`: `.env` nella CWD + `~/.openclaw/.env` (nessuno dei due sovrascrive le variabili esistenti). +- `shellEnv`: importa le chiavi attese mancanti dal profilo della tua shell di login. - Vedi [Environment](/it/help/environment) per la precedenza completa. ### Sostituzione delle variabili env @@ -3232,9 +3215,9 @@ Fai riferimento alle variabili env in qualsiasi stringa di configurazione con `$ } ``` -- Vengono corrisposti solo nomi in maiuscolo: `[A-Z_][A-Z0-9_]*`. -- Variabili mancanti/vuote generano un errore durante il caricamento della configurazione. -- Escape con `$${VAR}` per un letterale `${VAR}`. +- Vengono riconosciuti solo i nomi in maiuscolo: `[A-Z_][A-Z0-9_]*`. +- Variabili mancanti/vuote generano un errore al caricamento della configurazione. +- Usa l'escape `$${VAR}` per un `${VAR}` letterale. - Funziona con `$include`. --- @@ -3254,16 +3237,16 @@ Usa una forma oggetto: Convalida: - pattern `provider`: `^[a-z][a-z0-9_-]{0,63}$` -- pattern id `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` -- id `source: "file"`: puntatore JSON assoluto (per esempio `"/providers/openai/apiKey"`) -- pattern id `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- gli id `source: "exec"` non devono contenere segmenti di percorso delimitati da slash `.` o `..` (per esempio `a/../b` viene rifiutato) +- pattern `id` per `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` +- `id` per `source: "file"`: puntatore JSON assoluto (ad esempio `"/providers/openai/apiKey"`) +- pattern `id` per `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` +- Gli `id` con `source: "exec"` non devono contenere segmenti di percorso `.` o `..` delimitati da slash (ad esempio `a/../b` viene rifiutato) -### Superficie credenziali supportata +### Superficie delle credenziali supportata - Matrice canonica: [SecretRef Credential Surface](/it/reference/secretref-credential-surface) -- `secrets apply` usa come destinazione i percorsi credenziali supportati di `openclaw.json`. -- I riferimenti `auth-profiles.json` sono inclusi nella risoluzione runtime e nella copertura di audit. +- `secrets apply` ha come destinazione i percorsi delle credenziali supportati in `openclaw.json`. +- I riferimenti in `auth-profiles.json` sono inclusi nella risoluzione runtime e nella copertura dell'audit. ### Configurazione dei provider di segreti @@ -3271,7 +3254,7 @@ Convalida: { secrets: { providers: { - default: { source: "env" }, // provider env esplicito facoltativo + default: { source: "env" }, // provider env esplicito opzionale filemain: { source: "file", path: "~/.openclaw/secrets.json", @@ -3297,11 +3280,11 @@ Note: - Il provider `file` supporta `mode: "json"` e `mode: "singleValue"` (`id` deve essere `"value"` in modalità singleValue). - Il provider `exec` richiede un percorso `command` assoluto e usa payload di protocollo su stdin/stdout. -- Per impostazione predefinita, i percorsi di comando symlink vengono rifiutati. Imposta `allowSymlinkCommand: true` per consentire percorsi symlink validando però il percorso target risolto. -- Se `trustedDirs` è configurato, il controllo delle directory attendibili si applica al percorso target risolto. -- L'ambiente figlio `exec` è minimo per impostazione predefinita; passa esplicitamente le variabili richieste con `passEnv`. -- I riferimenti ai segreti vengono risolti al momento dell'attivazione in un'istantanea in memoria, poi i percorsi di richiesta leggono solo l'istantanea. -- Il filtraggio della superficie attiva si applica durante l'attivazione: i riferimenti non risolti sulle superfici abilitate fanno fallire avvio/reload, mentre le superfici inattive vengono saltate con diagnostica. +- Per impostazione predefinita, i percorsi di comando symlink vengono rifiutati. Imposta `allowSymlinkCommand: true` per consentire percorsi symlink convalidando però il percorso del target risolto. +- Se è configurato `trustedDirs`, il controllo della directory attendibile si applica al percorso del target risolto. +- L'ambiente figlio di `exec` è minimo per impostazione predefinita; passa esplicitamente le variabili necessarie con `passEnv`. +- I riferimenti ai segreti vengono risolti al momento dell'attivazione in uno snapshot in memoria, poi i percorsi di richiesta leggono solo dallo snapshot. +- Durante l'attivazione si applica il filtering della superficie attiva: i riferimenti non risolti sulle superfici abilitate fanno fallire avvio/reload, mentre le superfici inattive vengono saltate con diagnostica. --- @@ -3323,13 +3306,13 @@ Note: } ``` -- I profili per agente sono archiviati in `/auth-profiles.json`. -- `auth-profiles.json` supporta riferimenti a livello di valore (`keyRef` per `api_key`, `tokenRef` per `token`) per modalità di credenziali statiche. -- I profili in modalità OAuth (`auth.profiles..mode = "oauth"`) non supportano credenziali di profilo auth basate su SecretRef. -- Le credenziali runtime statiche provengono da istantanee risolte in memoria; le vecchie voci statiche `auth.json` vengono ripulite quando rilevate. -- Importazioni OAuth legacy da `~/.openclaw/credentials/oauth.json`. +- I profili per agente vengono memorizzati in `/auth-profiles.json`. +- `auth-profiles.json` supporta riferimenti a livello di valore (`keyRef` per `api_key`, `tokenRef` per `token`) per le modalità di credenziali statiche. +- I profili in modalità OAuth (`auth.profiles..mode = "oauth"`) non supportano credenziali dell'auth-profile supportate da SecretRef. +- Le credenziali runtime statiche provengono da snapshot risolti in memoria; le voci statiche legacy di `auth.json` vengono ripulite quando trovate. +- Import legacy OAuth da `~/.openclaw/credentials/oauth.json`. - Vedi [OAuth](/it/concepts/oauth). -- Comportamento runtime dei segreti e strumenti `audit/configure/apply`: [Secrets Management](/it/gateway/secrets). +- Comportamento runtime dei segreti e tooling `audit/configure/apply`: [Secrets Management](/it/gateway/secrets). ### `auth.cooldowns` @@ -3351,15 +3334,15 @@ Note: } ``` -- `billingBackoffHours`: backoff di base in ore quando un profilo fallisce per veri errori di fatturazione/credito insufficiente (predefinito: `5`). Testi espliciti di fatturazione possono comunque finire qui anche su risposte `401`/`403`, ma i matcher di testo specifici del provider restano limitati al provider che li possiede (per esempio OpenRouter `Key limit exceeded`). I messaggi `402` ritentabili relativi a finestra d'uso o limiti di spesa di organizzazione/workspace restano invece nel percorso `rate_limit`. -- `billingBackoffHoursByProvider`: override facoltativi per provider delle ore di backoff di fatturazione. +- `billingBackoffHours`: backoff base in ore quando un profilo fallisce a causa di veri errori di fatturazione/credito insufficiente (predefinito: `5`). Testo esplicito di fatturazione può comunque finire qui anche su risposte `401`/`403`, ma i matcher di testo specifici del provider restano limitati al provider che li possiede (ad esempio OpenRouter `Key limit exceeded`). I messaggi HTTP `402` riprovabili relativi a finestra di utilizzo o limiti di spesa di organizzazione/workspace restano invece nel percorso `rate_limit`. +- `billingBackoffHoursByProvider`: override opzionali per provider delle ore di backoff di fatturazione. - `billingMaxHours`: limite massimo in ore per la crescita esponenziale del backoff di fatturazione (predefinito: `24`). -- `authPermanentBackoffMinutes`: backoff di base in minuti per errori `auth_permanent` ad alta confidenza (predefinito: `10`). +- `authPermanentBackoffMinutes`: backoff base in minuti per errori `auth_permanent` ad alta confidenza (predefinito: `10`). - `authPermanentMaxMinutes`: limite massimo in minuti per la crescita del backoff `auth_permanent` (predefinito: `60`). - `failureWindowHours`: finestra mobile in ore usata per i contatori di backoff (predefinito: `24`). -- `overloadedProfileRotations`: massimo numero di rotazioni dello stesso provider auth-profile per errori di sovraccarico prima di passare al fallback del modello (predefinito: `1`). Le forme di provider occupato come `ModelNotReadyException` finiscono qui. -- `overloadedBackoffMs`: ritardo fisso prima di ritentare una rotazione di provider/profilo sovraccarico (predefinito: `0`). -- `rateLimitedProfileRotations`: massimo numero di rotazioni dello stesso provider auth-profile per errori di rate limit prima di passare al fallback del modello (predefinito: `1`). Quel bucket di rate limit include testo tipico del provider come `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` e `resource exhausted`. +- `overloadedProfileRotations`: numero massimo di rotazioni dello stesso auth-profile provider per errori di sovraccarico prima di passare al fallback del modello (predefinito: `1`). Le forme di provider occupato come `ModelNotReadyException` finiscono qui. +- `overloadedBackoffMs`: ritardo fisso prima di ritentare una rotazione provider/profilo sovraccarico (predefinito: `0`). +- `rateLimitedProfileRotations`: numero massimo di rotazioni dello stesso auth-profile provider per errori di rate limit prima di passare al fallback del modello (predefinito: `1`). Quel bucket rate-limit include testo caratteristico del provider come `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` e `resource exhausted`. --- @@ -3381,7 +3364,7 @@ Note: - File di log predefinito: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. - Imposta `logging.file` per un percorso stabile. - `consoleLevel` passa a `debug` con `--verbose`. -- `maxFileBytes`: dimensione massima del file di log in byte prima che le scritture vengano soppresse (intero positivo; predefinito: `524288000` = 500 MB). Usa una rotazione esterna dei log per i deployment di produzione. +- `maxFileBytes`: dimensione massima del file di log in byte prima che le scritture vengano soppresse (intero positivo; predefinito: `524288000` = 500 MB). Usa la rotazione esterna dei log per i deployment di produzione. --- @@ -3419,19 +3402,19 @@ Note: ``` - `enabled`: interruttore principale per l'output di strumentazione (predefinito: `true`). -- `flags`: array di stringhe flag che abilita output di log mirati (supporta wildcard come `"telegram.*"` o `"*"`). +- `flags`: array di stringhe flag che abilita output di log mirato (supporta wildcard come `"telegram.*"` oppure `"*"`). - `stuckSessionWarnMs`: soglia di età in ms per emettere avvisi di sessione bloccata mentre una sessione resta nello stato di elaborazione. - `otel.enabled`: abilita la pipeline di esportazione OpenTelemetry (predefinito: `false`). - `otel.endpoint`: URL del collector per l'esportazione OTel. -- `otel.protocol`: `"http/protobuf"` (predefinito) o `"grpc"`. -- `otel.headers`: header di metadati HTTP/gRPC aggiuntivi inviati con le richieste di esportazione OTel. +- `otel.protocol`: `"http/protobuf"` (predefinito) oppure `"grpc"`. +- `otel.headers`: header metadata HTTP/gRPC extra inviati con le richieste di esportazione OTel. - `otel.serviceName`: nome del servizio per gli attributi della risorsa. -- `otel.traces` / `otel.metrics` / `otel.logs`: abilita l'esportazione di trace, metriche o log. -- `otel.sampleRate`: frequenza di campionamento delle trace `0`–`1`. +- `otel.traces` / `otel.metrics` / `otel.logs`: abilitano l'esportazione di trace, metriche o log. +- `otel.sampleRate`: tasso di campionamento delle trace `0`–`1`. - `otel.flushIntervalMs`: intervallo periodico di flush della telemetria in ms. -- `cacheTrace.enabled`: registra snapshot del trace della cache per esecuzioni incorporate (predefinito: `false`). -- `cacheTrace.filePath`: percorso di output per il JSONL del trace della cache (predefinito: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: controlla cosa è incluso nell'output del trace della cache (tutti predefiniti: `true`). +- `cacheTrace.enabled`: registra snapshot di cache trace per le esecuzioni embedded (predefinito: `false`). +- `cacheTrace.filePath`: percorso di output per il JSONL del cache trace (predefinito: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: controllano cosa viene incluso nell'output del cache trace (tutti predefiniti: `true`). --- @@ -3453,12 +3436,12 @@ Note: } ``` -- `channel`: canale di rilascio per installazioni npm/git — `"stable"`, `"beta"` o `"dev"`. -- `checkOnStart`: verifica aggiornamenti npm all'avvio del gateway (predefinito: `true`). +- `channel`: canale di rilascio per installazioni npm/git — `"stable"`, `"beta"` oppure `"dev"`. +- `checkOnStart`: controlla gli aggiornamenti npm quando il gateway si avvia (predefinito: `true`). - `auto.enabled`: abilita l'aggiornamento automatico in background per le installazioni di pacchetti (predefinito: `false`). -- `auto.stableDelayHours`: ritardo minimo in ore prima dell'applicazione automatica sul canale stable (predefinito: `6`; max: `168`). -- `auto.stableJitterHours`: finestra aggiuntiva di distribuzione graduale del canale stable in ore (predefinito: `12`; max: `168`). -- `auto.betaCheckIntervalHours`: frequenza in ore dei controlli sul canale beta (predefinito: `1`; max: `24`). +- `auto.stableDelayHours`: ritardo minimo in ore prima dell'applicazione automatica sul canale stable (predefinito: `6`; massimo: `168`). +- `auto.stableJitterHours`: finestra extra di distribuzione graduale del rollout sul canale stable in ore (predefinito: `12`; massimo: `168`). +- `auto.betaCheckIntervalHours`: frequenza in ore dei controlli sul canale beta (predefinito: `1`; massimo: `24`). --- @@ -3492,21 +3475,21 @@ Note: ``` - `enabled`: gate globale della funzionalità ACP (predefinito: `false`). -- `dispatch.enabled`: gate indipendente per il dispatch dei turni di sessione ACP (predefinito: `true`). Imposta `false` per mantenere disponibili i comandi ACP bloccandone però l'esecuzione. -- `backend`: id backend runtime ACP predefinito (deve corrispondere a un plugin runtime ACP registrato). -- `defaultAgent`: id agente ACP di fallback quando gli spawn non specificano una destinazione esplicita. -- `allowedAgents`: allowlist di id agente consentiti per le sessioni runtime ACP; vuoto significa nessuna restrizione aggiuntiva. -- `maxConcurrentSessions`: numero massimo di sessioni ACP attive contemporaneamente. -- `stream.coalesceIdleMs`: finestra di flush per inattività in ms per il testo in streaming. -- `stream.maxChunkChars`: dimensione massima del blocco prima della suddivisione della proiezione dei blocchi in streaming. -- `stream.repeatSuppression`: sopprime righe di stato/strumenti ripetute per turno (predefinito: `true`). -- `stream.deliveryMode`: `"live"` trasmette incrementalmente; `"final_only"` bufferizza fino agli eventi terminali del turno. +- `dispatch.enabled`: gate indipendente per il dispatch dei turni di sessione ACP (predefinito: `true`). Imposta `false` per mantenere disponibili i comandi ACP bloccando però l'esecuzione. +- `backend`: id del backend runtime ACP predefinito (deve corrispondere a un plugin runtime ACP registrato). +- `defaultAgent`: id agente ACP di fallback quando gli spawn non specificano un target esplicito. +- `allowedAgents`: allowlist di ID agente consentiti per le sessioni runtime ACP; vuoto significa nessuna restrizione aggiuntiva. +- `maxConcurrentSessions`: numero massimo di sessioni ACP contemporaneamente attive. +- `stream.coalesceIdleMs`: finestra di flush inattivo in ms per il testo in streaming. +- `stream.maxChunkChars`: dimensione massima del chunk prima della suddivisione della proiezione del blocco in streaming. +- `stream.repeatSuppression`: sopprime per turno le righe ripetute di stato/strumento (predefinito: `true`). +- `stream.deliveryMode`: `"live"` esegue lo streaming incrementale; `"final_only"` effettua il buffering fino agli eventi terminali del turno. - `stream.hiddenBoundarySeparator`: separatore prima del testo visibile dopo eventi di strumenti nascosti (predefinito: `"paragraph"`). - `stream.maxOutputChars`: numero massimo di caratteri di output dell'assistente proiettati per turno ACP. -- `stream.maxSessionUpdateChars`: numero massimo di caratteri per righe di stato/aggiornamento ACP proiettate. -- `stream.tagVisibility`: record dei nomi dei tag con override booleani di visibilità per eventi in streaming. -- `runtime.ttlMinutes`: TTL di inattività in minuti per i worker di sessione ACP prima che possano essere ripuliti. -- `runtime.installCommand`: comando di installazione facoltativo da eseguire durante il bootstrap di un ambiente runtime ACP. +- `stream.maxSessionUpdateChars`: numero massimo di caratteri per le righe proiettate di stato/aggiornamento ACP. +- `stream.tagVisibility`: record dei nomi dei tag con override booleani di visibilità per gli eventi in streaming. +- `runtime.ttlMinutes`: TTL di inattività in minuti per i worker di sessione ACP prima che siano idonei alla pulizia. +- `runtime.installCommand`: comando di installazione opzionale da eseguire durante il bootstrap di un ambiente runtime ACP. --- @@ -3523,8 +3506,8 @@ Note: ``` - `cli.banner.taglineMode` controlla lo stile del tagline del banner: - - `"random"` (predefinito): tagline a rotazione divertenti/stagionali. - - `"default"`: tagline neutro fisso (`All your chats, one OpenClaw.`). + - `"random"` (predefinito): tagline rotanti divertenti/stagionali. + - `"default"`: tagline neutrale fissa (`Tutte le tue chat, un solo OpenClaw.`). - `"off"`: nessun testo tagline (titolo/versione del banner ancora mostrati). - Per nascondere l'intero banner (non solo i tagline), imposta la variabile env `OPENCLAW_HIDE_BANNER=1`. @@ -3548,15 +3531,15 @@ Metadati scritti dai flussi di configurazione guidata della CLI (`onboard`, `con --- -## Identità +## Identity -Vedi i campi identity di `agents.list` in [Valori predefiniti dell'agente](#agent-defaults). +Vedi i campi identity di `agents.list` sotto [Valori predefiniti dell'agente](#agent-defaults). --- ## Bridge (legacy, rimosso) -Le build correnti non includono più il bridge TCP. I node si connettono tramite il Gateway WebSocket. Le chiavi `bridge.*` non fanno più parte dello schema di configurazione (la convalida fallisce finché non vengono rimosse; `openclaw doctor --fix` può eliminare le chiavi sconosciute). +Le build attuali non includono più il bridge TCP. I Node si connettono tramite il WebSocket del Gateway. Le chiavi `bridge.*` non fanno più parte dello schema di configurazione (la convalida fallisce finché non vengono rimosse; `openclaw doctor --fix` può eliminare le chiavi sconosciute). @@ -3585,9 +3568,9 @@ Le build correnti non includono più il bridge TCP. I node si connettono tramite cron: { enabled: true, maxConcurrentRuns: 2, - webhook: "https://example.invalid/legacy", // fallback deprecato per job archiviati con notify:true - webhookToken: "replace-with-dedicated-token", // token bearer facoltativo per l'autenticazione webhook in uscita - sessionRetention: "24h", // stringa di durata oppure false + webhook: "https://example.invalid/legacy", // fallback deprecato per i job memorizzati notify:true + webhookToken: "replace-with-dedicated-token", // token bearer opzionale per l'autenticazione webhook in uscita + sessionRetention: "24h", // stringa durata oppure false runLog: { maxBytes: "2mb", // predefinito 2_000_000 byte keepLines: 2000, // predefinito 2000 @@ -3596,11 +3579,11 @@ Le build correnti non includono più il bridge TCP. I node si connettono tramite } ``` -- `sessionRetention`: per quanto tempo mantenere le sessioni completate delle esecuzioni cron isolate prima di eliminarle da `sessions.json`. Controlla anche la pulizia delle trascrizioni cron eliminate archiviate. Predefinito: `24h`; imposta `false` per disabilitare. +- `sessionRetention`: per quanto tempo mantenere le sessioni completate delle esecuzioni Cron isolate prima della rimozione da `sessions.json`. Controlla anche la pulizia dei transcript Cron eliminati archiviati. Predefinito: `24h`; imposta `false` per disabilitare. - `runLog.maxBytes`: dimensione massima per file di log di esecuzione (`cron/runs/.jsonl`) prima della pulizia. Predefinito: `2_000_000` byte. - `runLog.keepLines`: righe più recenti conservate quando viene attivata la pulizia del log di esecuzione. Predefinito: `2000`. -- `webhookToken`: token bearer usato per la consegna POST del webhook cron (`delivery.mode = "webhook"`); se omesso non viene inviato alcun header auth. -- `webhook`: URL webhook legacy deprecato di fallback (http/https) usato solo per i job archiviati che hanno ancora `notify: true`. +- `webhookToken`: token bearer usato per la consegna POST del webhook Cron (`delivery.mode = "webhook"`); se omesso non viene inviato alcun header di autenticazione. +- `webhook`: URL webhook legacy deprecato di fallback (http/https) usato solo per i job memorizzati che hanno ancora `notify: true`. ### `cron.retry` @@ -3616,11 +3599,11 @@ Le build correnti non includono più il bridge TCP. I node si connettono tramite } ``` -- `maxAttempts`: numero massimo di tentativi per job one-shot in caso di errori transitori (predefinito: `3`; intervallo: `0`–`10`). +- `maxAttempts`: numero massimo di retry per i job one-shot in caso di errori transitori (predefinito: `3`; intervallo: `0`–`10`). - `backoffMs`: array di ritardi di backoff in ms per ogni tentativo di retry (predefinito: `[30000, 60000, 300000]`; 1–10 voci). - `retryOn`: tipi di errore che attivano i retry — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Ometti per ritentare tutti i tipi transitori. -Si applica solo ai job cron one-shot. I job ricorrenti usano una gestione degli errori separata. +Si applica solo ai job Cron one-shot. I job ricorrenti usano una gestione dei fallimenti separata. ### `cron.failureAlert` @@ -3638,11 +3621,11 @@ Si applica solo ai job cron one-shot. I job ricorrenti usano una gestione degli } ``` -- `enabled`: abilita gli avvisi di errore per i job cron (predefinito: `false`). -- `after`: errori consecutivi prima che venga attivato un avviso (intero positivo, min: `1`). +- `enabled`: abilita gli avvisi di errore per i job Cron (predefinito: `false`). +- `after`: numero di errori consecutivi prima che venga inviato un avviso (intero positivo, minimo: `1`). - `cooldownMs`: millisecondi minimi tra avvisi ripetuti per lo stesso job (intero non negativo). - `mode`: modalità di consegna — `"announce"` invia tramite un messaggio di canale; `"webhook"` pubblica sul webhook configurato. -- `accountId`: id account o canale facoltativo per definire l'ambito della consegna dell'avviso. +- `accountId`: ID account o canale opzionale per limitare la consegna dell'avviso. ### `cron.failureDestination` @@ -3659,51 +3642,51 @@ Si applica solo ai job cron one-shot. I job ricorrenti usano una gestione degli } ``` -- Destinazione predefinita per le notifiche di errore cron per tutti i job. -- `mode`: `"announce"` o `"webhook"`; usa come predefinito `"announce"` quando esistono dati di destinazione sufficienti. -- `channel`: override del canale per la consegna announce. `"last"` riutilizza l'ultimo canale di consegna noto. -- `to`: destinazione announce esplicita o URL webhook. Obbligatorio per la modalità webhook. -- `accountId`: override facoltativo dell'account per la consegna. -- `delivery.failureDestination` per job sostituisce questo valore predefinito globale. -- Quando non è impostata né una destinazione di errore globale né una per job, i job che già consegnano tramite `announce` usano come fallback quella destinazione announce primaria in caso di errore. -- `delivery.failureDestination` è supportato solo per job `sessionTarget="isolated"` a meno che `delivery.mode` primario del job non sia `"webhook"`. +- Destinazione predefinita per le notifiche di errore Cron per tutti i job. +- `mode`: `"announce"` oppure `"webhook"`; il valore predefinito è `"announce"` quando esistono dati target sufficienti. +- `channel`: override del canale per la consegna announce. `"last"` riusa l'ultimo canale di consegna noto. +- `to`: target announce esplicito o URL webhook. Obbligatorio per la modalità webhook. +- `accountId`: override opzionale dell'account per la consegna. +- `delivery.failureDestination` per job sovrascrive questo valore predefinito globale. +- Quando non è impostata né una destinazione di errore globale né per job, i job che consegnano già tramite `announce` usano come fallback quel target announce primario in caso di errore. +- `delivery.failureDestination` è supportato solo per i job `sessionTarget="isolated"` a meno che il `delivery.mode` primario del job non sia `"webhook"`. -Vedi [Cron Jobs](/it/automation/cron-jobs). Le esecuzioni cron isolate sono tracciate come [background tasks](/it/automation/tasks). +Vedi [Cron Jobs](/it/automation/cron-jobs). Le esecuzioni Cron isolate vengono tracciate come [task in background](/it/automation/tasks). --- ## Variabili template del modello media -Segnaposto del template espansi in `tools.media.models[].args`: +Segnaposto template espansi in `tools.media.models[].args`: -| Variabile | Descrizione | -| ------------------ | ------------------------------------------------ | -| `{{Body}}` | Corpo completo del messaggio in ingresso | -| `{{RawBody}}` | Corpo grezzo (senza wrapper cronologia/mittente) | -| `{{BodyStripped}}` | Corpo con le menzioni di gruppo rimosse | -| `{{From}}` | Identificatore del mittente | -| `{{To}}` | Identificatore della destinazione | -| `{{MessageSid}}` | ID del messaggio del canale | -| `{{SessionId}}` | UUID della sessione corrente | -| `{{IsNewSession}}` | `"true"` quando viene creata una nuova sessione | -| `{{MediaUrl}}` | pseudo-URL del media in ingresso | -| `{{MediaPath}}` | percorso locale del media | -| `{{MediaType}}` | tipo di media (image/audio/document/…) | -| `{{Transcript}}` | trascrizione audio | -| `{{Prompt}}` | prompt media risolto per le voci CLI | -| `{{MaxChars}}` | max caratteri di output risolti per le voci CLI | -| `{{ChatType}}` | `"direct"` o `"group"` | -| `{{GroupSubject}}` | oggetto del gruppo (best effort) | -| `{{GroupMembers}}` | anteprima dei membri del gruppo (best effort) | -| `{{SenderName}}` | nome visualizzato del mittente (best effort) | -| `{{SenderE164}}` | numero di telefono del mittente (best effort) | +| Variabile | Descrizione | +| ------------------ | ----------------------------------------------- | +| `{{Body}}` | Corpo completo del messaggio in ingresso | +| `{{RawBody}}` | Corpo raw (senza wrapper di cronologia/mittente) | +| `{{BodyStripped}}` | Corpo con le menzioni di gruppo rimosse | +| `{{From}}` | Identificatore del mittente | +| `{{To}}` | Identificatore della destinazione | +| `{{MessageSid}}` | ID del messaggio del canale | +| `{{SessionId}}` | UUID della sessione corrente | +| `{{IsNewSession}}` | `"true"` quando viene creata una nuova sessione | +| `{{MediaUrl}}` | pseudo-URL del media in ingresso | +| `{{MediaPath}}` | percorso locale del media | +| `{{MediaType}}` | tipo di media (image/audio/document/…) | +| `{{Transcript}}` | trascrizione audio | +| `{{Prompt}}` | prompt media risolto per le voci CLI | +| `{{MaxChars}}` | caratteri massimi di output risolti per le voci CLI | +| `{{ChatType}}` | `"direct"` oppure `"group"` | +| `{{GroupSubject}}` | oggetto del gruppo (best effort) | +| `{{GroupMembers}}` | anteprima dei membri del gruppo (best effort) | +| `{{SenderName}}` | nome visualizzato del mittente (best effort) | +| `{{SenderE164}}` | numero di telefono del mittente (best effort) | | `{{Provider}}` | suggerimento provider (whatsapp, telegram, discord, ecc.) | --- ## Include di configurazione (`$include`) -Suddividi la configurazione in più file: +Dividi la configurazione in più file: ```json5 // ~/.openclaw/openclaw.json @@ -3719,10 +3702,10 @@ Suddividi la configurazione in più file: **Comportamento di merge:** - File singolo: sostituisce l'oggetto contenitore. -- Array di file: merge profondo in ordine (gli ultimi sostituiscono i precedenti). -- Chiavi sibling: unite dopo gli include (sostituiscono i valori inclusi). -- Include nidificati: fino a 10 livelli di profondità. -- Percorsi: risolti relativamente al file che include, ma devono restare all'interno della directory di configurazione di livello superiore (`dirname` di `openclaw.json`). Le forme assolute/`../` sono consentite solo se si risolvono comunque entro quel confine. +- Array di file: deep-merge in ordine (gli ultimi sovrascrivono i precedenti). +- Chiavi sibling: unite dopo gli include (sovrascrivono i valori inclusi). +- Include annidati: fino a 10 livelli di profondità. +- Percorsi: risolti relativamente al file che include, ma devono restare all'interno della directory di configurazione di primo livello (`dirname` di `openclaw.json`). Le forme assolute/`../` sono consentite solo quando si risolvono comunque all'interno di quel limite. - Errori: messaggi chiari per file mancanti, errori di parsing e include circolari. --- diff --git a/docs/it/gateway/local-models.md b/docs/it/gateway/local-models.md index d7bc37757..be2ee1ba8 100644 --- a/docs/it/gateway/local-models.md +++ b/docs/it/gateway/local-models.md @@ -1,28 +1,28 @@ --- read_when: - - Vuoi servire modelli dal tuo server GPU personale + - Vuoi servire modelli dal tuo box GPU personale - Stai configurando LM Studio o un proxy compatibile con OpenAI - Hai bisogno della guida più sicura per i modelli locali summary: Esegui OpenClaw su LLM locali (LM Studio, vLLM, LiteLLM, endpoint OpenAI personalizzati) title: Modelli locali x-i18n: - generated_at: "2026-04-15T08:18:07Z" + generated_at: "2026-04-15T14:40:34Z" model: gpt-5.4 provider: openai - source_hash: 8778cc1c623a356ff3cf306c494c046887f9417a70ec71e659e4a8aae912a780 + source_hash: 7a506ff83e4c2870d3878339f646c906584454a156ecd618c360f592cf3b0011 source_path: gateway/local-models.md workflow: 15 --- # Modelli locali -Usare modelli locali è fattibile, ma OpenClaw si aspetta un contesto ampio e difese solide contro la prompt injection. Le schede più piccole troncano il contesto e indeboliscono la sicurezza. Punta in alto: **≥2 Mac Studio al massimo della configurazione o una workstation GPU equivalente (~$30k+)**. Una singola GPU da **24 GB** funziona solo per prompt più leggeri con latenza più alta. Usa la **variante di modello più grande / full-size che riesci a eseguire**; checkpoint fortemente quantizzati o “small” aumentano il rischio di prompt injection (vedi [Sicurezza](/it/gateway/security)). +Il locale è fattibile, ma OpenClaw si aspetta un contesto ampio e difese robuste contro il prompt injection. Le schede piccole troncano il contesto e indeboliscono la sicurezza. Punta in alto: **≥2 Mac Studio al massimo della configurazione o un rig GPU equivalente (~$30k+)**. Una singola GPU da **24 GB** funziona solo con prompt più leggeri e con latenza più alta. Usa la **variante di modello più grande / full-size che riesci a eseguire**; i checkpoint fortemente quantizzati o “small” aumentano il rischio di prompt injection (vedi [Sicurezza](/it/gateway/security)). -Se vuoi la configurazione locale con meno attrito, inizia con [LM Studio](/it/providers/lmstudio) o [Ollama](/it/providers/ollama) e `openclaw onboard`. Questa pagina è la guida con indicazioni precise per stack locali di fascia alta e server locali personalizzati compatibili con OpenAI. +Se vuoi la configurazione locale con meno attrito, inizia con [LM Studio](/it/providers/lmstudio) o [Ollama](/it/providers/ollama) e `openclaw onboard`. Questa pagina è la guida con indicazioni precise per stack locali di fascia più alta e server locali personalizzati compatibili con OpenAI. -## Consigliato: LM Studio + modello locale grande (API Responses) +## Consigliato: LM Studio + modello locale grande (Responses API) -Il miglior stack locale attuale. Carica un modello grande in LM Studio (per esempio, una build full-size di Qwen, DeepSeek o Llama), abilita il server locale (predefinito `http://127.0.0.1:1234`) e usa l'API Responses per mantenere il ragionamento separato dal testo finale. +Il miglior stack locale attuale. Carica un modello grande in LM Studio (per esempio, una build full-size di Qwen, DeepSeek o Llama), abilita il server locale (predefinito `http://127.0.0.1:1234`) e usa la Responses API per mantenere separato il ragionamento dal testo finale. ```json5 { @@ -62,13 +62,13 @@ Il miglior stack locale attuale. Carica un modello grande in LM Studio (per esem **Checklist di configurazione** - Installa LM Studio: [https://lmstudio.ai](https://lmstudio.ai) -- In LM Studio, scarica la **build del modello più grande disponibile** (evita varianti “small”/fortemente quantizzate), avvia il server e conferma che `http://127.0.0.1:1234/v1/models` lo elenchi. -- Sostituisci `my-local-model` con l'ID effettivo del modello mostrato in LM Studio. +- In LM Studio, scarica la **build di modello più grande disponibile** (evita le varianti “small”/fortemente quantizzate), avvia il server e conferma che `http://127.0.0.1:1234/v1/models` lo elenchi. +- Sostituisci `my-local-model` con l'ID modello effettivo mostrato in LM Studio. - Mantieni il modello caricato; il caricamento a freddo aggiunge latenza di avvio. - Regola `contextWindow`/`maxTokens` se la tua build di LM Studio è diversa. -- Per WhatsApp, resta sull'API Responses così viene inviato solo il testo finale. +- Per WhatsApp, usa la Responses API così viene inviato solo il testo finale. -Mantieni configurati anche i modelli ospitati anche quando esegui modelli locali; usa `models.mode: "merge"` così i fallback restano disponibili. +Mantieni configurati anche i modelli ospitati quando esegui in locale; usa `models.mode: "merge"` così i fallback restano disponibili. ### Configurazione ibrida: primario ospitato, fallback locale @@ -113,16 +113,16 @@ Mantieni configurati anche i modelli ospitati anche quando esegui modelli locali ### Priorità al locale con rete di sicurezza ospitata -Inverti l'ordine di primario e fallback; mantieni lo stesso blocco `providers` e `models.mode: "merge"` così puoi ripiegare su Sonnet o Opus quando il sistema locale non è disponibile. +Inverti l'ordine tra primario e fallback; mantieni lo stesso blocco providers e `models.mode: "merge"` così puoi ripiegare su Sonnet o Opus quando il box locale non è disponibile. ### Hosting regionale / instradamento dei dati -- Varianti ospitate di MiniMax/Kimi/GLM esistono anche su OpenRouter con endpoint vincolati alla regione (ad esempio ospitati negli Stati Uniti). Scegli lì la variante regionale per mantenere il traffico nella giurisdizione scelta continuando a usare `models.mode: "merge"` per i fallback Anthropic/OpenAI. -- Solo locale resta il percorso più forte per la privacy; l'instradamento regionale ospitato è il compromesso intermedio quando ti servono funzionalità del provider ma vuoi controllare il flusso dei dati. +- Esistono anche varianti MiniMax/Kimi/GLM ospitate su OpenRouter con endpoint vincolati per regione (per esempio, ospitati negli Stati Uniti). Scegli lì la variante regionale per mantenere il traffico nella giurisdizione desiderata, continuando a usare `models.mode: "merge"` per i fallback Anthropic/OpenAI. +- Il solo locale resta la strada migliore per la privacy; l'instradamento regionale ospitato è la via di mezzo quando hai bisogno delle funzionalità del provider ma vuoi controllare il flusso dei dati. ## Altri proxy locali compatibili con OpenAI -vLLM, LiteLLM, OAI-proxy o gateway personalizzati funzionano se espongono un endpoint `/v1` in stile OpenAI. Sostituisci il blocco provider sopra con il tuo endpoint e l'ID del modello: +vLLM, LiteLLM, OAI-proxy o Gateway personalizzati funzionano se espongono un endpoint `/v1` in stile OpenAI. Sostituisci il blocco provider sopra con il tuo endpoint e l'ID del modello: ```json5 { @@ -152,41 +152,28 @@ vLLM, LiteLLM, OAI-proxy o gateway personalizzati funzionano se espongono un end Mantieni `models.mode: "merge"` così i modelli ospitati restano disponibili come fallback. -Nota sul comportamento per backend locali/proxati `/v1`: +Nota di comportamento per i backend locali/proxati `/v1`: -- OpenClaw li tratta come route proxy in stile OpenAI compatibili, non come endpoint OpenAI nativi -- il formato delle richieste riservato a OpenAI nativo non si applica qui: niente - `service_tier`, niente `store` di Responses, niente formattazione del payload di compatibilità del ragionamento OpenAI - e nessun suggerimento per la cache del prompt -- gli header nascosti di attribuzione di OpenClaw (`originator`, `version`, `User-Agent`) - non vengono iniettati su questi URL proxy personalizzati +- OpenClaw li tratta come route proxy in stile OpenAI-compatible, non come endpoint OpenAI nativi +- il model shaping delle richieste riservato a OpenAI nativo non si applica qui: niente `service_tier`, niente `store` della Responses API, niente shaping del payload di compatibilità per il ragionamento OpenAI e nessun suggerimento di prompt-cache +- gli header nascosti di attribuzione OpenClaw (`originator`, `version`, `User-Agent`) non vengono inseriti su questi URL proxy personalizzati -Note di compatibilità per backend compatibili con OpenAI più rigidi: +Note di compatibilità per backend compatibili con OpenAI più restrittivi: -- Alcuni server accettano solo `messages[].content` come stringa su Chat Completions, non - array strutturati di parti di contenuto. Imposta - `models.providers..models[].compat.requiresStringContent: true` per - quegli endpoint. -- Alcuni backend locali più piccoli o più rigidi sono instabili con la forma completa - del prompt del runtime agente di OpenClaw, specialmente quando sono inclusi gli schema degli strumenti. Se il - backend funziona per piccole chiamate dirette a `/v1/chat/completions` ma fallisce nei normali - turni agente di OpenClaw, prova prima - `agents.defaults.localModelMode: "lean"` per rimuovere gli strumenti predefiniti più pesanti - come `browser`, `cron` e `message`; se ancora non funziona, prova - `models.providers..models[].compat.supportsTools: false`. -- Se il backend continua a fallire solo in esecuzioni OpenClaw più grandi, il problema restante - di solito è la capacità del modello/server a monte o un bug del backend, non il layer di trasporto di OpenClaw. +- Alcuni server accettano solo `messages[].content` come stringa nelle Chat Completions, non array strutturati di content-part. Imposta `models.providers..models[].compat.requiresStringContent: true` per quegli endpoint. +- Alcuni backend locali più piccoli o più rigidi sono instabili con la forma completa del prompt del runtime agente di OpenClaw, specialmente quando sono inclusi gli schemi degli strumenti. Se il backend funziona per chiamate dirette minime a `/v1/chat/completions` ma fallisce nei normali turni agente di OpenClaw, prova prima `agents.defaults.experimental.localModelLean: true` per rimuovere strumenti predefiniti pesanti come `browser`, `cron` e `message`; questo è un flag sperimentale, non un'impostazione stabile della modalità predefinita. Vedi [Funzionalità sperimentali](/it/concepts/experimental-features). Se ancora non basta, prova `models.providers..models[].compat.supportsTools: false`. +- Se il backend continua a fallire solo nelle esecuzioni OpenClaw più grandi, il problema residuo di solito è la capacità del modello/server a monte o un bug del backend, non il livello di trasporto di OpenClaw. ## Risoluzione dei problemi - Il Gateway riesce a raggiungere il proxy? `curl http://127.0.0.1:1234/v1/models`. - Il modello LM Studio è stato scaricato dalla memoria? Ricaricalo; l'avvio a freddo è una causa comune di “blocco”. -- OpenClaw avvisa quando la finestra di contesto rilevata è sotto **32k** e blocca sotto **16k**. Se incontri quel controllo preliminare, aumenta il limite di contesto del server/modello o scegli un modello più grande. -- Errori di contesto? Riduci `contextWindow` o aumenta il limite del tuo server. +- OpenClaw avvisa quando la finestra di contesto rilevata è sotto **32k** e blocca sotto **16k**. Se incontri questo controllo preliminare, aumenta il limite di contesto del server/modello o scegli un modello più grande. +- Errori di contesto? Riduci `contextWindow` o aumenta il limite del server. - Il server compatibile con OpenAI restituisce `messages[].content ... expected a string`? - Aggiungi `compat.requiresStringContent: true` in quella voce del modello. -- Piccole chiamate dirette a `/v1/chat/completions` funzionano, ma `openclaw infer model run` - fallisce con Gemma o un altro modello locale? Disabilita prima gli schema degli strumenti con + Aggiungi `compat.requiresStringContent: true` a quella voce del modello. +- Le chiamate dirette minime a `/v1/chat/completions` funzionano, ma `openclaw infer model run` + fallisce con Gemma o un altro modello locale? Disabilita prima gli schemi degli strumenti con `compat.supportsTools: false`, poi riprova. Se il server continua a bloccarsi solo - con prompt OpenClaw più grandi, trattalo come un limite del modello/server a monte. -- Sicurezza: i modelli locali saltano i filtri lato provider; mantieni gli agenti limitati e Compaction attivo per ridurre il raggio d'azione della prompt injection. + con prompt OpenClaw più grandi, trattalo come un limite del server/modello a monte. +- Sicurezza: i modelli locali saltano i filtri lato provider; mantieni gli agenti ristretti e Compaction attivo per limitare l'impatto del prompt injection. diff --git a/docs/it/help/testing.md b/docs/it/help/testing.md index 0b11f5b6f..d71d222db 100644 --- a/docs/it/help/testing.md +++ b/docs/it/help/testing.md @@ -1,15 +1,15 @@ --- read_when: - - Eseguire i test localmente o in CI - - Aggiungere regressioni per bug di modello/provider - - Debug del comportamento di Gateway + agente -summary: 'Kit di test: suite unit/e2e/live, runner Docker e cosa copre ogni test' -title: Test + - Eseguire i test in locale o in CI + - Aggiungere test di regressione per bug del modello/provider + - Debug del comportamento di Gateway + agent +summary: 'Kit di test: suite unit/e2e/live, runner Docker e cosa copre ciascun test' +title: Test in corso x-i18n: - generated_at: "2026-04-15T08:18:06Z" + generated_at: "2026-04-15T14:40:32Z" model: gpt-5.4 provider: openai - source_hash: fbf647a5cf13b5861a3ba0cb367dc816c57f0e9c60d3cd6320da193bfadf5609 + source_hash: ec3632cafa1f38b27510372391b84af744266df96c58f7fac98aa03763465db8 source_path: help/testing.md workflow: 15 --- @@ -18,110 +18,110 @@ x-i18n: OpenClaw ha tre suite Vitest (unit/integration, e2e, live) e un piccolo insieme di runner Docker. -Questo documento è una guida su “come testiamo”: +Questa documentazione è una guida a “come testiamo”: -- Cosa copre ogni suite (e cosa deliberatamente _non_ copre) +- Cosa copre ciascuna suite (e cosa deliberatamente _non_ copre) - Quali comandi eseguire per i flussi di lavoro comuni (locale, pre-push, debug) -- Come i test live individuano le credenziali e selezionano modelli/provider +- Come i test live rilevano le credenziali e selezionano modelli/provider - Come aggiungere regressioni per problemi reali di modelli/provider ## Avvio rapido -La maggior parte dei giorni: +Nella maggior parte dei giorni: - Gate completo (atteso prima del push): `pnpm build && pnpm check && pnpm test` -- Esecuzione locale più rapida dell’intera suite su una macchina capiente: `pnpm test:max` -- Loop di watch diretto di Vitest: `pnpm test:watch` -- Il targeting diretto dei file ora instrada anche i percorsi di extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Quando stai iterando su un singolo errore, preferisci prima esecuzioni mirate. +- Esecuzione completa più veloce della suite in locale su una macchina capiente: `pnpm test:max` +- Loop watch diretto di Vitest: `pnpm test:watch` +- Il targeting diretto dei file ora instrada anche i percorsi extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Preferisci prima esecuzioni mirate quando stai iterando su un singolo errore. - Sito QA supportato da Docker: `pnpm qa:lab:up` -- Lane QA supportata da VM Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- Corsia QA supportata da VM Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Quando tocchi i test o vuoi più sicurezza: +Quando tocchi i test o vuoi maggiore confidenza: -- Gate di copertura: `pnpm test:coverage` +- Gate di coverage: `pnpm test:coverage` - Suite E2E: `pnpm test:e2e` Quando esegui il debug di provider/modelli reali (richiede credenziali reali): -- Suite live (modelli + probe di tool/immagini Gateway): `pnpm test:live` -- Esegui in modo silenzioso un singolo file live: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Suite live (probe di modelli + Gateway tool/image): `pnpm test:live` +- Punta a un singolo file live in modo silenzioso: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Suggerimento: quando ti serve solo un caso che fallisce, preferisci restringere i test live tramite le variabili env di allowlist descritte sotto. +Suggerimento: quando ti serve solo un caso in errore, preferisci restringere i test live tramite le variabili d’ambiente allowlist descritte di seguito. -## Runner specifici per QA +## Runner specifici QA -Questi comandi si affiancano alle suite di test principali quando ti serve il realismo di qa-lab: +Questi comandi si affiancano alle suite di test principali quando hai bisogno del realismo di qa-lab: - `pnpm openclaw qa suite` - - Esegue direttamente sull’host gli scenari QA supportati dal repository. - - Per impostazione predefinita esegue in parallelo più scenari selezionati con worker Gateway isolati, fino a 64 worker o al numero di scenari selezionati. Usa `--concurrency ` per regolare il numero di worker, oppure `--concurrency 1` per la vecchia lane seriale. + - Esegue direttamente sull’host scenari QA supportati dal repo. + - Per impostazione predefinita esegue in parallelo più scenari selezionati con worker Gateway isolati, fino a 64 worker o al numero di scenari selezionati. Usa `--concurrency ` per regolare il numero di worker, oppure `--concurrency 1` per la vecchia corsia seriale. - `pnpm openclaw qa suite --runner multipass` - Esegue la stessa suite QA dentro una VM Linux Multipass usa e getta. - Mantiene lo stesso comportamento di selezione degli scenari di `qa suite` sull’host. - Riutilizza gli stessi flag di selezione provider/modello di `qa suite`. - - Le esecuzioni live inoltrano gli input di autenticazione QA supportati e pratici per il guest: chiavi provider basate su env, il percorso di configurazione del provider live QA e `CODEX_HOME` quando presente. - - Le directory di output devono restare sotto la root del repository in modo che il guest possa scrivere di nuovo tramite il workspace montato. - - Scrive il normale report + riepilogo QA e i log Multipass sotto `.artifacts/qa-e2e/...`. + - Le esecuzioni live inoltrano gli input di autenticazione QA supportati che sono pratici per il guest: chiavi provider basate su env, il percorso della configurazione provider live QA e `CODEX_HOME` quando presente. + - Le directory di output devono restare sotto la root del repo affinché il guest possa scrivere indietro tramite il workspace montato. + - Scrive il normale report + riepilogo QA più i log Multipass sotto `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Avvia il sito QA supportato da Docker per attività QA in stile operatore. + - Avvia il sito QA supportato da Docker per lavoro QA in stile operatore. - `pnpm openclaw qa matrix` - - Esegue la lane QA live Matrix contro un homeserver Tuwunel usa e getta supportato da Docker. - - Questo host QA oggi è solo per repo/dev. Le installazioni OpenClaw pacchettizzate non includono `qa-lab`, quindi non espongono `openclaw qa`. - - I checkout del repository caricano direttamente il runner incluso; non è necessario alcun passaggio separato di installazione del plugin. - - Effettua il provisioning di tre utenti Matrix temporanei (`driver`, `sut`, `observer`) più una stanza privata, poi avvia un processo figlio QA gateway con il vero plugin Matrix come trasporto SUT. - - Usa per impostazione predefinita l’immagine Tuwunel stabile fissata `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Sostituiscila con `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` quando devi testare un’immagine diversa. - - Matrix non espone flag condivisi per la fonte delle credenziali perché la lane effettua localmente il provisioning di utenti usa e getta. - - Scrive un report QA Matrix, un riepilogo e un artifact observed-events sotto `.artifacts/qa-e2e/...`. + - Esegue la corsia QA live Matrix contro un homeserver Tuwunel usa e getta supportato da Docker. + - Questo host QA oggi è solo per repo/dev. Le installazioni OpenClaw pacchettizzate non distribuiscono `qa-lab`, quindi non espongono `openclaw qa`. + - I checkout del repo caricano direttamente il runner incluso; non è necessario alcun passaggio separato di installazione del plugin. + - Effettua il provisioning di tre utenti Matrix temporanei (`driver`, `sut`, `observer`) più una stanza privata, poi avvia un processo figlio QA Gateway con il vero plugin Matrix come trasporto del SUT. + - Usa per impostazione predefinita l’immagine Tuwunel stable fissata `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Sostituiscila con `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` quando devi testare un’immagine diversa. + - Matrix non espone flag condivisi per la sorgente credenziali perché la corsia effettua il provisioning locale di utenti usa e getta. + - Scrive un report QA Matrix, un riepilogo e un artifact degli eventi osservati sotto `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Esegue la lane QA live Telegram contro un gruppo privato reale usando i token bot driver e SUT dall’env. + - Esegue la corsia QA live Telegram contro un gruppo privato reale usando i token bot del driver e del SUT da env. - Richiede `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` e `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. L’id del gruppo deve essere l’id numerico della chat Telegram. - - Supporta `--credential-source convex` per credenziali condivise in pool. Usa per impostazione predefinita la modalità env, oppure imposta `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` per attivare i lease condivisi. - - Richiede due bot distinti nello stesso gruppo privato, con il bot SUT che espone un username Telegram. - - Per un’osservazione stabile bot-to-bot, abilita la modalità Bot-to-Bot Communication in `@BotFather` per entrambi i bot e assicurati che il bot driver possa osservare il traffico dei bot del gruppo. - - Scrive un report QA Telegram, un riepilogo e un artifact observed-messages sotto `.artifacts/qa-e2e/...`. + - Supporta `--credential-source convex` per credenziali condivise in pool. Usa per impostazione predefinita la modalità env, oppure imposta `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` per scegliere lease condivisi. + - Richiede due bot distinti nello stesso gruppo privato, con il bot SUT che espone uno username Telegram. + - Per un’osservazione bot-to-bot stabile, abilita la Modalità di comunicazione Bot-to-Bot in `@BotFather` per entrambi i bot e assicurati che il bot driver possa osservare il traffico dei bot nel gruppo. + - Scrive un report QA Telegram, un riepilogo e un artifact dei messaggi osservati sotto `.artifacts/qa-e2e/...`. -Le lane live di trasporto condividono un unico contratto standard così i nuovi trasporti non divergono: +Le corsie live di trasporto condividono un unico contratto standard, così i nuovi trasporti non divergono: -`qa-channel` resta la suite QA sintetica ampia e non fa parte della matrice di copertura del trasporto live. +`qa-channel` resta la suite QA sintetica ampia e non fa parte della matrice di copertura dei trasporti live. -| Lane | Canary | Mention gating | Blocco allowlist | Risposta di primo livello | Ripresa dopo riavvio | Follow-up nel thread | Isolamento del thread | Osservazione delle reazioni | Comando help | -| -------- | ------ | -------------- | ---------------- | ------------------------- | -------------------- | ------------------- | -------------------- | --------------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Corsia | Canary | Gating delle mention | Blocco allowlist | Risposta di primo livello | Ripresa dopo riavvio | Follow-up nel thread | Isolamento del thread | Osservazione delle reaction | Comando help | +| -------- | ------ | -------------------- | ---------------- | ------------------------- | ------------------- | ------------------- | -------------------- | --------------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### Credenziali Telegram condivise tramite Convex (v1) Quando `--credential-source convex` (o `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) è abilitato per -`openclaw qa telegram`, QA lab acquisisce un lease esclusivo da un pool supportato da Convex, invia heartbeat di quel lease mentre la lane è in esecuzione e rilascia il lease allo spegnimento. +`openclaw qa telegram`, QA lab acquisisce un lease esclusivo da un pool supportato da Convex, invia heartbeat su quel lease mentre la corsia è in esecuzione e rilascia il lease allo shutdown. -Scaffold del progetto Convex di riferimento: +Scaffold di riferimento per il progetto Convex: - `qa/convex-credential-broker/` -Variabili env richieste: +Variabili d’ambiente richieste: - `OPENCLAW_QA_CONVEX_SITE_URL` (per esempio `https://your-deployment.convex.site`) - Un secret per il ruolo selezionato: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` per `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` per `ci` -- Selezione del ruolo delle credenziali: +- Selezione del ruolo credenziale: - CLI: `--credential-role maintainer|ci` - - Valore predefinito env: `OPENCLAW_QA_CREDENTIAL_ROLE` (predefinito `maintainer`) + - Predefinito env: `OPENCLAW_QA_CREDENTIAL_ROLE` (predefinito `maintainer`) -Variabili env opzionali: +Variabili d’ambiente facoltative: - `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (predefinito `1200000`) - `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (predefinito `30000`) - `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (predefinito `90000`) - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (predefinito `15000`) - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (predefinito `/qa-credentials/v1`) -- `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (id di tracciamento opzionale) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` consente URL Convex `http://` in loopback per sviluppo solo locale. +- `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (id di tracciamento facoltativo) +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` consente URL Convex loopback `http://` solo per sviluppo locale. `OPENCLAW_QA_CONVEX_SITE_URL` dovrebbe usare `https://` nel normale funzionamento. -I comandi admin del maintainer (aggiunta/rimozione/elenco del pool) richiedono +I comandi CLI di amministrazione per i maintainer (add/remove/list del pool) richiedono specificamente `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. Helper CLI per i maintainer: @@ -132,7 +132,7 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Usa `--json` per output leggibile da macchina in script e utility CI. +Usa `--json` per output leggibile dalle macchine in script e utility CI. Contratto endpoint predefinito (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): @@ -142,17 +142,17 @@ Contratto endpoint predefinito (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials - Esaurito/riprovabile: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` - `POST /heartbeat` - Richiesta: `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` - - Successo: `{ status: "ok" }` (o `2xx` vuoto) + - Successo: `{ status: "ok" }` (oppure `2xx` vuoto) - `POST /release` - Richiesta: `{ kind, ownerId, actorRole, credentialId, leaseToken }` - - Successo: `{ status: "ok" }` (o `2xx` vuoto) + - Successo: `{ status: "ok" }` (oppure `2xx` vuoto) - `POST /admin/add` (solo secret maintainer) - Richiesta: `{ kind, actorId, payload, note?, status? }` - Successo: `{ status: "ok", credential }` - `POST /admin/remove` (solo secret maintainer) - Richiesta: `{ credentialId, actorId }` - Successo: `{ status: "ok", changed, credential }` - - Guardia lease attivo: `{ status: "error", code: "LEASE_ACTIVE", ... }` + - Protezione lease attivo: `{ status: "error", code: "LEASE_ACTIVE", ... }` - `POST /admin/list` (solo secret maintainer) - Richiesta: `{ kind?, status?, includePayload?, limit? }` - Successo: `{ status: "ok", credentials, count }` @@ -170,12 +170,12 @@ Aggiungere un canale al sistema QA markdown richiede esattamente due cose: 1. Un adapter di trasporto per il canale. 2. Un pacchetto di scenari che eserciti il contratto del canale. -Non aggiungere una nuova root di comando QA di primo livello quando l’host condiviso `qa-lab` può gestire il flusso. +Non aggiungere una nuova root di comando QA di primo livello quando l’host condiviso `qa-lab` può possedere il flusso. `qa-lab` possiede la meccanica condivisa dell’host: - la root di comando `openclaw qa` -- avvio e teardown della suite +- startup e teardown della suite - concorrenza dei worker - scrittura degli artifact - generazione dei report @@ -184,14 +184,14 @@ Non aggiungere una nuova root di comando QA di primo livello quando l’host con I plugin runner possiedono il contratto di trasporto: -- come `openclaw qa ` viene montato sotto la root condivisa `qa` -- come il gateway viene configurato per quel trasporto -- come viene verificata la readiness -- come vengono iniettati gli eventi inbound -- come vengono osservati i messaggi outbound -- come sono esposti transcript e stato di trasporto normalizzato +- come `openclaw qa ` è montato sotto la root condivisa `qa` +- come il Gateway è configurato per quel trasporto +- come viene controllata la readiness +- come vengono iniettati gli eventi in ingresso +- come vengono osservati i messaggi in uscita +- come transcript e stato di trasporto normalizzato vengono esposti - come vengono eseguite le azioni supportate dal trasporto -- come viene gestito il reset o la pulizia specifica del trasporto +- come vengono gestiti reset o cleanup specifici del trasporto La soglia minima di adozione per un nuovo canale è: @@ -200,19 +200,19 @@ La soglia minima di adozione per un nuovo canale è: 3. Mantenere la meccanica specifica del trasporto dentro il plugin runner o l’harness del plugin. 4. Montare il runner come `openclaw qa ` invece di registrare una root di comando concorrente. I plugin runner dovrebbero dichiarare `qaRunners` in `openclaw.plugin.json` ed esportare un array `qaRunnerCliRegistrations` corrispondente da `runtime-api.ts`. - Mantieni `runtime-api.ts` leggero; l’esecuzione lazy di CLI e runner dovrebbe restare dietro entrypoint separati. -5. Scrivere o adattare scenari markdown sotto `qa/scenarios/`. -6. Usare gli helper di scenario generici per i nuovi scenari. -7. Mantenere funzionanti gli alias di compatibilità esistenti, a meno che il repository non stia facendo una migrazione intenzionale. + Mantieni `runtime-api.ts` leggero; CLI lazy ed esecuzione del runner dovrebbero restare dietro entrypoint separati. +5. Creare o adattare scenari markdown sotto `qa/scenarios/`. +6. Usare gli helper generici per gli scenari nuovi. +7. Mantenere funzionanti gli alias di compatibilità esistenti, salvo una migrazione intenzionale del repo. -La regola decisionale è rigorosa: +La regola decisionale è rigida: - Se un comportamento può essere espresso una sola volta in `qa-lab`, mettilo in `qa-lab`. - Se un comportamento dipende da un solo trasporto di canale, mantienilo in quel plugin runner o harness del plugin. - Se uno scenario richiede una nuova capability che più di un canale può usare, aggiungi un helper generico invece di un branch specifico del canale in `suite.ts`. - Se un comportamento ha senso solo per un trasporto, mantieni lo scenario specifico del trasporto e rendilo esplicito nel contratto dello scenario. -I nomi preferiti degli helper generici per i nuovi scenari sono: +I nomi preferiti per i nuovi helper generici di scenario sono: - `waitForTransportReady` - `waitForChannelReady` @@ -227,7 +227,7 @@ I nomi preferiti degli helper generici per i nuovi scenari sono: - `formatTransportTranscript` - `resetTransport` -Gli alias di compatibilità restano disponibili per gli scenari esistenti, inclusi: +Restano disponibili gli alias di compatibilità per gli scenari esistenti, inclusi: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -235,98 +235,98 @@ Gli alias di compatibilità restano disponibili per gli scenari esistenti, inclu - `formatConversationTranscript` - `resetBus` -Il nuovo lavoro sui canali dovrebbe usare i nomi degli helper generici. -Gli alias di compatibilità esistono per evitare una migrazione “flag day”, non come modello per la scrittura di nuovi scenari. +Il nuovo lavoro sui canali dovrebbe usare i nomi generici degli helper. +Gli alias di compatibilità esistono per evitare una migrazione in un solo giorno, non come modello per la scrittura di nuovi scenari. ## Suite di test (cosa viene eseguito dove) -Pensa alle suite come a un “realismo crescente” (e flakiness/costo crescente): +Pensa alle suite come a “realismo crescente” (e crescente fragilità/costo): ### Unit / integration (predefinita) - Comando: `pnpm test` -- Configurazione: dieci esecuzioni sequenziali di shard (`vitest.full-*.config.ts`) sui project Vitest scoped esistenti +- Configurazione: dieci esecuzioni shard sequenziali (`vitest.full-*.config.ts`) sui progetti Vitest scoped esistenti - File: inventari core/unit sotto `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` e i test node `ui` in allowlist coperti da `vitest.unit.config.ts` - Ambito: - - Test unit puri - - Test di integrazione in-process (auth gateway, routing, tooling, parsing, config) + - Test unitari puri + - Test di integrazione in-process (auth Gateway, routing, tooling, parsing, config) - Regressioni deterministiche per bug noti - Aspettative: - Viene eseguito in CI - Non richiede chiavi reali - Dovrebbe essere veloce e stabile -- Nota sui project: - - `pnpm test` senza target ora esegue undici configurazioni shard più piccole (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) invece di un unico enorme processo native root-project. Questo riduce il picco RSS su macchine sotto carico ed evita che il lavoro di auto-reply/extension sottragga risorse a suite non correlate. - - `pnpm test --watch` usa ancora il grafo dei project del root nativo `vitest.config.ts`, perché un loop watch multi-shard non è pratico. - - `pnpm test`, `pnpm test:watch` e `pnpm test:perf:imports` instradano prima i target espliciti di file/directory attraverso lane scoped, quindi `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita il costo di avvio dell’intero root project. - - `pnpm test:changed` espande i percorsi git modificati nelle stesse lane scoped quando il diff tocca solo file source/test instradabili; le modifiche a config/setup tornano comunque alla riesecuzione ampia del root project. - - I test unit leggeri in termini di import da agents, commands, plugins, helper auto-reply, `plugin-sdk` e aree utility pure simili vengono instradati tramite la lane `unit-fast`, che salta `test/setup-openclaw-runtime.ts`; i file stateful/pesanti a runtime restano sulle lane esistenti. - - Alcuni file sorgente helper selezionati di `plugin-sdk` e `commands` mappano anche le esecuzioni in modalità changed a test sibling espliciti in quelle lane leggere, così le modifiche agli helper evitano di rieseguire l’intera suite pesante per quella directory. - - `auto-reply` ora ha tre bucket dedicati: helper core di primo livello, test di integrazione `reply.*` di primo livello e il sottoalbero `src/auto-reply/reply/**`. Questo mantiene il lavoro dell’harness reply più pesante fuori dai test economici di status/chunk/token. -- Nota sul runner embedded: +- Nota sui progetti: + - `pnpm test` senza target ora esegue undici config shard più piccole (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) invece di un unico grande processo nativo root-project. Questo riduce il picco RSS su macchine cariche ed evita che il lavoro auto-reply/extension affami suite non correlate. + - `pnpm test --watch` usa ancora il grafo di progetti nativo root `vitest.config.ts`, perché un loop watch multi-shard non è pratico. + - `pnpm test`, `pnpm test:watch` e `pnpm test:perf:imports` instradano prima i target espliciti di file/directory attraverso corsie scoped, così `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita di pagare il costo completo di startup del progetto root. + - `pnpm test:changed` espande i percorsi git modificati nelle stesse corsie scoped quando il diff tocca solo file source/test instradabili; le modifiche a config/setup tornano comunque alla riesecuzione ampia del root-project. + - I test unitari leggeri dal punto di vista degli import da agenti, comandi, plugin, helper auto-reply, `plugin-sdk` e aree utility pure simili vengono instradati nella corsia `unit-fast`, che salta `test/setup-openclaw-runtime.ts`; i file stateful/runtime-heavy restano nelle corsie esistenti. + - Alcuni file sorgente helper selezionati di `plugin-sdk` e `commands` mappano inoltre le esecuzioni in modalità changed a test sibling espliciti in quelle corsie leggere, così le modifiche agli helper evitano di rieseguire l’intera suite pesante per quella directory. + - `auto-reply` ora ha tre bucket dedicati: helper core di primo livello, test di integrazione `reply.*` di primo livello e il sottoalbero `src/auto-reply/reply/**`. Questo tiene il lavoro dell’harness reply più pesante lontano dai test economici di status/chunk/token. +- Nota sull’embedded runner: - Quando modifichi gli input di discovery dei message-tool o il contesto runtime di Compaction, mantieni entrambi i livelli di copertura. - - Aggiungi regressioni helper mirate per i boundary puri di routing/normalizzazione. - - Mantieni anche in salute le suite di integrazione dell’embedded runner: + - Aggiungi regressioni helper mirate per boundary puri di routing/normalizzazione. + - Mantieni sane anche le suite di integrazione dell’embedded runner: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` e `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - Queste suite verificano che gli id scoped e il comportamento di Compaction continuino a fluire - attraverso i percorsi reali `run.ts` / `compact.ts`; i test solo helper non sono un - sostituto sufficiente di questi percorsi di integrazione. + attraverso i percorsi reali `run.ts` / `compact.ts`; i test solo-helper non sono un + sostituto sufficiente per questi percorsi di integrazione. - Nota sul pool: - - La configurazione Vitest di base ora usa `threads` per impostazione predefinita. - - La configurazione Vitest condivisa fissa anche `isolate: false` e usa il runner non isolato tra root project, config e2e e live. - - La lane UI root mantiene la sua configurazione `jsdom` e l’optimizer, ma ora gira anch’essa sul runner condiviso non isolato. - - Ogni shard di `pnpm test` eredita gli stessi valori predefiniti `threads` + `isolate: false` dalla configurazione Vitest condivisa. - - Il launcher condiviso `scripts/run-vitest.mjs` ora aggiunge anche `--no-maglev` per impostazione predefinita ai processi Node figli di Vitest per ridurre il churn di compilazione V8 durante grandi esecuzioni locali. Imposta `OPENCLAW_VITEST_ENABLE_MAGLEV=1` se devi confrontare il comportamento con quello standard di V8. -- Nota sull’iterazione locale rapida: - - `pnpm test:changed` instrada attraverso lane scoped quando i percorsi modificati mappano in modo pulito a una suite più piccola. + - La config Vitest di base ora usa `threads` per impostazione predefinita. + - La config Vitest condivisa fissa anche `isolate: false` e usa il runner non isolato nei progetti root, e2e e live. + - La corsia UI root mantiene la sua configurazione `jsdom` e l’optimizer, ma ora gira anch’essa sul runner condiviso non isolato. + - Ogni shard `pnpm test` eredita gli stessi valori predefiniti `threads` + `isolate: false` dalla config Vitest condivisa. + - Il launcher condiviso `scripts/run-vitest.mjs` ora aggiunge anche `--no-maglev` per impostazione predefinita ai processi Node figli di Vitest, per ridurre il churn di compilazione V8 durante le grandi esecuzioni locali. Imposta `OPENCLAW_VITEST_ENABLE_MAGLEV=1` se devi confrontare il comportamento V8 standard. +- Nota sull’iterazione locale veloce: + - `pnpm test:changed` instrada attraverso corsie scoped quando i percorsi modificati si mappano in modo pulito a una suite più piccola. - `pnpm test:max` e `pnpm test:changed:max` mantengono lo stesso comportamento di instradamento, solo con un limite di worker più alto. - - L’auto-scaling locale dei worker ora è intenzionalmente più conservativo e arretra anche quando il load average dell’host è già alto, così più esecuzioni Vitest concorrenti fanno meno danni per impostazione predefinita. - - La configurazione Vitest di base contrassegna i project/file di configurazione come `forceRerunTriggers` così le riesecuzioni in modalità changed restano corrette quando cambia il wiring dei test. - - La configurazione mantiene `OPENCLAW_VITEST_FS_MODULE_CACHE` abilitato sugli host supportati; imposta `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` se vuoi una singola posizione di cache esplicita per il profiling diretto. -- Nota di debug prestazioni: - - `pnpm test:perf:imports` abilita il reporting della durata degli import in Vitest più l’output del dettaglio degli import. - - `pnpm test:perf:imports:changed` applica la stessa vista di profiling ai file modificati rispetto a `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` confronta `test:changed` instradato con il percorso root-project nativo per quel diff committato e stampa wall time più il max RSS su macOS. -- `pnpm test:perf:changed:bench -- --worktree` misura il tree sporco corrente instradando l’elenco dei file modificati attraverso `scripts/test-projects.mjs` e la configurazione root Vitest. - - `pnpm test:perf:profile:main` scrive un profilo CPU del thread principale per overhead di startup e transform di Vitest/Vite. - - `pnpm test:perf:profile:runner` scrive profili CPU+heap del runner per la suite unit con il parallelismo sui file disabilitato. + - L’auto-scaling locale dei worker ora è intenzionalmente conservativo e rallenta anche quando il load average dell’host è già alto, così più esecuzioni Vitest concorrenti fanno meno danni per impostazione predefinita. + - La config Vitest di base contrassegna i file di progetto/config come `forceRerunTriggers`, così le riesecuzioni in modalità changed restano corrette quando cambia il wiring dei test. + - La config mantiene `OPENCLAW_VITEST_FS_MODULE_CACHE` abilitato sugli host supportati; imposta `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` se vuoi una posizione di cache esplicita per profiling diretto. +- Nota per il debug delle performance: + - `pnpm test:perf:imports` abilita il reporting della durata degli import di Vitest più l’output del dettaglio degli import. + - `pnpm test:perf:imports:changed` limita la stessa vista di profiling ai file modificati rispetto a `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` confronta `test:changed` instradato con il percorso nativo root-project per quel diff committed e stampa wall time più max RSS su macOS. +- `pnpm test:perf:changed:bench -- --worktree` esegue il benchmark dell’albero dirty corrente instradando l’elenco dei file modificati attraverso `scripts/test-projects.mjs` e la config root Vitest. + - `pnpm test:perf:profile:main` scrive un profilo CPU del thread principale per l’overhead di startup e transform di Vitest/Vite. + - `pnpm test:perf:profile:runner` scrive profili CPU+heap del runner per la suite unit con parallelismo dei file disabilitato. -### E2E (smoke del gateway) +### E2E (smoke del Gateway) - Comando: `pnpm test:e2e` - Configurazione: `vitest.e2e.config.ts` - File: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` - Valori predefiniti runtime: - - Usa Vitest `threads` con `isolate: false`, in linea con il resto del repository. + - Usa Vitest `threads` con `isolate: false`, in linea con il resto del repo. - Usa worker adattivi (CI: fino a 2, locale: 1 per impostazione predefinita). - - Per impostazione predefinita gira in modalità silenziosa per ridurre l’overhead di I/O sulla console. + - Esegue in modalità silenziosa per impostazione predefinita per ridurre l’overhead di I/O della console. - Override utili: - `OPENCLAW_E2E_WORKERS=` per forzare il numero di worker (massimo 16). - - `OPENCLAW_E2E_VERBOSE=1` per riattivare l’output verboso sulla console. + - `OPENCLAW_E2E_VERBOSE=1` per riabilitare output console verboso. - Ambito: - - Comportamento end-to-end del gateway multiistanza - - Superfici WebSocket/HTTP, pairing dei Node e networking più pesante + - Comportamento end-to-end multiistanza del Gateway + - Superfici WebSocket/HTTP, pairing dei node e networking più pesante - Aspettative: - Viene eseguito in CI (quando abilitato nella pipeline) - Non richiede chiavi reali - - Ha più parti mobili rispetto ai test unit (può essere più lento) + - Ha più parti in movimento rispetto ai test unitari (può essere più lento) ### E2E: smoke del backend OpenShell - Comando: `pnpm test:e2e:openshell` - File: `test/openshell-sandbox.e2e.test.ts` - Ambito: - - Avvia un gateway OpenShell isolato sull’host tramite Docker + - Avvia sull’host un Gateway OpenShell isolato tramite Docker - Crea una sandbox da un Dockerfile locale temporaneo - - Esercita il backend OpenShell di OpenClaw tramite `sandbox ssh-config` reale + esecuzione SSH - - Verifica il comportamento del filesystem remote-canonical tramite il bridge fs della sandbox + - Esercita il backend OpenShell di OpenClaw tramite `sandbox ssh-config` + exec SSH reali + - Verifica il comportamento del filesystem canonico remoto tramite il bridge fs della sandbox - Aspettative: - Solo opt-in; non fa parte dell’esecuzione predefinita `pnpm test:e2e` - Richiede una CLI `openshell` locale più un demone Docker funzionante - - Usa `HOME` / `XDG_CONFIG_HOME` isolati, poi distrugge il gateway di test e la sandbox + - Usa `HOME` / `XDG_CONFIG_HOME` isolati, poi distrugge il Gateway di test e la sandbox - Override utili: - `OPENCLAW_E2E_OPENSHELL=1` per abilitare il test quando esegui manualmente la suite e2e più ampia - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` per puntare a un binario CLI non predefinito o a uno script wrapper @@ -339,111 +339,111 @@ Pensa alle suite come a un “realismo crescente” (e flakiness/costo crescente - Predefinito: **abilitato** da `pnpm test:live` (imposta `OPENCLAW_LIVE_TEST=1`) - Ambito: - “Questo provider/modello funziona davvero _oggi_ con credenziali reali?” - - Intercettare cambi di formato del provider, particolarità del tool-calling, problemi di auth e comportamento dei rate limit + - Intercettare cambi di formato del provider, particolarità nelle chiamate ai tool, problemi di auth e comportamento dei rate limit - Aspettative: - - Per progettazione non è stabile in CI (reti reali, policy reali dei provider, quote, outage) + - Per definizione non stabile in CI (reti reali, policy reali dei provider, quote, outage) - Costa denaro / usa rate limit - È preferibile eseguire sottoinsiemi ristretti invece di “tutto” -- Le esecuzioni live leggono `~/.profile` per recuperare eventuali chiavi API mancanti. -- Per impostazione predefinita, le esecuzioni live isolano comunque `HOME` e copiano il materiale config/auth in una home di test temporanea così i fixture unit non possono mutare il tuo vero `~/.openclaw`. -- Imposta `OPENCLAW_LIVE_USE_REAL_HOME=1` solo quando hai intenzionalmente bisogno che i test live usino la tua vera home directory. -- `pnpm test:live` ora usa per impostazione predefinita una modalità più silenziosa: mantiene l’output di avanzamento `[live] ...`, ma sopprime l’avviso aggiuntivo su `~/.profile` e silenzia i log di bootstrap del gateway e il chatter Bonjour. Imposta `OPENCLAW_LIVE_TEST_QUIET=0` se vuoi di nuovo i log completi di avvio. -- Rotazione delle chiavi API (specifica per provider): imposta `*_API_KEYS` con formato separato da virgole/punto e virgola oppure `*_API_KEY_1`, `*_API_KEY_2` (per esempio `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) oppure override per-live tramite `OPENCLAW_LIVE_*_KEY`; i test ritentano in caso di risposte di rate limit. +- Le esecuzioni live leggono `~/.profile` per recuperare chiavi API mancanti. +- Per impostazione predefinita, le esecuzioni live isolano comunque `HOME` e copiano materiale di config/auth in una home di test temporanea così le fixture unit non possono modificare il tuo `~/.openclaw` reale. +- Imposta `OPENCLAW_LIVE_USE_REAL_HOME=1` solo quando hai intenzionalmente bisogno che i test live usino la tua home directory reale. +- `pnpm test:live` ora usa per impostazione predefinita una modalità più silenziosa: mantiene l’output di avanzamento `[live] ...`, ma sopprime l’avviso extra su `~/.profile` e silenzia i log di bootstrap del Gateway/il traffico Bonjour. Imposta `OPENCLAW_LIVE_TEST_QUIET=0` se vuoi ripristinare i log completi di startup. +- Rotazione delle API key (specifica per provider): imposta `*_API_KEYS` con formato separato da virgole/punto e virgola oppure `*_API_KEY_1`, `*_API_KEY_2` (per esempio `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) oppure override per-live tramite `OPENCLAW_LIVE_*_KEY`; i test ritentano in caso di risposte di rate limit. - Output di avanzamento/heartbeat: - - Le suite live ora emettono righe di avanzamento su stderr così le chiamate lunghe ai provider risultano visibilmente attive anche quando la cattura della console di Vitest è silenziosa. - - `vitest.live.config.ts` disabilita l’intercettazione della console di Vitest così le righe di avanzamento di provider/gateway vengono trasmesse immediatamente durante le esecuzioni live. - - Regola gli heartbeat direct-model con `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Regola gli heartbeat gateway/probe con `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Le suite live ora emettono righe di avanzamento su stderr così le lunghe chiamate ai provider risultano visibilmente attive anche quando la cattura console di Vitest è silenziosa. + - `vitest.live.config.ts` disabilita l’intercettazione della console di Vitest così le righe di avanzamento provider/Gateway vengono trasmesse immediatamente durante le esecuzioni live. + - Regola gli heartbeat del modello diretto con `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Regola gli heartbeat del Gateway/probe con `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Quale suite dovrei eseguire? Usa questa tabella decisionale: - Modifica di logica/test: esegui `pnpm test` (e `pnpm test:coverage` se hai cambiato molto) -- Tocchi networking del gateway / protocollo WS / pairing: aggiungi `pnpm test:e2e` -- Debug di “il mio bot è giù” / errori specifici del provider / tool calling: esegui un `pnpm test:live` ristretto +- Toccare networking del Gateway / protocollo WS / pairing: aggiungi `pnpm test:e2e` +- Debug di “il mio bot è down” / errori specifici del provider / chiamata ai tool: esegui un `pnpm test:live` ristretto -## Live: sweep delle capability del Node Android +## Live: sweep delle capability del node Android - Test: `src/gateway/android-node.capabilities.live.test.ts` - Script: `pnpm android:test:integration` -- Obiettivo: invocare **ogni comando attualmente pubblicizzato** da un Node Android connesso e verificare il comportamento del contratto dei comandi. +- Obiettivo: invocare **ogni comando attualmente pubblicizzato** da un node Android connesso e verificare il comportamento del contratto del comando. - Ambito: - Setup manuale/con precondizioni (la suite non installa/esegue/abbina l’app). - - Validazione `node.invoke` del gateway comando per comando per il Node Android selezionato. + - Validazione `node.invoke` del Gateway comando per comando per il node Android selezionato. - Pre-setup richiesto: - - App Android già connessa e abbinata al gateway. - - App mantenuta in primo piano. - - Permessi/consenso alla cattura concessi per le capability che ti aspetti superino il test. -- Override target opzionali: + - App Android già connessa e paired al Gateway. + - App mantenuta in foreground. + - Permessi/consenso alla cattura concessi per le capability che ti aspetti passino. +- Override facoltativi del target: - `OPENCLAW_ANDROID_NODE_ID` oppure `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Dettagli completi sulla configurazione Android: [Android App](/it/platforms/android) +- Dettagli completi sul setup Android: [App Android](/it/platforms/android) -## Live: smoke dei modelli (chiavi profilo) +## Live: smoke del modello (chiavi profile) I test live sono divisi in due livelli così possiamo isolare i guasti: -- “Direct model” ci dice se il provider/modello può rispondere in assoluto con la chiave fornita. -- “Gateway smoke” ci dice se l’intera pipeline gateway+agent funziona per quel modello (sessioni, cronologia, tool, policy della sandbox, ecc.). +- “Direct model” ci dice se il provider/modello riesce almeno a rispondere con la chiave fornita. +- “Gateway smoke” ci dice se l’intera pipeline Gateway+agent funziona per quel modello (sessioni, cronologia, tool, policy sandbox, ecc.). -### Livello 1: completamento diretto del modello (senza gateway) +### Livello 1: completamento diretto del modello (senza Gateway) - Test: `src/agents/models.profiles.live.test.ts` - Obiettivo: - - Enumerare i modelli individuati + - Enumerare i modelli rilevati - Usare `getApiKeyForModel` per selezionare i modelli per cui hai credenziali - - Eseguire un piccolo completamento per modello (e regressioni mirate dove necessario) + - Eseguire un piccolo completion per modello (e regressioni mirate dove necessario) - Come abilitarlo: - `pnpm test:live` (oppure `OPENCLAW_LIVE_TEST=1` se invochi Vitest direttamente) -- Imposta `OPENCLAW_LIVE_MODELS=modern` (oppure `all`, alias di modern) per eseguire davvero questa suite; altrimenti viene saltata per mantenere `pnpm test:live` focalizzato sullo smoke del gateway +- Imposta `OPENCLAW_LIVE_MODELS=modern` (oppure `all`, alias di modern) per eseguire davvero questa suite; altrimenti viene saltata per mantenere `pnpm test:live` focalizzato sullo smoke del Gateway - Come selezionare i modelli: - - `OPENCLAW_LIVE_MODELS=modern` per eseguire l’allowlist moderna (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_MODELS=all` è un alias per l’allowlist moderna + - `OPENCLAW_LIVE_MODELS=modern` per eseguire l’allowlist modern (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_MODELS=all` è un alias per l’allowlist modern - oppure `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist separata da virgole) - - Gli sweep modern/all usano per impostazione predefinita un cap curato ad alto segnale; imposta `OPENCLAW_LIVE_MAX_MODELS=0` per uno sweep moderno esaustivo oppure un numero positivo per un cap più piccolo. + - Gli sweep modern/all usano per impostazione predefinita un limite curato ad alto segnale; imposta `OPENCLAW_LIVE_MAX_MODELS=0` per uno sweep modern esaustivo oppure un numero positivo per un limite più piccolo. - Come selezionare i provider: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist separata da virgole) - Da dove arrivano le chiavi: - - Per impostazione predefinita: store dei profili e fallback env - - Imposta `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre **solo** lo store dei profili + - Per impostazione predefinita: profile store e fallback env + - Imposta `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre **solo** il profile store - Perché esiste: - - Separa “l’API del provider è rotta / la chiave non è valida” da “la pipeline dell’agent del gateway è rotta” - - Contiene regressioni piccole e isolate (esempio: replay del ragionamento OpenAI Responses/Codex Responses + flussi di tool-call) + - Separa “l’API del provider è rotta / la chiave non è valida” da “la pipeline agent del Gateway è rotta” + - Contiene regressioni piccole e isolate (esempio: replay del reasoning OpenAI Responses/Codex Responses + flussi di tool-call) -### Livello 2: smoke del gateway + dev agent (quello che fa davvero "@openclaw") +### Livello 2: smoke Gateway + agent dev (quello che fa davvero "@openclaw") - Test: `src/gateway/gateway-models.profiles.live.test.ts` - Obiettivo: - - Avviare un gateway in-process - - Creare/modificare una sessione `agent:dev:*` (override del modello per esecuzione) - - Iterare sui modelli con chiavi e verificare: + - Avviare un Gateway in-process + - Creare/aggiornare una sessione `agent:dev:*` (override del modello per esecuzione) + - Iterare sui modelli-con-chiavi e verificare: - risposta “significativa” (senza tool) - - il funzionamento di una vera invocazione di tool (probe di lettura) - - probe di tool extra opzionali (probe exec+read) - - il mantenimento del funzionamento dei percorsi di regressione OpenAI (solo tool-call → follow-up) + - che una vera invocazione di tool funzioni (probe `read`) + - probe di tool extra facoltative (probe `exec+read`) + - che i percorsi di regressione OpenAI (solo tool-call → follow-up) continuino a funzionare - Dettagli delle probe (così puoi spiegare rapidamente i guasti): - - probe `read`: il test scrive un file nonce nel workspace e chiede all’agente di eseguire `read` su quel file e rimandare il nonce. - - probe `exec+read`: il test chiede all’agente di scrivere via `exec` un nonce in un file temporaneo e poi di leggerlo di nuovo con `read`. - - probe immagine: il test allega un PNG generato (gatto + codice casuale) e si aspetta che il modello restituisca `cat `. + - probe `read`: il test scrive un file nonce nel workspace e chiede all’agent di leggerlo con `read` e di restituire il nonce. + - probe `exec+read`: il test chiede all’agent di scrivere un nonce in un file temporaneo tramite `exec`, quindi di rileggerlo con `read`. + - image probe: il test allega un PNG generato (gatto + codice randomizzato) e si aspetta che il modello restituisca `cat `. - Riferimento implementativo: `src/gateway/gateway-models.profiles.live.test.ts` e `src/gateway/live-image-probe.ts`. - Come abilitarlo: - `pnpm test:live` (oppure `OPENCLAW_LIVE_TEST=1` se invochi Vitest direttamente) - Come selezionare i modelli: - - Predefinito: allowlist moderna (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` è un alias per l’allowlist moderna - - Oppure imposta `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (o un elenco separato da virgole) per restringere - - Gli sweep gateway modern/all usano per impostazione predefinita un cap curato ad alto segnale; imposta `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` per uno sweep moderno esaustivo oppure un numero positivo per un cap più piccolo. + - Predefinito: allowlist modern (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` è un alias per l’allowlist modern + - Oppure imposta `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (o una lista separata da virgole) per restringere + - Gli sweep Gateway modern/all usano per impostazione predefinita un limite curato ad alto segnale; imposta `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` per uno sweep modern esaustivo oppure un numero positivo per un limite più piccolo. - Come selezionare i provider (evita “tutto OpenRouter”): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist separata da virgole) - Le probe di tool + immagine sono sempre attive in questo test live: - - probe `read` + probe `exec+read` (stress sui tool) - - la probe immagine viene eseguita quando il modello dichiara il supporto per input immagine + - probe `read` + probe `exec+read` (stress dei tool) + - la image probe viene eseguita quando il modello dichiara supporto per input immagine - Flusso (alto livello): - Il test genera un piccolo PNG con “CAT” + codice casuale (`src/gateway/live-image-probe.ts`) - Lo invia tramite `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - Gateway analizza gli allegati in `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - L’agente embedded inoltra al modello un messaggio utente multimodale + - L’agent embedded inoltra al modello un messaggio utente multimodale - Verifica: la risposta contiene `cat` + il codice (tolleranza OCR: sono ammessi piccoli errori) Suggerimento: per vedere cosa puoi testare sulla tua macchina (e gli id esatti `provider/model`), esegui: @@ -456,15 +456,15 @@ openclaw models list --json ## Live: smoke del backend CLI (Claude, Codex, Gemini o altre CLI locali) - Test: `src/gateway/gateway-cli-backend.live.test.ts` -- Obiettivo: validare la pipeline Gateway + agente usando un backend CLI locale, senza toccare la configurazione predefinita. +- Obiettivo: validare la pipeline Gateway + agent usando un backend CLI locale, senza toccare la tua configurazione predefinita. - I valori predefiniti smoke specifici del backend si trovano nella definizione `cli-backend.ts` dell’extension proprietaria. - Abilitazione: - `pnpm test:live` (oppure `OPENCLAW_LIVE_TEST=1` se invochi Vitest direttamente) - `OPENCLAW_LIVE_CLI_BACKEND=1` -- Valori predefiniti: +- Predefiniti: - Provider/modello predefinito: `claude-cli/claude-sonnet-4-6` - - Il comportamento di comando/argomenti/immagini proviene dai metadati del plugin proprietario del backend CLI. -- Override (opzionali): + - Comando/argomenti/comportamento immagine provengono dai metadati del plugin backend CLI proprietario. +- Override (facoltativi): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` @@ -472,7 +472,7 @@ openclaw models list --json - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` per passare i percorsi dei file immagine come argomenti CLI invece che tramite iniezione nel prompt. - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (oppure `"list"`) per controllare come vengono passati gli argomenti immagine quando `IMAGE_ARG` è impostato. - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` per inviare un secondo turno e validare il flusso di ripresa. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` per disabilitare la probe predefinita di continuità nella stessa sessione Claude Sonnet -> Opus (impostalo a `1` per forzarla quando il modello selezionato supporta una destinazione di switch). + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` per disabilitare la probe predefinita di continuità nella stessa sessione Claude Sonnet -> Opus (imposta `1` per forzarla quando il modello selezionato supporta un target di switch). Esempio: @@ -500,27 +500,27 @@ pnpm test:docker:live-cli-backend:gemini Note: - Il runner Docker si trova in `scripts/test-live-cli-backend-docker.sh`. -- Esegue lo smoke live del backend CLI dentro l’immagine Docker del repository come utente non root `node`. -- Risolve i metadati smoke della CLI dall’extension proprietaria, poi installa il pacchetto CLI Linux corrispondente (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) in un prefisso scrivibile in cache su `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (predefinito: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` richiede OAuth portabile di sottoscrizione Claude Code tramite `~/.claude/.credentials.json` con `claudeAiOauth.subscriptionType` oppure `CLAUDE_CODE_OAUTH_TOKEN` da `claude setup-token`. Prima dimostra `claude -p` diretto in Docker, poi esegue due turni Gateway CLI-backend senza preservare le variabili env delle chiavi API Anthropic. Questa lane subscription disabilita per impostazione predefinita le probe Claude MCP/tool e immagine perché Claude attualmente instrada l’uso di app di terze parti tramite fatturazione per uso extra invece che tramite i normali limiti del piano di sottoscrizione. -- Lo smoke live del backend CLI ora esercita lo stesso flusso end-to-end per Claude, Codex e Gemini: turno di testo, turno di classificazione immagine, poi chiamata del tool MCP `cron` verificata tramite la CLI del gateway. -- Lo smoke predefinito di Claude modifica anche la sessione da Sonnet a Opus e verifica che la sessione ripresa ricordi ancora una nota precedente. +- Esegue lo smoke live del backend CLI dentro l’immagine Docker del repo come utente non root `node`. +- Risolve i metadati smoke della CLI dall’extension proprietaria, poi installa il pacchetto CLI Linux corrispondente (`@anthropic-ai/claude-code`, `@openai/codex` oppure `@google/gemini-cli`) in un prefisso scrivibile in cache in `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (predefinito: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` richiede OAuth portabile di sottoscrizione Claude Code tramite `~/.claude/.credentials.json` con `claudeAiOauth.subscriptionType` oppure `CLAUDE_CODE_OAUTH_TOKEN` da `claude setup-token`. Prima verifica `claude -p` diretto in Docker, poi esegue due turni Gateway CLI-backend senza preservare le variabili d’ambiente della chiave API Anthropic. Questa corsia subscription disabilita per impostazione predefinita le probe Claude MCP/tool e immagine perché Claude attualmente instrada l’uso delle app di terze parti tramite addebiti per uso extra invece che attraverso i normali limiti del piano di sottoscrizione. +- Lo smoke live del backend CLI ora esercita lo stesso flusso end-to-end per Claude, Codex e Gemini: turno testuale, turno di classificazione immagine, quindi chiamata al tool MCP `cron` verificata tramite la CLI del Gateway. +- Lo smoke predefinito di Claude aggiorna inoltre la sessione da Sonnet a Opus e verifica che la sessione ripresa ricordi ancora una nota precedente. -## Live: smoke del bind ACP (`/acp spawn ... --bind here`) +## Live: smoke ACP bind (`/acp spawn ... --bind here`) - Test: `src/gateway/gateway-acp-bind.live.test.ts` -- Obiettivo: validare il vero flusso di conversation-bind ACP con un agente ACP live: +- Obiettivo: validare il vero flusso ACP conversation-bind con un agent ACP live: - inviare `/acp spawn --bind here` - - collegare in loco una conversazione sintetica su canale di messaggistica + - collegare in-place una conversazione sintetica di message-channel - inviare un normale follow-up sulla stessa conversazione - verificare che il follow-up arrivi nel transcript della sessione ACP collegata - Abilitazione: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` -- Valori predefiniti: - - Agenti ACP in Docker: `claude,codex,gemini` - - Agente ACP per `pnpm test:live ...` diretto: `claude` - - Canale sintetico: contesto di conversazione in stile DM Slack +- Predefiniti: + - Agent ACP in Docker: `claude,codex,gemini` + - Agent ACP per `pnpm test:live ...` diretto: `claude` + - Canale sintetico: contesto conversazione stile Slack DM - Backend ACP: `acpx` - Override: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` @@ -529,8 +529,8 @@ Note: - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Note: - - Questa lane usa la superficie `chat.send` del gateway con campi synthetic originating-route solo admin così i test possono collegare il contesto del canale di messaggistica senza fingere una consegna esterna. - - Quando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` non è impostato, il test usa il registro agent incorporato del plugin embedded `acpx` per l’agente harness ACP selezionato. + - Questa corsia usa la superficie Gateway `chat.send` con campi `originating-route` sintetici solo-admin, così i test possono collegare il contesto message-channel senza fingere una consegna esterna. + - Quando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` non è impostato, il test usa il registro agent integrato del plugin embedded `acpx` per l’agent harness ACP selezionato. Esempio: @@ -546,7 +546,7 @@ Ricetta Docker: pnpm test:docker:live-acp-bind ``` -Ricette Docker per singolo agente: +Ricette Docker per singolo agent: ```bash pnpm test:docker:live-acp-bind:claude @@ -557,31 +557,31 @@ pnpm test:docker:live-acp-bind:gemini Note Docker: - Il runner Docker si trova in `scripts/test-live-acp-bind-docker.sh`. -- Per impostazione predefinita, esegue in sequenza lo smoke ACP bind contro tutti gli agenti CLI live supportati: `claude`, `codex`, poi `gemini`. -- Usa `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` o `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` per restringere la matrice. -- Legge `~/.profile`, prepara nel container il materiale di autenticazione CLI corrispondente, installa `acpx` in un prefisso npm scrivibile, poi installa la CLI live richiesta (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) se manca. -- Dentro Docker, il runner imposta `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` così acpx mantiene disponibili alla CLI harness figlia le variabili env del provider provenienti dal profilo caricato. +- Per impostazione predefinita esegue in sequenza lo smoke ACP bind contro tutti gli agent CLI live supportati: `claude`, `codex`, poi `gemini`. +- Usa `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` oppure `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` per restringere la matrice. +- Legge `~/.profile`, prepara nel container il materiale auth CLI corrispondente, installa `acpx` in un prefisso npm scrivibile, quindi installa la CLI live richiesta (`@anthropic-ai/claude-code`, `@openai/codex` oppure `@google/gemini-cli`) se manca. +- Dentro Docker, il runner imposta `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` così `acpx` mantiene disponibili alla CLI harness figlia le variabili d’ambiente del provider provenienti dal profilo caricato. -## Live: smoke dell’harness app-server Codex +## Live: smoke dell’harness Codex app-server -- Obiettivo: validare l’harness Codex posseduto dal plugin tramite il normale - metodo `agent` del gateway: +- Obiettivo: validare l’harness Codex di proprietà del plugin tramite il normale metodo Gateway + `agent`: - caricare il plugin `codex` incluso - selezionare `OPENCLAW_AGENT_RUNTIME=codex` - - inviare un primo turno agent del gateway a `codex/gpt-5.4` + - inviare un primo turno Gateway agent a `codex/gpt-5.4` - inviare un secondo turno alla stessa sessione OpenClaw e verificare che il thread app-server possa riprendere - - eseguire `/codex status` e `/codex models` tramite lo stesso percorso - di comando del gateway + - eseguire `/codex status` e `/codex models` tramite lo stesso percorso di comando + del Gateway - Test: `src/gateway/gateway-codex-harness.live.test.ts` - Abilitazione: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Modello predefinito: `codex/gpt-5.4` -- Probe immagine opzionale: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- Probe MCP/tool opzionale: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- Probe immagine facoltativa: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- Probe MCP/tool facoltativa: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` - Lo smoke imposta `OPENCLAW_AGENT_HARNESS_FALLBACK=none` così un harness Codex - rotto non può superare il test ricadendo silenziosamente su PI. -- Auth: `OPENAI_API_KEY` dalla shell/profilo, più eventuali file copiati - `~/.codex/auth.json` e `~/.codex/config.toml` + rotto non può passare cadendo silenziosamente su PI. +- Auth: `OPENAI_API_KEY` dalla shell/profilo, più eventuali + `~/.codex/auth.json` e `~/.codex/config.toml` copiati Ricetta locale: @@ -604,27 +604,24 @@ pnpm test:docker:live-codex-harness Note Docker: - Il runner Docker si trova in `scripts/test-live-codex-harness-docker.sh`. -- Legge il `~/.profile` montato, passa `OPENAI_API_KEY`, copia i file auth della CLI Codex - quando presenti, installa `@openai/codex` in un prefisso npm montato e scrivibile, - prepara il source tree, poi esegue solo il test live dell’harness Codex. +- Legge `~/.profile` montato, passa `OPENAI_API_KEY`, copia i file di auth della CLI Codex quando presenti, installa `@openai/codex` in un prefisso npm montato e scrivibile, prepara il source tree, quindi esegue solo il test live Codex-harness. - Docker abilita per impostazione predefinita le probe immagine e MCP/tool. Imposta `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` oppure - `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` quando hai bisogno di un’esecuzione di debug più ristretta. -- Docker esporta anche `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, in linea con la configurazione - del test live così il fallback `openai-codex/*` o PI non può nascondere una regressione - dell’harness Codex. + `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` quando ti serve un’esecuzione di debug più ristretta. +- Docker esporta anche `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, in linea con la + configurazione del test live così il fallback `openai-codex/*` o PI non può nascondere una regressione dell’harness Codex. ### Ricette live consigliate -Allowlist ristrette ed esplicite sono più rapide e meno soggette a flakiness: +Allowlist ristrette ed esplicite sono più veloci e meno soggette a fragilità: -- Modello singolo, diretto (senza gateway): +- Modello singolo, diretto (senza Gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- Modello singolo, smoke del gateway: +- Modello singolo, smoke Gateway: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Tool calling su diversi provider: +- Chiamata ai tool su più provider: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Focus Google (chiave API Gemini + Antigravity): @@ -635,31 +632,31 @@ Note: - `google/...` usa l’API Gemini (chiave API). - `google-antigravity/...` usa il bridge OAuth Antigravity (endpoint agent in stile Cloud Code Assist). -- `google-gemini-cli/...` usa la CLI Gemini locale sulla tua macchina (auth separata + particolarità del tooling). +- `google-gemini-cli/...` usa la CLI Gemini locale sulla tua macchina (auth separata + particolarità degli strumenti). - API Gemini vs CLI Gemini: - - API: OpenClaw chiama l’API Gemini ospitata da Google tramite HTTP (auth con chiave API / profilo); è ciò che la maggior parte degli utenti intende con “Gemini”. - - CLI: OpenClaw esegue una shell verso un binario `gemini` locale; ha una propria auth e può comportarsi in modo diverso (streaming/supporto tool/version skew). + - API: OpenClaw chiama l’API Gemini ospitata da Google via HTTP (chiave API / auth profile); è ciò che la maggior parte degli utenti intende con “Gemini”. + - CLI: OpenClaw esegue una shell verso un binario locale `gemini`; ha una propria auth e può comportarsi in modo diverso (streaming/supporto tool/version skew). ## Live: matrice dei modelli (cosa copriamo) -Non esiste un elenco fisso di “modelli CI” (live è opt-in), ma questi sono i modelli **consigliati** da coprire regolarmente su una macchina di sviluppo con chiavi. +Non esiste un “elenco modelli CI” fisso (live è opt-in), ma questi sono i modelli **consigliati** da coprire regolarmente su una macchina di sviluppo con chiavi. ### Set smoke moderno (tool calling + immagine) Questa è l’esecuzione dei “modelli comuni” che ci aspettiamo continui a funzionare: -- OpenAI (non-Codex): `openai/gpt-5.4` (opzionale: `openai/gpt-5.4-mini`) +- OpenAI (non-Codex): `openai/gpt-5.4` (facoltativo: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` - Anthropic: `anthropic/claude-opus-4-6` (oppure `anthropic/claude-sonnet-4-6`) -- Google (API Gemini): `google/gemini-3.1-pro-preview` e `google/gemini-3-flash-preview` (evita i modelli Gemini 2.x più vecchi) +- Google (API Gemini): `google/gemini-3.1-pro-preview` e `google/gemini-3-flash-preview` (evita i vecchi modelli Gemini 2.x) - Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` e `google-antigravity/gemini-3-flash` - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Esegui lo smoke del gateway con tool + immagine: +Esegui lo smoke Gateway con tool + immagine: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Baseline: tool calling (Read + Exec opzionale) +### Baseline: tool calling (Read + Exec facoltativo) Scegline almeno uno per famiglia di provider: @@ -669,7 +666,7 @@ Scegline almeno uno per famiglia di provider: - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Copertura aggiuntiva opzionale (utile averla): +Copertura aggiuntiva facoltativa (utile averla): - xAI: `xai/grok-4` (oppure l’ultima disponibile) - Mistral: `mistral/`… (scegli un modello con capability “tools” che hai abilitato) @@ -678,35 +675,35 @@ Copertura aggiuntiva opzionale (utile averla): ### Vision: invio immagine (allegato → messaggio multimodale) -Includi almeno un modello con capability immagine in `OPENCLAW_LIVE_GATEWAY_MODELS` (varianti Claude/Gemini/OpenAI con supporto vision, ecc.) per esercitare la probe immagine. +Includi almeno un modello con capability immagine in `OPENCLAW_LIVE_GATEWAY_MODELS` (varianti Claude/Gemini/OpenAI con supporto vision, ecc.) per esercitare la image probe. ### Aggregatori / gateway alternativi -Se hai chiavi abilitate, supportiamo anche i test tramite: +Se hai chiavi abilitate, supportiamo anche il test tramite: - OpenRouter: `openrouter/...` (centinaia di modelli; usa `openclaw models scan` per trovare candidati con capability tool+image) - OpenCode: `opencode/...` per Zen e `opencode-go/...` per Go (auth tramite `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Altri provider che puoi includere nella matrice live (se hai credenziali/configurazione): +Altri provider che puoi includere nella matrice live (se hai credenziali/config): -- Inclusi: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` +- Integrati: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` - Tramite `models.providers` (endpoint personalizzati): `minimax` (cloud/API), più qualsiasi proxy compatibile OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, ecc.) -Suggerimento: non cercare di hardcodare “tutti i modelli” nella documentazione. L’elenco autorevole è qualunque cosa restituisca `discoverModels(...)` sulla tua macchina + qualunque chiave sia disponibile. +Suggerimento: non cercare di codificare in modo rigido “tutti i modelli” nella documentazione. L’elenco autorevole è qualunque cosa restituisca `discoverModels(...)` sulla tua macchina + qualunque chiave sia disponibile. ## Credenziali (non fare mai commit) -I test live individuano le credenziali nello stesso modo della CLI. Implicazioni pratiche: +I test live rilevano le credenziali nello stesso modo della CLI. Implicazioni pratiche: - Se la CLI funziona, i test live dovrebbero trovare le stesse chiavi. -- Se un test live dice “nessuna credenziale”, esegui il debug come faresti con `openclaw models list` / selezione del modello. +- Se un test live dice “nessuna credenziale”, esegui il debug nello stesso modo in cui faresti per `openclaw models list` / selezione del modello. -- Profili auth per agent: `~/.openclaw/agents//agent/auth-profiles.json` (questo è il significato di “chiavi profilo” nei test live) -- Configurazione: `~/.openclaw/openclaw.json` (oppure `OPENCLAW_CONFIG_PATH`) -- Directory di stato legacy: `~/.openclaw/credentials/` (copiata nella home live staged quando presente, ma non è lo store principale delle chiavi profilo) -- Le esecuzioni live locali copiano per impostazione predefinita la configurazione attiva, i file `auth-profiles.json` per agent, `credentials/` legacy e le directory auth supportate delle CLI esterne in una home di test temporanea; le home live staged saltano `workspace/` e `sandboxes/`, e gli override di percorso `agents.*.workspace` / `agentDir` vengono rimossi così le probe restano fuori dal tuo vero workspace host. +- Profili auth per agent: `~/.openclaw/agents//agent/auth-profiles.json` (questo è ciò che “profile keys” significa nei test live) +- Config: `~/.openclaw/openclaw.json` (oppure `OPENCLAW_CONFIG_PATH`) +- Directory stato legacy: `~/.openclaw/credentials/` (copiata nella home live staged quando presente, ma non è il main profile-key store) +- Le esecuzioni live locali copiano per impostazione predefinita config attiva, file `auth-profiles.json` per-agent, `credentials/` legacy e directory auth CLI esterne supportate in una home di test temporanea; le home live staged saltano `workspace/` e `sandboxes/`, e gli override di percorso `agents.*.workspace` / `agentDir` vengono rimossi così le probe restano fuori dal tuo workspace host reale. -Se vuoi basarti su chiavi env (ad esempio esportate nel tuo `~/.profile`), esegui i test locali dopo `source ~/.profile`, oppure usa i runner Docker qui sotto (possono montare `~/.profile` nel container). +Se vuoi affidarti alle chiavi env (per esempio esportate nel tuo `~/.profile`), esegui i test locali dopo `source ~/.profile`, oppure usa i runner Docker qui sotto (possono montare `~/.profile` nel container). ## Live Deepgram (trascrizione audio) @@ -717,28 +714,28 @@ Se vuoi basarti su chiavi env (ad esempio esportate nel tuo `~/.profile`), esegu - Test: `src/agents/byteplus.live.test.ts` - Abilitazione: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` -- Override modello opzionale: `BYTEPLUS_CODING_MODEL=ark-code-latest` +- Override facoltativo del modello: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Live media del workflow ComfyUI +## Live ComfyUI workflow media - Test: `extensions/comfy/comfy.live.test.ts` - Abilitazione: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Ambito: - - Esercita i percorsi inclusi comfy per immagini, video e `music_generate` + - Esercita i percorsi image, video e `music_generate` del comfy incluso - Salta ogni capability a meno che `models.providers.comfy.` non sia configurato - Utile dopo modifiche a invio workflow comfy, polling, download o registrazione del plugin -## Live generazione immagini +## Live image generation - Test: `src/image-generation/runtime.live.test.ts` - Comando: `pnpm test:live src/image-generation/runtime.live.test.ts` - Harness: `pnpm test:live:media image` - Ambito: - - Enumera ogni plugin provider di generazione immagini registrato - - Carica le variabili env provider mancanti dalla tua shell di login (`~/.profile`) prima delle probe - - Usa per impostazione predefinita le chiavi API live/env prima dei profili auth memorizzati, così chiavi di test obsolete in `auth-profiles.json` non mascherano le vere credenziali della shell - - Salta i provider senza auth/profilo/modello utilizzabile - - Esegue le varianti standard di generazione immagini tramite la capability runtime condivisa: + - Enumera ogni plugin provider di image generation registrato + - Carica le variabili env provider mancanti dalla tua login shell (`~/.profile`) prima della probe + - Usa per impostazione predefinita chiavi API live/env prima dei profili auth memorizzati, così chiavi di test obsolete in `auth-profiles.json` non mascherano le credenziali reali della shell + - Salta i provider senza auth/profile/modello utilizzabile + - Esegue le varianti standard di image generation tramite la capability runtime condivisa: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` @@ -746,147 +743,146 @@ Se vuoi basarti su chiavi env (ad esempio esportate nel tuo `~/.profile`), esegu - Provider inclusi attualmente coperti: - `openai` - `google` -- Restrizione opzionale: +- Restrizione facoltativa: - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` -- Comportamento auth opzionale: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre l’auth dello store profili e ignorare gli override solo env +- Comportamento auth facoltativo: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre l’auth dal profile store e ignorare gli override solo-env -## Live generazione musicale +## Live music generation - Test: `extensions/music-generation-providers.live.test.ts` - Abilitazione: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Ambito: - - Esercita il percorso condiviso incluso dei provider di generazione musicale + - Esercita il percorso condiviso del provider di music generation incluso - Attualmente copre Google e MiniMax - - Carica le variabili env provider dalla tua shell di login (`~/.profile`) prima delle probe - - Usa per impostazione predefinita le chiavi API live/env prima dei profili auth memorizzati, così chiavi di test obsolete in `auth-profiles.json` non mascherano le vere credenziali della shell - - Salta i provider senza auth/profilo/modello utilizzabile + - Carica le variabili env provider dalla tua login shell (`~/.profile`) prima della probe + - Usa per impostazione predefinita chiavi API live/env prima dei profili auth memorizzati, così chiavi di test obsolete in `auth-profiles.json` non mascherano le credenziali reali della shell + - Salta i provider senza auth/profile/modello utilizzabile - Esegue entrambe le modalità runtime dichiarate quando disponibili: - `generate` con input solo prompt - `edit` quando il provider dichiara `capabilities.edit.enabled` - - Copertura attuale della lane condivisa: + - Copertura attuale della corsia condivisa: - `google`: `generate`, `edit` - `minimax`: `generate` - `comfy`: file live Comfy separato, non questo sweep condiviso -- Restrizione opzionale: +- Restrizione facoltativa: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` -- Comportamento auth opzionale: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre l’auth dello store profili e ignorare gli override solo env +- Comportamento auth facoltativo: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre l’auth dal profile store e ignorare gli override solo-env -## Live generazione video +## Live video generation - Test: `extensions/video-generation-providers.live.test.ts` - Abilitazione: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Ambito: - - Esercita il percorso condiviso incluso dei provider di generazione video - - Per impostazione predefinita usa il percorso smoke sicuro per release: provider non-FAL, una richiesta text-to-video per provider, prompt lobster di un secondo e un cap per-provider sulle operazioni da `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` per impostazione predefinita) - - Per impostazione predefinita salta FAL perché la latenza della coda lato provider può dominare il tempo della release; passa `--video-providers fal` oppure `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` per eseguirlo esplicitamente - - Carica le variabili env provider dalla tua shell di login (`~/.profile`) prima delle probe - - Usa per impostazione predefinita le chiavi API live/env prima dei profili auth memorizzati, così chiavi di test obsolete in `auth-profiles.json` non mascherano le vere credenziali della shell - - Salta i provider senza auth/profilo/modello utilizzabile - - Per impostazione predefinita esegue solo `generate` + - Esercita il percorso condiviso del provider di video generation incluso + - Usa per impostazione predefinita il percorso smoke sicuro per la release: provider non-FAL, una richiesta text-to-video per provider, prompt lobster di un secondo e un limite di operazione per provider da `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` per impostazione predefinita) + - Salta FAL per impostazione predefinita perché la latenza della coda lato provider può dominare il tempo di release; passa `--video-providers fal` oppure `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` per eseguirlo esplicitamente + - Carica le variabili env provider dalla tua login shell (`~/.profile`) prima della probe + - Usa per impostazione predefinita chiavi API live/env prima dei profili auth memorizzati, così chiavi di test obsolete in `auth-profiles.json` non mascherano le credenziali reali della shell + - Salta i provider senza auth/profile/modello utilizzabile + - Esegue solo `generate` per impostazione predefinita - Imposta `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` per eseguire anche le modalità transform dichiarate quando disponibili: - - `imageToVideo` quando il provider dichiara `capabilities.imageToVideo.enabled` e il provider/modello selezionato accetta input immagine locale supportato da buffer nello sweep condiviso - - `videoToVideo` quando il provider dichiara `capabilities.videoToVideo.enabled` e il provider/modello selezionato accetta input video locale supportato da buffer nello sweep condiviso + - `imageToVideo` quando il provider dichiara `capabilities.imageToVideo.enabled` e il provider/modello selezionato accetta input immagine locale buffer-backed nello sweep condiviso + - `videoToVideo` quando il provider dichiara `capabilities.videoToVideo.enabled` e il provider/modello selezionato accetta input video locale buffer-backed nello sweep condiviso - Provider `imageToVideo` attualmente dichiarati ma saltati nello sweep condiviso: - `vydra` perché `veo3` incluso è solo testo e `kling` incluso richiede un URL immagine remoto - - Copertura Vydra specifica del provider: + - Copertura specifica del provider Vydra: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - quel file esegue `veo3` text-to-video più una lane `kling` che usa per impostazione predefinita un fixture con URL immagine remoto + - quel file esegue `veo3` text-to-video più una corsia `kling` che usa per impostazione predefinita una fixture con URL immagine remoto - Copertura live attuale `videoToVideo`: - - solo `runway` quando il modello selezionato è `runway/gen4_aleph` + - `runway` solo quando il modello selezionato è `runway/gen4_aleph` - Provider `videoToVideo` attualmente dichiarati ma saltati nello sweep condiviso: - - `alibaba`, `qwen`, `xai` perché quei percorsi richiedono attualmente URL di riferimento remoti `http(s)` / MP4 - - `google` perché l’attuale lane condivisa Gemini/Veo usa input locale supportato da buffer e quel percorso non è accettato nello sweep condiviso - - `openai` perché l’attuale lane condivisa non garantisce l’accesso specifico dell’organizzazione a video inpaint/remix -- Restrizione opzionale: + - `alibaba`, `qwen`, `xai` perché questi percorsi al momento richiedono URL di riferimento remoti `http(s)` / MP4 + - `google` perché l’attuale corsia condivisa Gemini/Veo usa input locale buffer-backed e quel percorso non viene accettato nello sweep condiviso + - `openai` perché l’attuale corsia condivisa non garantisce accesso org-specific a video inpaint/remix +- Restrizione facoltativa: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` per includere ogni provider nello sweep predefinito, incluso FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` per ridurre il cap operativo di ogni provider in uno smoke run aggressivo -- Comportamento auth opzionale: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre l’auth dello store profili e ignorare gli override solo env + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` per ridurre il limite operativo di ogni provider in un’esecuzione smoke aggressiva +- Comportamento auth facoltativo: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre l’auth dal profile store e ignorare gli override solo-env ## Harness live media - Comando: `pnpm test:live:media` - Scopo: - - Esegue le suite live condivise di immagini, musica e video tramite un unico entrypoint nativo del repository + - Esegue le suite live condivise image, music e video tramite un unico entrypoint nativo del repo - Carica automaticamente le variabili env provider mancanti da `~/.profile` - - Per impostazione predefinita restringe automaticamente ogni suite ai provider che attualmente hanno auth utilizzabile - - Riutilizza `scripts/test-live.mjs`, così il comportamento di heartbeat e modalità silenziosa resta coerente + - Restringe automaticamente per impostazione predefinita ogni suite ai provider che al momento hanno auth utilizzabile + - Riutilizza `scripts/test-live.mjs`, così heartbeat e comportamento quiet-mode restano coerenti - Esempi: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Runner Docker (controlli opzionali “funziona su Linux”) +## Runner Docker (controlli facoltativi “funziona su Linux”) -Questi runner Docker si dividono in due gruppi: +Questi runner Docker sono divisi in due categorie: -- Runner live-model: `test:docker:live-models` e `test:docker:live-gateway` eseguono solo il rispettivo file live a chiavi profilo dentro l’immagine Docker del repository (`src/agents/models.profiles.live.test.ts` e `src/gateway/gateway-models.profiles.live.test.ts`), montando la tua directory di configurazione locale e il workspace (e leggendo `~/.profile` se montato). Gli entrypoint locali corrispondenti sono `test:live:models-profiles` e `test:live:gateway-profiles`. -- I runner live Docker usano per impostazione predefinita un cap smoke più piccolo così uno sweep Docker completo resta praticabile: +- Runner live-model: `test:docker:live-models` e `test:docker:live-gateway` eseguono solo il rispettivo file live con profile-key dentro l’immagine Docker del repo (`src/agents/models.profiles.live.test.ts` e `src/gateway/gateway-models.profiles.live.test.ts`), montando la tua directory config locale e il workspace (e leggendo `~/.profile` se montato). Gli entrypoint locali corrispondenti sono `test:live:models-profiles` e `test:live:gateway-profiles`. +- I runner live Docker usano per impostazione predefinita un limite smoke più piccolo così uno sweep Docker completo resta praticabile: `test:docker:live-models` usa per impostazione predefinita `OPENCLAW_LIVE_MAX_MODELS=12`, e `test:docker:live-gateway` usa per impostazione predefinita `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` e `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Sostituisci queste variabili env quando vuoi esplicitamente la scansione esaustiva più ampia. -- `test:docker:all` costruisce una volta l’immagine Docker live tramite `test:docker:live-build`, poi la riutilizza per le due lane Docker live. -- Runner smoke in container: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` e `test:docker:plugins` avviano uno o più container reali e verificano percorsi di integrazione di livello superiore. +- `test:docker:all` costruisce una sola volta l’immagine Docker live tramite `test:docker:live-build`, poi la riutilizza per le due corsie live Docker. +- Runner smoke del container: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` e `test:docker:plugins` avviano uno o più container reali e verificano percorsi di integrazione di livello superiore. -I runner Docker live-model montano inoltre solo le home auth CLI necessarie (o tutte quelle supportate quando l’esecuzione non è ristretta), poi le copiano nella home del container prima dell’esecuzione così l’OAuth delle CLI esterne può aggiornare i token senza modificare lo store auth dell’host: +I runner Docker live-model montano inoltre solo le home auth CLI necessarie (oppure tutte quelle supportate quando l’esecuzione non è ristretta), poi le copiano nella home del container prima dell’esecuzione così l’OAuth della CLI esterna può aggiornare i token senza modificare lo store auth dell’host: - Modelli diretti: `pnpm test:docker:live-models` (script: `scripts/test-live-models-docker.sh`) - Smoke ACP bind: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`) - Smoke backend CLI: `pnpm test:docker:live-cli-backend` (script: `scripts/test-live-cli-backend-docker.sh`) -- Smoke harness app-server Codex: `pnpm test:docker:live-codex-harness` (script: `scripts/test-live-codex-harness-docker.sh`) -- Gateway + agente dev: `pnpm test:docker:live-gateway` (script: `scripts/test-live-gateway-models-docker.sh`) +- Smoke harness Codex app-server: `pnpm test:docker:live-codex-harness` (script: `scripts/test-live-codex-harness-docker.sh`) +- Gateway + agent dev: `pnpm test:docker:live-gateway` (script: `scripts/test-live-gateway-models-docker.sh`) - Smoke live Open WebUI: `pnpm test:docker:openwebui` (script: `scripts/e2e/openwebui-docker.sh`) - Wizard di onboarding (TTY, scaffolding completo): `pnpm test:docker:onboard` (script: `scripts/e2e/onboard-docker.sh`) -- Networking del gateway (due container, auth WS + health): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) -- Bridge di canale MCP (Gateway seeded + bridge stdio + smoke raw Claude notification-frame): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) -- Plugin (smoke di installazione + alias `/plugin` + semantica di riavvio del bundle Claude): `pnpm test:docker:plugins` (script: `scripts/e2e/plugins-docker.sh`) +- Networking Gateway (due container, auth WS + health): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) +- Bridge canale MCP (Gateway seeded + bridge stdio + smoke raw Claude notification-frame): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) +- Plugin (smoke install + alias `/plugin` + semantica di riavvio Claude-bundle): `pnpm test:docker:plugins` (script: `scripts/e2e/plugins-docker.sh`) -I runner Docker live-model montano inoltre il checkout corrente in sola lettura e -lo preparano in una workdir temporanea dentro il container. Questo mantiene snella l’immagine -runtime pur eseguendo comunque Vitest sul tuo esatto source/config locale. -Il passaggio di staging salta grandi cache solo locali e output di build dell’app come -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` e directory di output `.build` o -Gradle locali all’app, così le esecuzioni live Docker non passano minuti a copiare +I runner Docker live-model montano anche il checkout corrente in sola lettura e +lo preparano in una workdir temporanea dentro il container. Questo mantiene +snella l’immagine runtime pur eseguendo comunque Vitest contro il tuo source/config locale esatto. +Il passaggio di staging salta grandi cache solo-locali e output di build delle app come +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` e directory di output locali `.build` o +Gradle, così le esecuzioni live Docker non passano minuti a copiare artifact specifici della macchina. -Impostano anche `OPENCLAW_SKIP_CHANNELS=1` così le probe live del gateway non avviano +Impostano anche `OPENCLAW_SKIP_CHANNELS=1` così le probe live Gateway non avviano worker di canale reali Telegram/Discord/ecc. dentro il container. -`test:docker:live-models` esegue comunque `pnpm test:live`, quindi inoltra anche -`OPENCLAW_LIVE_GATEWAY_*` quando hai bisogno di restringere o escludere la copertura -live del gateway da quella lane Docker. +`test:docker:live-models` esegue comunque `pnpm test:live`, quindi fai passare anche +`OPENCLAW_LIVE_GATEWAY_*` quando devi restringere o escludere la copertura live Gateway da quella corsia Docker. `test:docker:openwebui` è uno smoke di compatibilità di livello superiore: avvia un -container gateway OpenClaw con gli endpoint HTTP compatibili OpenAI abilitati, -avvia un container Open WebUI fissato verso quel gateway, esegue il sign-in tramite -Open WebUI, verifica che `/api/models` esponga `openclaw/default`, poi invia una -vera richiesta di chat tramite il proxy `/api/chat/completions` di Open WebUI. -La prima esecuzione può essere sensibilmente più lenta perché Docker potrebbe dover scaricare l’immagine -Open WebUI e Open WebUI potrebbe dover completare il proprio setup cold-start. -Questa lane si aspetta una chiave modello live utilizzabile, e `OPENCLAW_PROFILE_FILE` +container Gateway OpenClaw con gli endpoint HTTP compatibili OpenAI abilitati, +avvia un container Open WebUI fissato contro quel Gateway, effettua l’accesso tramite +Open WebUI, verifica che `/api/models` esponga `openclaw/default`, quindi invia una +vera richiesta chat tramite il proxy `/api/chat/completions` di Open WebUI. +La prima esecuzione può essere sensibilmente più lenta perché Docker potrebbe dover scaricare +l’immagine Open WebUI e Open WebUI potrebbe dover completare il proprio cold-start setup. +Questa corsia si aspetta una chiave di modello live utilizzabile, e `OPENCLAW_PROFILE_FILE` (`~/.profile` per impostazione predefinita) è il modo principale per fornirla nelle esecuzioni Dockerizzate. Le esecuzioni riuscite stampano un piccolo payload JSON come `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` è intenzionalmente deterministico e non richiede un -account reale Telegram, Discord o iMessage. Avvia un container Gateway -seeded, avvia un secondo container che esegue `openclaw mcp serve`, quindi -verifica discovery delle conversazioni instradate, letture dei transcript, metadati degli allegati, -comportamento della coda di eventi live, instradamento dell’invio outbound e notifiche di canale + -permesso in stile Claude tramite il vero bridge MCP stdio. Il controllo delle notifiche -ispeziona direttamente i frame MCP stdio grezzi così lo smoke valida ciò che il -bridge emette davvero, non solo ciò che un particolare SDK client rende visibile. +account reale Telegram, Discord o iMessage. Avvia un container Gateway seeded, +avvia un secondo container che esegue `openclaw mcp serve`, quindi +verifica discovery della conversazione instradata, letture del transcript, metadati degli allegati, +comportamento della coda eventi live, instradamento dell’invio in uscita e notifiche in stile Claude di canale + +permessi sul vero bridge MCP stdio. Il controllo delle notifiche +ispeziona direttamente i frame MCP stdio raw così lo smoke valida ciò che il +bridge emette davvero, non solo ciò che un particolare SDK client capita di esporre. -Smoke manuale ACP del thread in linguaggio naturale (non CI): +Smoke manuale ACP plain-language thread (non CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` - Mantieni questo script per i flussi di lavoro di regressione/debug. Potrebbe servire di nuovo per la validazione del routing dei thread ACP, quindi non eliminarlo. @@ -896,57 +892,58 @@ Variabili env utili: - `OPENCLAW_CONFIG_DIR=...` (predefinito: `~/.openclaw`) montata su `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (predefinito: `~/.openclaw/workspace`) montata su `/home/node/.openclaw/workspace` - `OPENCLAW_PROFILE_FILE=...` (predefinito: `~/.profile`) montata su `/home/node/.profile` e letta prima di eseguire i test +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` per verificare solo le variabili env lette da `OPENCLAW_PROFILE_FILE`, usando directory config/workspace temporanee e senza mount auth CLI esterni - `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (predefinito: `~/.cache/openclaw/docker-cli-tools`) montata su `/home/node/.npm-global` per installazioni CLI in cache dentro Docker -- Le directory/file auth CLI esterni sotto `$HOME` sono montati in sola lettura sotto `/host-auth...`, poi copiati in `/home/node/...` prima dell’avvio dei test +- Directory/file auth CLI esterni sotto `$HOME` vengono montati in sola lettura sotto `/host-auth...`, poi copiati in `/home/node/...` prima dell’avvio dei test - Directory predefinite: `.minimax` - File predefiniti: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - Le esecuzioni ristrette per provider montano solo le directory/file necessari dedotti da `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Override manuale con `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` o un elenco separato da virgole come `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - Override manuale con `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` oppure una lista separata da virgole come `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` per restringere l’esecuzione - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` per filtrare i provider nel container - `OPENCLAW_SKIP_DOCKER_BUILD=1` per riutilizzare un’immagine `openclaw:local-live` esistente per riesecuzioni che non richiedono una nuova build -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per assicurarsi che le credenziali provengano dallo store dei profili (non dall’env) -- `OPENCLAW_OPENWEBUI_MODEL=...` per scegliere il modello esposto dal gateway per lo smoke Open WebUI +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per assicurarsi che le credenziali provengano dal profile store (non da env) +- `OPENCLAW_OPENWEBUI_MODEL=...` per scegliere il modello esposto dal Gateway per lo smoke Open WebUI - `OPENCLAW_OPENWEBUI_PROMPT=...` per sostituire il prompt di controllo nonce usato dallo smoke Open WebUI -- `OPENWEBUI_IMAGE=...` per sostituire il tag dell’immagine Open WebUI fissata +- `OPENWEBUI_IMAGE=...` per sostituire il tag immagine Open WebUI fissato -## Controllo di integrità della documentazione +## Sanity della documentazione -Esegui i controlli della documentazione dopo modifiche ai documenti: `pnpm check:docs`. -Esegui la validazione completa degli anchor Mintlify quando ti servono anche i controlli sugli heading nella pagina: `pnpm docs:check-links:anchors`. +Esegui i controlli docs dopo modifiche alla documentazione: `pnpm check:docs`. +Esegui la validazione completa degli anchor Mintlify quando ti servono anche i controlli degli heading in-page: `pnpm docs:check-links:anchors`. ## Regressione offline (sicura per CI) -Queste sono regressioni della “pipeline reale” senza provider reali: +Queste sono regressioni di “pipeline reale” senza provider reali: -- Tool calling del gateway (mock OpenAI, vero gateway + loop agente): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Wizard del gateway (WS `wizard.start`/`wizard.next`, scrive config + auth enforced): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") +- Gateway tool calling (mock OpenAI, vero loop Gateway + agent): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Wizard Gateway (WS `wizard.start`/`wizard.next`, scrittura di config + auth applicata): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") -## Valutazioni di affidabilità dell’agente (Skills) +## Valutazioni di affidabilità dell’agent (Skills) -Abbiamo già alcuni test sicuri per CI che si comportano come “valutazioni di affidabilità dell’agente”: +Abbiamo già alcuni test sicuri per CI che si comportano come “valutazioni di affidabilità dell’agent”: -- Mock tool-calling attraverso il vero gateway + loop agente (`src/gateway/gateway.test.ts`). -- Flussi wizard end-to-end che validano il wiring della sessione e gli effetti di configurazione (`src/gateway/gateway.test.ts`). +- Mock del tool-calling tramite il vero loop Gateway + agent (`src/gateway/gateway.test.ts`). +- Flussi wizard end-to-end che validano wiring della sessione ed effetti della config (`src/gateway/gateway.test.ts`). -Cosa manca ancora per Skills (vedi [Skills](/it/tools/skills)): +Cosa manca ancora per le Skills (vedi [Skills](/it/tools/skills)): -- **Decisioning:** quando le Skills sono elencate nel prompt, l’agente sceglie la Skill giusta (o evita quelle irrilevanti)? -- **Compliance:** l’agente legge `SKILL.md` prima dell’uso e segue i passaggi/argomenti richiesti? +- **Decisioning:** quando le Skills sono elencate nel prompt, l’agent sceglie la Skill giusta (o evita quelle irrilevanti)? +- **Compliance:** l’agent legge `SKILL.md` prima dell’uso e segue i passaggi/argomenti richiesti? - **Workflow contracts:** scenari multi-turn che verificano ordine dei tool, persistenza della cronologia di sessione e boundary della sandbox. Le valutazioni future dovrebbero restare prima di tutto deterministiche: -- Un runner di scenari che usa provider mock per verificare chiamate dei tool + ordine, letture dei file Skill e wiring della sessione. -- Una piccola suite di scenari focalizzati sulle Skill (usare vs evitare, gating, prompt injection). -- Valutazioni live opzionali (opt-in, protette da env) solo dopo che la suite sicura per CI è in funzione. +- Un runner di scenari che usa provider mock per verificare chiamate ai tool + ordine, letture dei file Skill e wiring della sessione. +- Una piccola suite di scenari focalizzati sulle Skill (usa vs evita, gating, prompt injection). +- Valutazioni live facoltative (opt-in, controllate da env) solo dopo che la suite sicura per CI sarà pronta. -## Test di contratto (forma di plugin e canale) +## Test di contratto (forma di plugin e canali) -I test di contratto verificano che ogni plugin e canale registrato sia conforme al -proprio contratto di interfaccia. Iterano su tutti i plugin scoperti ed eseguono una suite di -asserzioni su forma e comportamento. La lane unit predefinita `pnpm test` -salta intenzionalmente questi file condivisi di seam e smoke; esegui i comandi di contratto esplicitamente +I test di contratto verificano che ogni plugin e canale registrato sia conforme al proprio +contratto di interfaccia. Iterano su tutti i plugin rilevati ed eseguono una suite di +verifiche su forma e comportamento. La corsia unit predefinita `pnpm test` +salta intenzionalmente questi file condivisi di seam e smoke; esegui esplicitamente i comandi di contratto quando tocchi superfici condivise di canale o provider. ### Comandi @@ -957,55 +954,55 @@ quando tocchi superfici condivise di canale o provider. ### Contratti dei canali -Si trovano in `src/channels/plugins/contracts/*.contract.test.ts`: +Situati in `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Forma di base del plugin (id, nome, capability) -- **setup** - Contratto del wizard di configurazione -- **session-binding** - Comportamento del binding di sessione +- **plugin** - Forma base del plugin (id, nome, capability) +- **setup** - Contratto del wizard di setup +- **session-binding** - Comportamento del session binding - **outbound-payload** - Struttura del payload del messaggio -- **inbound** - Gestione dei messaggi inbound +- **inbound** - Gestione dei messaggi in ingresso - **actions** - Handler delle azioni del canale -- **threading** - Gestione degli ID thread +- **threading** - Gestione degli id thread - **directory** - API directory/roster - **group-policy** - Applicazione della policy di gruppo -### Contratti di stato del provider +### Contratti di stato dei provider -Si trovano in `src/plugins/contracts/*.contract.test.ts`. +Situati in `src/plugins/contracts/*.contract.test.ts`. - **status** - Probe di stato del canale - **registry** - Forma del registry del plugin ### Contratti dei provider -Si trovano in `src/plugins/contracts/*.contract.test.ts`: +Situati in `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Contratto del flusso auth +- **auth** - Contratto del flusso di auth - **auth-choice** - Scelta/selezione auth -- **catalog** - API del catalogo dei modelli +- **catalog** - API del catalogo modelli - **discovery** - Discovery del plugin - **loader** - Caricamento del plugin - **runtime** - Runtime del provider - **shape** - Forma/interfaccia del plugin -- **wizard** - Wizard di configurazione +- **wizard** - Wizard di setup ### Quando eseguirli -- Dopo aver modificato export o subpath di plugin-sdk +- Dopo modifiche a export o subpath di plugin-sdk - Dopo aver aggiunto o modificato un plugin canale o provider -- Dopo aver refattorizzato la registrazione o la discovery dei plugin +- Dopo refactor della registrazione o discovery dei plugin I test di contratto vengono eseguiti in CI e non richiedono chiavi API reali. ## Aggiungere regressioni (linee guida) -Quando risolvi un problema di provider/modello scoperto in live: +Quando correggi un problema di provider/modello scoperto in live: -- Aggiungi una regressione sicura per CI se possibile (provider mock/stub oppure acquisisci l’esatta trasformazione della forma della richiesta) -- Se è intrinsecamente solo live (rate limit, policy auth), mantieni il test live ristretto e opt-in tramite variabili env -- Preferisci mirare al livello più piccolo che intercetta il bug: - - bug di conversione/replay della richiesta del provider → test diretto dei modelli - - bug della pipeline di sessione/cronologia/tool del gateway → smoke live del gateway o test mock del gateway sicuro per CI +- Aggiungi, se possibile, una regressione sicura per CI (provider mock/stub, oppure cattura della trasformazione esatta della forma della richiesta) +- Se è intrinsecamente solo-live (rate limit, policy auth), mantieni il test live ristretto e opt-in tramite variabili env +- Preferisci puntare al livello più piccolo che intercetta il bug: + - bug di conversione/replay della richiesta del provider → test direct models + - bug della pipeline session/history/tool del Gateway → smoke live Gateway o test mock Gateway sicuro per CI - Guardrail di attraversamento SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva un target campionato per classe SecretRef dai metadati del registry (`listSecretTargetRegistryEntries()`), poi verifica che gli id exec dei segmenti di attraversamento siano rifiutati. - - Se aggiungi una nuova famiglia di target SecretRef `includeInPlan` in `src/secrets/target-registry-data.ts`, aggiorna `classifyTargetClass` in quel test. Il test fallisce intenzionalmente sugli id target non classificati così le nuove classi non possono essere saltate in silenzio. + - `src/secrets/exec-secret-ref-id-parity.test.ts` ricava un target campionato per classe SecretRef dai metadati del registry (`listSecretTargetRegistryEntries()`), quindi verifica che gli id exec dei segmenti di attraversamento vengano rifiutati. + - Se aggiungi una nuova famiglia di target SecretRef `includeInPlan` in `src/secrets/target-registry-data.ts`, aggiorna `classifyTargetClass` in quel test. Il test fallisce intenzionalmente su id target non classificati così le nuove classi non possono essere saltate in silenzio. diff --git a/docs/it/providers/github-copilot.md b/docs/it/providers/github-copilot.md index be794a01f..9ed1648ae 100644 --- a/docs/it/providers/github-copilot.md +++ b/docs/it/providers/github-copilot.md @@ -1,28 +1,27 @@ --- read_when: - - Vuoi usare GitHub Copilot come provider di modelli - - Ti serve il flusso `openclaw models auth login-github-copilot` -summary: Accedi a GitHub Copilot da OpenClaw usando il flusso del dispositivo + - Vuoi utilizzare GitHub Copilot come provider di modelli + - Hai bisogno del flusso `openclaw models auth login-github-copilot` +summary: Accedi a GitHub Copilot da OpenClaw utilizzando il flusso del dispositivo title: GitHub Copilot x-i18n: - generated_at: "2026-04-12T23:30:31Z" + generated_at: "2026-04-15T14:40:28Z" model: gpt-5.4 provider: openai - source_hash: 51fee006e7d4e78e37b0c29356b0090b132de727d99b603441767d3fb642140b + source_hash: b8258fecff22fb73b057de878462941f6eb86d0c5f775c5eac4840e95ba5eccf source_path: providers/github-copilot.md workflow: 15 --- # GitHub Copilot -GitHub Copilot è l’assistente di coding con IA di GitHub. Fornisce accesso ai modelli Copilot per il tuo account e piano GitHub. OpenClaw può usare Copilot come provider di modelli in due modi diversi. +GitHub Copilot è l'assistente di coding con IA di GitHub. Fornisce accesso ai modelli di Copilot per il tuo account e piano GitHub. OpenClaw può utilizzare Copilot come provider di modelli in due modi diversi. ## Due modi per usare Copilot in OpenClaw - Usa il flusso di accesso nativo del dispositivo per ottenere un token GitHub, quindi scambialo con - token API Copilot quando OpenClaw è in esecuzione. Questo è il percorso **predefinito** e più semplice + Usa il flusso di accesso al dispositivo nativo per ottenere un token GitHub, quindi scambiarlo con token API Copilot quando OpenClaw è in esecuzione. Questo è il percorso **predefinito** e più semplice perché non richiede VS Code. @@ -32,7 +31,7 @@ GitHub Copilot è l’assistente di coding con IA di GitHub. Fornisce accesso ai ``` Ti verrà chiesto di visitare un URL e inserire un codice monouso. Tieni il - terminale aperto finché l’operazione non è completata. + terminale aperto fino al completamento. ```bash @@ -52,12 +51,12 @@ GitHub Copilot è l’assistente di coding con IA di GitHub. Fornisce accesso ai - Usa l’estensione VS Code **Copilot Proxy** come bridge locale. OpenClaw comunica con - l’endpoint `/v1` del proxy e usa l’elenco di modelli che configuri lì. + Usa l'estensione VS Code **Copilot Proxy** come bridge locale. OpenClaw comunica con + l'endpoint `/v1` del proxy e usa l'elenco di modelli che configuri lì. - Scegli questa opzione se usi già Copilot Proxy in VS Code o se devi instradare - attraverso di esso. Devi abilitare il plugin e mantenere in esecuzione l’estensione VS Code. + Scegli questa opzione se esegui già Copilot Proxy in VS Code o hai bisogno di instradare + attraverso di esso. Devi abilitare il Plugin e mantenere in esecuzione l'estensione VS Code. @@ -65,22 +64,22 @@ GitHub Copilot è l’assistente di coding con IA di GitHub. Fornisce accesso ai ## Flag facoltativi -| Flag | Description | +| Flag | Descrizione | | --------------- | --------------------------------------------------- | | `--yes` | Salta il prompt di conferma | -| `--set-default` | Applica anche il modello predefinito consigliato dal provider | +| `--set-default` | Applica anche il modello predefinito consigliato del provider | ```bash # Salta la conferma openclaw models auth login-github-copilot --yes -# Accedi e imposta il modello predefinito in un solo passaggio +# Accedi e imposta il modello predefinito in un unico passaggio openclaw models auth login --provider github-copilot --method device --set-default ``` - Il flusso di accesso del dispositivo richiede un TTY interattivo. Eseguilo direttamente in un + Il flusso di accesso al dispositivo richiede un TTY interattivo. Eseguilo direttamente in un terminale, non in uno script non interattivo o in una pipeline CI. @@ -95,42 +94,82 @@ openclaw models auth login --provider github-copilot --method device --set-defau seleziona il trasporto corretto in base al riferimento del modello. - - OpenClaw risolve l’autenticazione Copilot dalle variabili d’ambiente nel seguente + + OpenClaw risolve l'autenticazione Copilot dalle variabili di ambiente nel seguente ordine di priorità: - | Priority | Variable | Notes | - | -------- | --------------------- | -------------------------------- | - | 1 | `COPILOT_GITHUB_TOKEN` | Priorità massima, specifico per Copilot | - | 2 | `GH_TOKEN` | Token GitHub CLI (fallback) | + | Priorità | Variabile | Note | + | -------- | --------------------- | ------------------------------------ | + | 1 | `COPILOT_GITHUB_TOKEN` | Priorità più alta, specifica per Copilot | + | 2 | `GH_TOKEN` | Token GitHub CLI (fallback) | | 3 | `GITHUB_TOKEN` | Token GitHub standard (priorità più bassa) | - Quando sono impostate più variabili, OpenClaw usa quella con priorità più alta. - Il flusso di accesso del dispositivo (`openclaw models auth login-github-copilot`) memorizza - il suo token nell’archivio dei profili di autenticazione e ha la precedenza su tutte le - variabili d’ambiente. + Quando sono impostate più variabili, OpenClaw usa quella con la priorità più alta. + Il flusso di accesso al dispositivo (`openclaw models auth login-github-copilot`) memorizza + il suo token nell'archivio dei profili di autenticazione e ha la precedenza su tutte le variabili + di ambiente. - L’accesso memorizza un token GitHub nell’archivio dei profili di autenticazione e lo scambia - con un token API Copilot quando OpenClaw è in esecuzione. Non devi gestire il + L'accesso memorizza un token GitHub nell'archivio dei profili di autenticazione e lo scambia + con un token API Copilot quando OpenClaw è in esecuzione. Non è necessario gestire il token manualmente. Richiede un TTY interattivo. Esegui il comando di accesso direttamente in un terminale, non -all’interno di uno script headless o di un job CI. +all'interno di uno script headless o di un processo CI. +## Embedding per la ricerca nella memoria + +GitHub Copilot può anche fungere da provider di embedding per la +[ricerca nella memoria](/it/concepts/memory-search). Se hai un abbonamento Copilot e +hai effettuato l'accesso, OpenClaw può usarlo per gli embedding senza una chiave API separata. + +### Rilevamento automatico + +Quando `memorySearch.provider` è `"auto"` (il valore predefinito), GitHub Copilot viene provato +con priorità 15 -- dopo gli embedding locali ma prima di OpenAI e altri provider +a pagamento. Se è disponibile un token GitHub, OpenClaw rileva i modelli di +embedding disponibili dall'API Copilot e sceglie automaticamente il migliore. + +### Configurazione esplicita + +```json5 +{ + agents: { + defaults: { + memorySearch: { + provider: "github-copilot", + // Facoltativo: sostituisce il modello rilevato automaticamente + model: "text-embedding-3-small", + }, + }, + }, +} +``` + +### Come funziona + +1. OpenClaw risolve il tuo token GitHub (dalle variabili di ambiente o dal profilo di autenticazione). +2. Lo scambia con un token API Copilot a breve durata. +3. Interroga l'endpoint Copilot `/models` per rilevare i modelli di embedding disponibili. +4. Sceglie il modello migliore (preferisce `text-embedding-3-small`). +5. Invia le richieste di embedding all'endpoint Copilot `/embeddings`. + +La disponibilità dei modelli dipende dal tuo piano GitHub. Se non sono disponibili modelli di embedding, +OpenClaw salta Copilot e prova il provider successivo. + ## Correlati - Scelta dei provider, dei riferimenti di modello e del comportamento di failover. + Scelta dei provider, dei riferimenti dei modelli e del comportamento di failover. - Dettagli di autenticazione e regole di riutilizzo delle credenziali. + Dettagli sull'autenticazione e regole di riutilizzo delle credenziali. diff --git a/docs/it/providers/ollama.md b/docs/it/providers/ollama.md index f8cacc031..f296d08ff 100644 --- a/docs/it/providers/ollama.md +++ b/docs/it/providers/ollama.md @@ -1,50 +1,49 @@ --- read_when: - Vuoi eseguire OpenClaw con modelli cloud o locali tramite Ollama - - Hai bisogno di istruzioni per la configurazione e il setup di Ollama + - Hai bisogno di indicazioni per la configurazione e l’impostazione di Ollama summary: Esegui OpenClaw con Ollama (modelli cloud e locali) title: Ollama x-i18n: - generated_at: "2026-04-12T23:31:46Z" + generated_at: "2026-04-15T14:40:51Z" model: gpt-5.4 provider: openai - source_hash: ec796241b884ca16ec7077df4f3f1910e2850487bb3ea94f8fdb37c77e02b219 + source_hash: 098e083e0fc484bddb5270eb630c55d7832039b462d1710372b6afece5cefcdf source_path: providers/ollama.md workflow: 15 --- # Ollama -Ollama è un runtime LLM locale che rende semplice eseguire modelli open source sulla tua macchina. OpenClaw si integra con l’API nativa di Ollama (`/api/chat`), supporta lo streaming e il tool calling, e può rilevare automaticamente i modelli Ollama locali quando abiliti questa opzione con `OLLAMA_API_KEY` (o un profilo auth) e non definisci una voce esplicita `models.providers.ollama`. +OpenClaw si integra con l'API nativa di Ollama (`/api/chat`) per modelli cloud ospitati e server Ollama locali/self-hosted. Puoi usare Ollama in tre modalità: `Cloud + Local` tramite un host Ollama raggiungibile, `Cloud only` contro `https://ollama.com`, oppure `Local only` contro un host Ollama raggiungibile. -**Utenti di Ollama remoto**: non usare l’URL compatibile OpenAI `/v1` (`http://host:11434/v1`) con OpenClaw. Questo interrompe il tool calling e i modelli potrebbero produrre JSON degli strumenti grezzo come testo normale. Usa invece l’URL dell’API nativa di Ollama: `baseUrl: "http://host:11434"` (senza `/v1`). +**Utenti di Ollama remoto**: non usare l'URL OpenAI-compatible `/v1` (`http://host:11434/v1`) con OpenClaw. Questo interrompe il tool calling e i modelli possono produrre JSON di strumenti grezzo come testo normale. Usa invece l'URL dell'API nativa di Ollama: `baseUrl: "http://host:11434"` (senza `/v1`). ## Per iniziare -Scegli il metodo di configurazione e la modalità che preferisci. +Scegli il metodo e la modalità di configurazione che preferisci. - **Ideale per:** il percorso più rapido verso una configurazione Ollama funzionante con rilevamento automatico dei modelli. + **Ideale per:** il percorso più rapido verso una configurazione funzionante di Ollama cloud o locale. - + ```bash openclaw onboard ``` - Seleziona **Ollama** dall’elenco dei provider. + Seleziona **Ollama** dall'elenco dei provider. - - **Cloud + Local** — modelli ospitati nel cloud e modelli locali insieme - - **Local** — solo modelli locali - - Se scegli **Cloud + Local** e non hai effettuato l’accesso a ollama.com, l’onboarding apre un flusso di accesso nel browser. + - **Cloud + Local** — host Ollama locale più modelli cloud instradati tramite quell'host + - **Cloud only** — modelli Ollama ospitati tramite `https://ollama.com` + - **Local only** — solo modelli locali - L’onboarding rileva i modelli disponibili e suggerisce i valori predefiniti. Scarica automaticamente il modello selezionato se non è disponibile localmente. + `Cloud only` richiede `OLLAMA_API_KEY` e suggerisce valori predefiniti cloud ospitati. `Cloud + Local` e `Local only` richiedono un URL base di Ollama, individuano i modelli disponibili ed eseguono automaticamente il pull del modello locale selezionato se non è ancora disponibile. `Cloud + Local` controlla anche se quell'host Ollama ha effettuato l'accesso per l'accesso cloud. ```bash @@ -61,7 +60,7 @@ Scegli il metodo di configurazione e la modalità che preferisci. --accept-risk ``` - Facoltativamente puoi specificare un URL base personalizzato o un modello: + Facoltativamente, specifica un URL base o un modello personalizzato: ```bash openclaw onboard --non-interactive \ @@ -74,13 +73,15 @@ Scegli il metodo di configurazione e la modalità che preferisci. - **Ideale per:** pieno controllo su installazione, download dei modelli e configurazione. + **Ideale per:** controllo completo sulla configurazione cloud o locale. - - Scaricalo da [ollama.com/download](https://ollama.com/download). + + - **Cloud + Local**: installa Ollama, accedi con `ollama signin` e instrada le richieste cloud tramite quell'host + - **Cloud only**: usa `https://ollama.com` con un `OLLAMA_API_KEY` + - **Local only**: installa Ollama da [ollama.com/download](https://ollama.com/download) - + ```bash ollama pull gemma4 # oppure @@ -89,25 +90,21 @@ Scegli il metodo di configurazione e la modalità che preferisci. ollama pull llama3.3 ``` - - Se vuoi anche i modelli cloud: - - ```bash - ollama signin - ``` - - Imposta un valore qualsiasi per la chiave API (Ollama non richiede una chiave reale): + Per `Cloud only`, usa il tuo `OLLAMA_API_KEY` reale. Per le configurazioni basate su host, va bene qualsiasi valore segnaposto: ```bash - # Imposta la variabile d’ambiente + # Cloud + export OLLAMA_API_KEY="your-ollama-api-key" + + # Solo locale export OLLAMA_API_KEY="ollama-local" - # Oppure configuralo nel file di configurazione - openclaw config set models.providers.ollama.apiKey "ollama-local" + # Oppure configura nel file di configurazione + openclaw config set models.providers.ollama.apiKey "OLLAMA_API_KEY" ``` - + ```bash openclaw models list openclaw models set ollama/gemma4 @@ -134,38 +131,43 @@ Scegli il metodo di configurazione e la modalità che preferisci. - I modelli cloud ti permettono di eseguire modelli ospitati nel cloud insieme ai tuoi modelli locali. Esempi includono `kimi-k2.5:cloud`, `minimax-m2.7:cloud` e `glm-5.1:cloud` -- questi **non** richiedono un `ollama pull` locale. + `Cloud + Local` usa un host Ollama raggiungibile come punto di controllo sia per i modelli locali sia per quelli cloud. Questo è il flusso ibrido preferito da Ollama. - Seleziona la modalità **Cloud + Local** durante la configurazione. La procedura guidata verifica se hai effettuato l’accesso e apre un flusso di accesso nel browser quando necessario. Se l’autenticazione non può essere verificata, la procedura guidata torna ai valori predefiniti dei modelli locali. + Usa **Cloud + Local** durante la configurazione. OpenClaw richiede l'URL base di Ollama, individua i modelli locali da quell'host e controlla se l'host ha effettuato l'accesso per l'accesso cloud con `ollama signin`. Quando l'host ha effettuato l'accesso, OpenClaw suggerisce anche valori predefiniti cloud ospitati come `kimi-k2.5:cloud`, `minimax-m2.7:cloud` e `glm-5.1:cloud`. - Puoi anche accedere direttamente su [ollama.com/signin](https://ollama.com/signin). - - OpenClaw attualmente suggerisce questi valori predefiniti cloud: `kimi-k2.5:cloud`, `minimax-m2.7:cloud`, `glm-5.1:cloud`. + Se l'host non ha ancora effettuato l'accesso, OpenClaw mantiene la configurazione in modalità solo locale finché non esegui `ollama signin`. - - In modalità solo locale, OpenClaw rileva i modelli dall’istanza locale di Ollama. Non è necessario alcun accesso cloud. + + `Cloud only` viene eseguito contro l'API ospitata di Ollama su `https://ollama.com`. + + Usa **Cloud only** durante la configurazione. OpenClaw richiede `OLLAMA_API_KEY`, imposta `baseUrl: "https://ollama.com"` e inizializza l'elenco dei modelli cloud ospitati. Questo percorso **non** richiede un server Ollama locale né `ollama signin`. + + + + + In modalità solo locale, OpenClaw individua i modelli dall'istanza Ollama configurata. Questo percorso è destinato a server Ollama locali o self-hosted. OpenClaw attualmente suggerisce `gemma4` come valore predefinito locale. -## Rilevamento dei modelli (provider implicito) +## Individuazione dei modelli (provider implicito) -Quando imposti `OLLAMA_API_KEY` (o un profilo auth) e **non** definisci `models.providers.ollama`, OpenClaw rileva i modelli dall’istanza locale di Ollama all’indirizzo `http://127.0.0.1:11434`. +Quando imposti `OLLAMA_API_KEY` (o un profilo di autenticazione) e **non** definisci `models.providers.ollama`, OpenClaw individua i modelli dall'istanza Ollama locale su `http://127.0.0.1:11434`. -| Comportamento | Dettaglio | -| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Query del catalogo | Interroga `/api/tags` | -| Rilevamento capacità | Usa lookup `/api/show` best-effort per leggere `contextWindow` e rilevare le capacità (inclusa la vision) | -| Modelli vision | I modelli con capacità `vision` riportata da `/api/show` sono contrassegnati come capaci di elaborare immagini (`input: ["text", "image"]`), quindi OpenClaw inietta automaticamente le immagini nel prompt | -| Rilevamento reasoning | Contrassegna `reasoning` con un’euristica basata sul nome del modello (`r1`, `reasoning`, `think`) | -| Limiti di token | Imposta `maxTokens` sul limite massimo predefinito di token Ollama usato da OpenClaw | -| Costi | Imposta tutti i costi a `0` | +| Comportamento | Dettaglio | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Query del catalogo | Interroga `/api/tags` | +| Rilevamento delle capacità | Usa richieste `/api/show` best-effort per leggere `contextWindow` e rilevare le capacità (inclusa la visione) | +| Modelli vision | I modelli con capacità `vision` riportata da `/api/show` vengono contrassegnati come capaci di elaborare immagini (`input: ["text", "image"]`), quindi OpenClaw inserisce automaticamente le immagini nel prompt | +| Rilevamento del reasoning | Contrassegna `reasoning` con un'euristica basata sul nome del modello (`r1`, `reasoning`, `think`) | +| Limiti di token | Imposta `maxTokens` al limite massimo di token predefinito di Ollama usato da OpenClaw | +| Costi | Imposta tutti i costi a `0` | -Questo evita voci manuali dei modelli mantenendo il catalogo allineato con l’istanza Ollama locale. +Questo evita inserimenti manuali dei modelli mantenendo il catalogo allineato con l'istanza Ollama locale. ```bash # Vedi quali modelli sono disponibili @@ -173,54 +175,54 @@ ollama list openclaw models list ``` -Per aggiungere un nuovo modello, scaricalo semplicemente con Ollama: +Per aggiungere un nuovo modello, esegui semplicemente il pull con Ollama: ```bash ollama pull mistral ``` -Il nuovo modello verrà rilevato automaticamente e sarà disponibile per l’uso. +Il nuovo modello verrà individuato automaticamente e sarà disponibile per l'uso. -Se imposti esplicitamente `models.providers.ollama`, il rilevamento automatico viene saltato e devi definire i modelli manualmente. Vedi la sezione della configurazione esplicita qui sotto. +Se imposti `models.providers.ollama` esplicitamente, l'individuazione automatica viene saltata e devi definire i modelli manualmente. Vedi la sezione sulla configurazione esplicita qui sotto. ## Configurazione - - Il modo più semplice per abilitare Ollama è tramite variabile d’ambiente: + + Il percorso di abilitazione solo locale più semplice avviene tramite variabile d'ambiente: ```bash export OLLAMA_API_KEY="ollama-local" ``` - Se `OLLAMA_API_KEY` è impostata, puoi omettere `apiKey` nella voce del provider e OpenClaw la compilerà per i controlli di disponibilità. + Se `OLLAMA_API_KEY` è impostato, puoi omettere `apiKey` nella voce del provider e OpenClaw lo userà per i controlli di disponibilità. - Usa la configurazione esplicita quando Ollama è in esecuzione su un altro host/porta, vuoi forzare finestre di contesto o elenchi di modelli specifici, oppure vuoi definizioni dei modelli completamente manuali. + Usa la configurazione esplicita quando vuoi una configurazione cloud ospitata, Ollama è in esecuzione su un altro host/porta, vuoi forzare finestre di contesto o elenchi di modelli specifici, oppure vuoi definizioni di modelli completamente manuali. ```json5 { models: { providers: { ollama: { - baseUrl: "http://ollama-host:11434", - apiKey: "ollama-local", + baseUrl: "https://ollama.com", + apiKey: "OLLAMA_API_KEY", api: "ollama", models: [ { - id: "gpt-oss:20b", - name: "GPT-OSS 20B", + id: "kimi-k2.5:cloud", + name: "kimi-k2.5:cloud", reasoning: false, - input: ["text"], + input: ["text", "image"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, - contextWindow: 8192, - maxTokens: 8192 * 10 + contextWindow: 128000, + maxTokens: 8192 } ] } @@ -232,7 +234,7 @@ Se imposti esplicitamente `models.providers.ollama`, il rilevamento automatico v - Se Ollama è in esecuzione su un host o una porta diversi (la configurazione esplicita disabilita il rilevamento automatico, quindi definisci i modelli manualmente): + Se Ollama è in esecuzione su un host o una porta diversi (la configurazione esplicita disabilita l'individuazione automatica, quindi definisci i modelli manualmente): ```json5 { @@ -240,8 +242,8 @@ Se imposti esplicitamente `models.providers.ollama`, il rilevamento automatico v providers: { ollama: { apiKey: "ollama-local", - baseUrl: "http://ollama-host:11434", // Nessun /v1 - usa l’URL dell’API nativa di Ollama - api: "ollama", // Impostalo esplicitamente per garantire il comportamento nativo del tool calling + baseUrl: "http://ollama-host:11434", // Nessun /v1 - usa l'URL dell'API nativa di Ollama + api: "ollama", // Impostalo esplicitamente per garantire il comportamento nativo di tool-calling }, }, }, @@ -249,7 +251,7 @@ Se imposti esplicitamente `models.providers.ollama`, il rilevamento automatico v ``` - Non aggiungere `/v1` all’URL. Il percorso `/v1` usa la modalità compatibile OpenAI, in cui il tool calling non è affidabile. Usa l’URL base di Ollama senza suffisso di percorso. + Non aggiungere `/v1` all'URL. Il percorso `/v1` usa la modalità OpenAI-compatible, in cui il tool calling non è affidabile. Usa l'URL base di Ollama senza suffissi nel percorso. @@ -276,11 +278,11 @@ Una volta configurato, tutti i tuoi modelli Ollama sono disponibili: OpenClaw supporta **Ollama Web Search** come provider `web_search` incluso. -| Proprietà | Dettaglio | -| ----------- | --------------------------------------------------------------------------------------------------------------------- | -| Host | Usa l’host Ollama configurato (`models.providers.ollama.baseUrl` quando impostato, altrimenti `http://127.0.0.1:11434`) | -| Auth | Nessuna chiave richiesta | -| Requisito | Ollama deve essere in esecuzione e con accesso effettuato tramite `ollama signin` | +| Proprietà | Dettaglio | +| ----------- | ------------------------------------------------------------------------------------------------------------------- | +| Host | Usa il tuo host Ollama configurato (`models.providers.ollama.baseUrl` quando impostato, altrimenti `http://127.0.0.1:11434`) | +| Autenticazione | Senza chiave | +| Requisito | Ollama deve essere in esecuzione e avere effettuato l'accesso con `ollama signin` | Scegli **Ollama Web Search** durante `openclaw onboard` o `openclaw configure --section web`, oppure imposta: @@ -297,18 +299,18 @@ Scegli **Ollama Web Search** durante `openclaw onboard` o `openclaw configure -- ``` -Per i dettagli completi di configurazione e comportamento, vedi [Ollama Web Search](/it/tools/ollama-search). +Per tutti i dettagli su configurazione e comportamento, vedi [Ollama Web Search](/it/tools/ollama-search). ## Configurazione avanzata - + - **Il tool calling non è affidabile in modalità compatibile OpenAI.** Usa questa modalità solo se ti serve il formato OpenAI per un proxy e non dipendi dal comportamento nativo del tool calling. + **Il tool calling non è affidabile nella modalità OpenAI-compatible.** Usa questa modalità solo se hai bisogno del formato OpenAI per un proxy e non dipendi dal comportamento nativo di tool calling. - Se invece devi usare l’endpoint compatibile OpenAI (ad esempio dietro un proxy che supporta solo il formato OpenAI), imposta esplicitamente `api: "openai-completions"`: + Se invece devi usare l'endpoint OpenAI-compatible (ad esempio dietro un proxy che supporta solo il formato OpenAI), imposta `api: "openai-completions"` esplicitamente: ```json5 { @@ -326,9 +328,9 @@ Per i dettagli completi di configurazione e comportamento, vedi [Ollama Web Sear } ``` - Questa modalità potrebbe non supportare contemporaneamente streaming e tool calling. Potrebbe essere necessario disabilitare lo streaming con `params: { streaming: false }` nella configurazione del modello. + Questa modalità potrebbe non supportare simultaneamente streaming e tool calling. Potrebbe essere necessario disabilitare lo streaming con `params: { streaming: false }` nella configurazione del modello. - Quando `api: "openai-completions"` viene usato con Ollama, OpenClaw inietta `options.num_ctx` per default così Ollama non torna silenziosamente a una finestra di contesto di 4096. Se il tuo proxy/upstream rifiuta campi `options` sconosciuti, disabilita questo comportamento: + Quando `api: "openai-completions"` viene usato con Ollama, OpenClaw inserisce `options.num_ctx` per impostazione predefinita così Ollama non torna silenziosamente a una finestra di contesto di 4096. Se il tuo proxy/upstream rifiuta campi `options` sconosciuti, disabilita questo comportamento: ```json5 { @@ -349,9 +351,9 @@ Per i dettagli completi di configurazione e comportamento, vedi [Ollama Web Sear - Per i modelli rilevati automaticamente, OpenClaw usa la finestra di contesto riportata da Ollama quando disponibile, altrimenti torna alla finestra di contesto predefinita di Ollama usata da OpenClaw. + Per i modelli individuati automaticamente, OpenClaw usa la finestra di contesto riportata da Ollama quando disponibile, altrimenti usa come fallback la finestra di contesto predefinita di Ollama usata da OpenClaw. - Puoi sostituire `contextWindow` e `maxTokens` nella configurazione esplicita del provider: + Puoi sovrascrivere `contextWindow` e `maxTokens` nella configurazione esplicita del provider: ```json5 { @@ -374,7 +376,7 @@ Per i dettagli completi di configurazione e comportamento, vedi [Ollama Web Sear - OpenClaw tratta per default come capaci di reasoning i modelli con nomi come `deepseek-r1`, `reasoning` o `think`. + OpenClaw considera per impostazione predefinita come capaci di reasoning i modelli con nomi come `deepseek-r1`, `reasoning` o `think`. ```bash ollama pull deepseek-r1:32b @@ -385,18 +387,18 @@ Per i dettagli completi di configurazione e comportamento, vedi [Ollama Web Sear - Ollama è gratuito e viene eseguito localmente, quindi tutti i costi dei modelli sono impostati a $0. Questo vale sia per i modelli rilevati automaticamente sia per quelli definiti manualmente. + Ollama è gratuito e viene eseguito localmente, quindi tutti i costi dei modelli sono impostati a $0. Questo vale sia per i modelli individuati automaticamente sia per quelli definiti manualmente. Il Plugin Ollama incluso registra un provider di embedding della memoria per - la [ricerca nella memoria](/it/concepts/memory). Usa l’URL base - e la chiave API Ollama configurati. + la [ricerca nella memoria](/it/concepts/memory). Usa l'URL base di Ollama + configurato e la chiave API. | Proprietà | Valore | | -------------- | ------------------- | | Modello predefinito | `nomic-embed-text` | - | Download automatico | Sì — il modello di embedding viene scaricato automaticamente se non è presente localmente | + | Pull automatico | Sì — il modello di embedding viene scaricato automaticamente se non è presente in locale | Per selezionare Ollama come provider di embedding per la ricerca nella memoria: @@ -413,10 +415,10 @@ Per i dettagli completi di configurazione e comportamento, vedi [Ollama Web Sear - L’integrazione Ollama di OpenClaw usa per default l’**API nativa di Ollama** (`/api/chat`), che supporta pienamente streaming e tool calling simultaneamente. Non è necessaria alcuna configurazione speciale. + L'integrazione Ollama di OpenClaw usa per impostazione predefinita l'**API nativa di Ollama** (`/api/chat`), che supporta pienamente streaming e tool calling simultaneamente. Non è necessaria alcuna configurazione speciale. - Se devi usare l’endpoint compatibile OpenAI, vedi la sezione "Modalità legacy compatibile OpenAI" qui sopra. In quella modalità, streaming e tool calling potrebbero non funzionare contemporaneamente. + Se devi usare l'endpoint OpenAI-compatible, consulta la sezione "Modalità legacy OpenAI-compatible" sopra. Streaming e tool calling potrebbero non funzionare contemporaneamente in quella modalità. @@ -426,13 +428,13 @@ Per i dettagli completi di configurazione e comportamento, vedi [Ollama Web Sear - Assicurati che Ollama sia in esecuzione, di aver impostato `OLLAMA_API_KEY` (o un profilo auth) e di **non** aver definito una voce esplicita `models.providers.ollama`: + Assicurati che Ollama sia in esecuzione, di aver impostato `OLLAMA_API_KEY` (o un profilo di autenticazione) e di **non** aver definito una voce esplicita `models.providers.ollama`: ```bash ollama serve ``` - Verifica che l’API sia accessibile: + Verifica che l'API sia accessibile: ```bash curl http://localhost:11434/api/tags @@ -441,7 +443,7 @@ Per i dettagli completi di configurazione e comportamento, vedi [Ollama Web Sear - Se il tuo modello non è elencato, scaricalo localmente oppure definiscilo esplicitamente in `models.providers.ollama`. + Se il tuo modello non è elencato, esegui il pull del modello in locale oppure definiscilo esplicitamente in `models.providers.ollama`. ```bash ollama list # Vedi cosa è installato @@ -467,20 +469,20 @@ Per i dettagli completi di configurazione e comportamento, vedi [Ollama Web Sear -Altro aiuto: [Risoluzione dei problemi](/it/help/troubleshooting) e [FAQ](/it/help/faq). +Ulteriore aiuto: [Risoluzione dei problemi](/it/help/troubleshooting) e [FAQ](/it/help/faq). ## Correlati - Panoramica di tutti i provider, riferimenti ai modelli e comportamento di failover. + Panoramica di tutti i provider, dei riferimenti ai modelli e del comportamento di failover. Come scegliere e configurare i modelli. - Dettagli completi di configurazione e comportamento per la ricerca web supportata da Ollama. + Dettagli completi su configurazione e comportamento per la ricerca web basata su Ollama. Riferimento completo della configurazione. diff --git a/docs/it/reference/memory-config.md b/docs/it/reference/memory-config.md index a129d3e55..5cd19f7f7 100644 --- a/docs/it/reference/memory-config.md +++ b/docs/it/reference/memory-config.md @@ -1,84 +1,86 @@ --- read_when: - - Vuoi configurare provider di ricerca nella memoria o modelli di embedding + - Vuoi configurare i provider di ricerca nella memoria o i modelli di embeddings - Vuoi configurare il backend QMD - - Vuoi regolare ricerca ibrida, MMR o decadimento temporale + - Vuoi ottimizzare la ricerca ibrida, MMR o il decadimento temporale - Vuoi abilitare l'indicizzazione della memoria multimodale -summary: Tutte le opzioni di configurazione per ricerca nella memoria, provider di embedding, QMD, ricerca ibrida e indicizzazione multimodale -title: Riferimento della configurazione della memoria +summary: Tutte le opzioni di configurazione per la ricerca nella memoria, i provider di embeddings, QMD, la ricerca ibrida e l'indicizzazione multimodale +title: Riferimento di configurazione della memoria x-i18n: - generated_at: "2026-04-12T23:33:34Z" + generated_at: "2026-04-15T14:40:51Z" model: gpt-5.4 provider: openai - source_hash: 299ca9b69eea292ea557a2841232c637f5c1daf2bc0f73c0a42f7c0d8d566ce2 + source_hash: 334c3c4dac08e864487047d3822c75f96e9e7a97c38be4b4e0cd9e63c4489a53 source_path: reference/memory-config.md workflow: 15 --- -# Riferimento della configurazione della memoria +# Riferimento di configurazione della memoria -Questa pagina elenca tutte le opzioni di configurazione per la ricerca nella memoria di OpenClaw. Per -le panoramiche concettuali, vedi: +Questa pagina elenca tutte le opzioni di configurazione per la ricerca nella memoria di OpenClaw. Per panoramiche concettuali, vedi: - [Panoramica della memoria](/it/concepts/memory) -- come funziona la memoria - [Motore integrato](/it/concepts/memory-builtin) -- backend SQLite predefinito -- [Motore QMD](/it/concepts/memory-qmd) -- sidecar local-first -- [Ricerca nella memoria](/it/concepts/memory-search) -- pipeline di ricerca e regolazione -- [Active Memory](/it/concepts/active-memory) -- abilitazione del sotto-agente di memoria per le sessioni interattive +- [Motore QMD](/it/concepts/memory-qmd) -- sidecar locale-first +- [Ricerca nella memoria](/it/concepts/memory-search) -- pipeline di ricerca e ottimizzazione +- [Active Memory](/it/concepts/active-memory) -- abilitazione del sottoagente di memoria per sessioni interattive -Tutte le impostazioni di ricerca nella memoria si trovano sotto `agents.defaults.memorySearch` in +Tutte le impostazioni della ricerca nella memoria si trovano sotto `agents.defaults.memorySearch` in `openclaw.json`, salvo diversa indicazione. -Se stai cercando l'interruttore della funzionalità **Active Memory** e la configurazione del sotto-agente, +Se stai cercando l'interruttore della funzionalità **active memory** e la configurazione del sottoagente, si trovano sotto `plugins.entries.active-memory` invece che sotto `memorySearch`. -Active Memory usa un modello a due gate: +Active memory usa un modello a due condizioni: -1. il Plugin deve essere abilitato e puntare all'ID agente corrente -2. la richiesta deve essere una sessione di chat persistente interattiva idonea +1. il plugin deve essere abilitato e puntare all'ID agente corrente +2. la richiesta deve essere una sessione di chat interattiva persistente idonea -Vedi [Active Memory](/it/concepts/active-memory) per il modello di attivazione, -la configurazione posseduta dal Plugin, la persistenza delle trascrizioni e il modello di rollout sicuro. +Consulta [Active Memory](/it/concepts/active-memory) per il modello di attivazione, +la configurazione gestita dal plugin, la persistenza delle trascrizioni e il modello di distribuzione sicura. --- ## Selezione del provider -| Chiave | Tipo | Predefinito | Descrizione | -| ---------- | --------- | ---------------- | ------------------------------------------------------------------------------------------- | -| `provider` | `string` | rilevato automaticamente | ID dell'adattatore di embedding: `openai`, `gemini`, `voyage`, `mistral`, `bedrock`, `ollama`, `local` | -| `model` | `string` | provider predefinito | Nome del modello di embedding | -| `fallback` | `string` | `"none"` | ID dell'adattatore di fallback quando quello principale fallisce | -| `enabled` | `boolean` | `true` | Abilita o disabilita la ricerca nella memoria | +| Chiave | Tipo | Predefinito | Descrizione | +| ---------- | --------- | ---------------- | ------------------------------------------------------------------------------------------------------------- | +| `provider` | `string` | rilevato automaticamente | ID dell'adattatore di embeddings: `bedrock`, `gemini`, `github-copilot`, `local`, `mistral`, `ollama`, `openai`, `voyage` | +| `model` | `string` | predefinito del provider | Nome del modello di embeddings | +| `fallback` | `string` | `"none"` | ID dell'adattatore di fallback quando quello primario fallisce | +| `enabled` | `boolean` | `true` | Abilita o disabilita la ricerca nella memoria | ### Ordine di rilevamento automatico Quando `provider` non è impostato, OpenClaw seleziona il primo disponibile: 1. `local` -- se `memorySearch.local.modelPath` è configurato e il file esiste. -2. `openai` -- se è possibile risolvere una chiave OpenAI. -3. `gemini` -- se è possibile risolvere una chiave Gemini. -4. `voyage` -- se è possibile risolvere una chiave Voyage. -5. `mistral` -- se è possibile risolvere una chiave Mistral. -6. `bedrock` -- se la catena di credenziali predefinita dell'SDK AWS viene risolta (ruolo istanza, chiavi di accesso, profilo, SSO, web identity o configurazione condivisa). +2. `github-copilot` -- se è possibile risolvere un token GitHub Copilot (variabile d'ambiente o profilo di autenticazione). +3. `openai` -- se è possibile risolvere una chiave OpenAI. +4. `gemini` -- se è possibile risolvere una chiave Gemini. +5. `voyage` -- se è possibile risolvere una chiave Voyage. +6. `mistral` -- se è possibile risolvere una chiave Mistral. +7. `bedrock` -- se la catena di credenziali AWS SDK si risolve (ruolo istanza, chiavi di accesso, profilo, SSO, identità web o configurazione condivisa). `ollama` è supportato ma non viene rilevato automaticamente (impostalo esplicitamente). ### Risoluzione della chiave API -Gli embedding remoti richiedono una chiave API. Bedrock usa invece la catena di -credenziali predefinita dell'SDK AWS (ruoli istanza, SSO, chiavi di accesso). +Gli embeddings remoti richiedono una chiave API. Bedrock usa invece la catena di credenziali +predefinita dell'AWS SDK (ruoli istanza, SSO, chiavi di accesso). -| Provider | Variabile env | Chiave config | -| -------- | ----------------------------- | ---------------------------------- | -| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` | -| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` | -| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` | -| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` | -| Bedrock | Catena di credenziali AWS | Nessuna chiave API necessaria | -| Ollama | `OLLAMA_API_KEY` (segnaposto) | -- | +| Provider | Variabile d'ambiente | Chiave di configurazione | +| -------------- | ------------------------------------------------- | --------------------------------- | +| Bedrock | catena di credenziali AWS | Nessuna chiave API necessaria | +| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` | +| GitHub Copilot | `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` | Profilo di autenticazione tramite login del dispositivo | +| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` | +| Ollama | `OLLAMA_API_KEY` (segnaposto) | -- | +| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` | +| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` | -Codex OAuth copre solo chat/completions e non soddisfa le richieste di embedding. +OAuth di Codex copre solo chat/completions e non soddisfa le richieste di +embeddings. --- @@ -86,11 +88,11 @@ Codex OAuth copre solo chat/completions e non soddisfa le richieste di embedding Per endpoint personalizzati compatibili con OpenAI o per sovrascrivere i valori predefiniti del provider: -| Chiave | Tipo | Descrizione | -| ---------------- | -------- | -------------------------------------------------- | -| `remote.baseUrl` | `string` | URL di base API personalizzato | -| `remote.apiKey` | `string` | Sovrascrive la chiave API | -| `remote.headers` | `object` | Header HTTP aggiuntivi (uniti con i valori predefiniti del provider) | +| Chiave | Tipo | Descrizione | +| ------------------ | -------- | ------------------------------------------------ | +| `remote.baseUrl` | `string` | URL base API personalizzato | +| `remote.apiKey` | `string` | Sovrascrive la chiave API | +| `remote.headers` | `object` | Header HTTP aggiuntivi (uniti ai valori predefiniti del provider) | ```json5 { @@ -119,15 +121,15 @@ Per endpoint personalizzati compatibili con OpenAI o per sovrascrivere i valori | `outputDimensionality` | `number` | `3072` | Per Embedding 2: 768, 1536 o 3072 | -Cambiare il modello o `outputDimensionality` attiva automaticamente una reindicizzazione completa. +La modifica del modello o di `outputDimensionality` attiva automaticamente una reindicizzazione completa. --- -## Configurazione degli embedding Bedrock +## Configurazione degli embeddings Bedrock -Bedrock usa la catena di credenziali predefinita dell'SDK AWS -- non servono chiavi API. -Se OpenClaw viene eseguito su EC2 con un ruolo istanza abilitato per Bedrock, basta impostare +Bedrock usa la catena di credenziali predefinita dell'AWS SDK -- non servono chiavi API. +Se OpenClaw è in esecuzione su EC2 con un ruolo istanza abilitato per Bedrock, imposta semplicemente provider e modello: ```json5 @@ -143,48 +145,48 @@ provider e modello: } ``` -| Chiave | Tipo | Predefinito | Descrizione | -| ---------------------- | -------- | ------------------------------ | ------------------------------- | -| `model` | `string` | `amazon.titan-embed-text-v2:0` | Qualsiasi ID modello embedding Bedrock | -| `outputDimensionality` | `number` | modello predefinito | Per Titan V2: 256, 512 o 1024 | +| Chiave | Tipo | Predefinito | Descrizione | +| ---------------------- | -------- | ----------------------------- | ------------------------------ | +| `model` | `string` | `amazon.titan-embed-text-v2:0` | Qualsiasi ID modello di embeddings Bedrock | +| `outputDimensionality` | `number` | predefinito del modello | Per Titan V2: 256, 512 o 1024 | ### Modelli supportati Sono supportati i seguenti modelli (con rilevamento della famiglia e valori dimensionali predefiniti): -| ID modello | Provider | Dim predefinite | Dim configurabili | -| ------------------------------------------ | ---------- | --------------- | -------------------- | -| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 | -| `amazon.titan-embed-text-v1` | Amazon | 1536 | -- | -| `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- | -| `amazon.titan-embed-image-v1` | Amazon | 1024 | -- | -| `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 | -| `cohere.embed-english-v3` | Cohere | 1024 | -- | -| `cohere.embed-multilingual-v3` | Cohere | 1024 | -- | -| `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 | -| `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- | -| `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- | +| ID modello | Provider | Dims predefinite | Dims configurabili | +| ------------------------------------------- | ---------- | ---------------- | -------------------- | +| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 | +| `amazon.titan-embed-text-v1` | Amazon | 1536 | -- | +| `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- | +| `amazon.titan-embed-image-v1` | Amazon | 1024 | -- | +| `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 | +| `cohere.embed-english-v3` | Cohere | 1024 | -- | +| `cohere.embed-multilingual-v3` | Cohere | 1024 | -- | +| `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 | +| `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- | +| `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- | Le varianti con suffisso di throughput (ad esempio `amazon.titan-embed-text-v1:2:8k`) ereditano -la configurazione del modello di base. +la configurazione del modello base. ### Autenticazione -L'autenticazione Bedrock usa l'ordine standard di risoluzione delle credenziali dell'SDK AWS: +L'autenticazione Bedrock usa l'ordine standard di risoluzione delle credenziali AWS SDK: 1. Variabili d'ambiente (`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`) 2. Cache del token SSO -3. Credenziali del token web identity +3. Credenziali del token di identità web 4. File condivisi di credenziali e configurazione -5. Credenziali dei metadata ECS o EC2 +5. Credenziali dei metadati ECS o EC2 La regione viene risolta da `AWS_REGION`, `AWS_DEFAULT_REGION`, dal -`baseUrl` del provider `amazon-bedrock`, oppure usa come valore predefinito `us-east-1`. +`baseUrl` del provider `amazon-bedrock`, oppure per impostazione predefinita da `us-east-1`. ### Permessi IAM -Il ruolo IAM o l'utente deve avere: +Il ruolo o l'utente IAM necessita di: ```json { @@ -202,15 +204,15 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0 --- -## Configurazione degli embedding locali +## Configurazione degli embeddings locali -| Chiave | Tipo | Predefinito | Descrizione | -| --------------------- | -------- | ---------------------- | ------------------------------- | +| Chiave | Tipo | Predefinito | Descrizione | +| --------------------- | -------- | ---------------------- | ------------------------------ | | `local.modelPath` | `string` | scaricato automaticamente | Percorso del file modello GGUF | -| `local.modelCacheDir` | `string` | predefinito node-llama-cpp | Directory cache per i modelli scaricati | +| `local.modelCacheDir` | `string` | predefinito di node-llama-cpp | Directory cache per i modelli scaricati | -Modello predefinito: `embeddinggemma-300m-qat-Q8_0.gguf` (~0.6 GB, scaricato automaticamente). -Richiede build nativa: `pnpm approve-builds` poi `pnpm rebuild node-llama-cpp`. +Modello predefinito: `embeddinggemma-300m-qat-Q8_0.gguf` (~0,6 GB, scaricato automaticamente). +Richiede una build nativa: `pnpm approve-builds` poi `pnpm rebuild node-llama-cpp`. --- @@ -218,11 +220,11 @@ Richiede build nativa: `pnpm approve-builds` poi `pnpm rebuild node-llama-cpp`. Tutto sotto `memorySearch.query.hybrid`: -| Chiave | Tipo | Predefinito | Descrizione | -| --------------------- | --------- | ----------- | ----------------------------------- | +| Chiave | Tipo | Predefinito | Descrizione | +| --------------------- | --------- | ----------- | ---------------------------------- | | `enabled` | `boolean` | `true` | Abilita la ricerca ibrida BM25 + vettoriale | | `vectorWeight` | `number` | `0.7` | Peso per i punteggi vettoriali (0-1) | -| `textWeight` | `number` | `0.3` | Peso per i punteggi BM25 (0-1) | +| `textWeight` | `number` | `0.3` | Peso per i punteggi BM25 (0-1) | | `candidateMultiplier` | `number` | `4` | Moltiplicatore della dimensione del pool di candidati | ### MMR (diversità) @@ -230,16 +232,16 @@ Tutto sotto `memorySearch.query.hybrid`: | Chiave | Tipo | Predefinito | Descrizione | | ------------- | --------- | ----------- | ------------------------------------ | | `mmr.enabled` | `boolean` | `false` | Abilita il reranking MMR | -| `mmr.lambda` | `number` | `0.7` | 0 = massima diversità, 1 = massima rilevanza | +| `mmr.lambda` | `number` | `0.7` | 0 = massima diversità, 1 = massima pertinenza | -### Decadimento temporale (recency) +### Decadimento temporale (recenza) -| Chiave | Tipo | Predefinito | Descrizione | -| ---------------------------- | --------- | ----------- | ------------------------------ | -| `temporalDecay.enabled` | `boolean` | `false` | Abilita il boost della recency | +| Chiave | Tipo | Predefinito | Descrizione | +| ---------------------------- | --------- | ----------- | -------------------------- | +| `temporalDecay.enabled` | `boolean` | `false` | Abilita il boost di recenza | | `temporalDecay.halfLifeDays` | `number` | `30` | Il punteggio si dimezza ogni N giorni | -I file evergreen (`MEMORY.md`, file senza data in `memory/`) non subiscono mai decadimento. +I file evergreen (`MEMORY.md`, file non datati in `memory/`) non subiscono mai decadimento. ### Esempio completo @@ -266,8 +268,8 @@ I file evergreen (`MEMORY.md`, file senza data in `memory/`) non subiscono mai d ## Percorsi di memoria aggiuntivi -| Chiave | Tipo | Descrizione | -| ------------ | ---------- | ----------------------------------------- | +| Chiave | Tipo | Descrizione | +| ----------- | ---------- | ----------------------------------------- | | `extraPaths` | `string[]` | Directory o file aggiuntivi da indicizzare | ```json5 @@ -282,16 +284,16 @@ I file evergreen (`MEMORY.md`, file senza data in `memory/`) non subiscono mai d } ``` -I percorsi possono essere assoluti o relativi al workspace. Le directory vengono scansionate +I percorsi possono essere assoluti o relativi allo spazio di lavoro. Le directory vengono analizzate ricorsivamente per i file `.md`. La gestione dei collegamenti simbolici dipende dal backend attivo: -il motore integrato ignora i collegamenti simbolici, mentre QMD segue il comportamento dello -scanner QMD sottostante. +il motore integrato ignora i symlink, mentre QMD segue il comportamento dello scanner QMD +sottostante. -Per la ricerca di trascrizioni cross-agent con ambito agente, usa +Per la ricerca di trascrizioni tra agenti con ambito agente, usa `agents.list[].memorySearch.qmd.extraCollections` invece di `memory.qmd.paths`. -Queste raccolte aggiuntive seguono la stessa forma `{ path, name, pattern? }`, ma -vengono unite per agente e possono conservare nomi condivisi espliciti quando il percorso -punta fuori dal workspace corrente. +Queste raccolte aggiuntive seguono la stessa struttura `{ path, name, pattern? }`, ma +vengono unite per agente e possono preservare nomi condivisi espliciti quando il percorso +punta fuori dallo spazio di lavoro corrente. Se lo stesso percorso risolto appare sia in `memory.qmd.paths` sia in `memorySearch.qmd.extraCollections`, QMD mantiene la prima voce e salta il duplicato. @@ -302,10 +304,10 @@ duplicato. Indicizza immagini e audio insieme al Markdown usando Gemini Embedding 2: -| Chiave | Tipo | Predefinito | Descrizione | -| ------------------------- | ---------- | ----------- | ----------------------------------------- | -| `multimodal.enabled` | `boolean` | `false` | Abilita l'indicizzazione multimodale | -| `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]` oppure `["all"]` | +| Chiave | Tipo | Predefinito | Descrizione | +| ------------------------- | ---------- | ----------- | -------------------------------------- | +| `multimodal.enabled` | `boolean` | `false` | Abilita l'indicizzazione multimodale | +| `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]` o `["all"]` | | `multimodal.maxFileBytes` | `number` | `10000000` | Dimensione massima del file per l'indicizzazione | Si applica solo ai file in `extraPaths`. Le radici di memoria predefinite restano solo Markdown. @@ -316,67 +318,66 @@ Formati supportati: `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.heic`, `.heif` --- -## Cache degli embedding +## Cache degli embeddings -| Chiave | Tipo | Predefinito | Descrizione | -| ------------------ | --------- | ----------- | -------------------------------- | -| `cache.enabled` | `boolean` | `false` | Memorizza in cache gli embedding dei chunk in SQLite | -| `cache.maxEntries` | `number` | `50000` | Numero massimo di embedding in cache | +| Chiave | Tipo | Predefinito | Descrizione | +| ------------------ | --------- | ----------- | ------------------------------------- | +| `cache.enabled` | `boolean` | `false` | Memorizza nella cache gli embeddings dei blocchi in SQLite | +| `cache.maxEntries` | `number` | `50000` | Numero massimo di embeddings nella cache | -Impedisce il re-embedding di testo invariato durante la reindicizzazione o gli aggiornamenti delle trascrizioni. +Impedisce di ricalcolare gli embeddings per testo invariato durante la reindicizzazione o gli aggiornamenti delle trascrizioni. --- -## Indicizzazione batch +## Indicizzazione in batch -| Chiave | Tipo | Predefinito | Descrizione | -| ----------------------------- | --------- | ----------- | -------------------------- | -| `remote.batch.enabled` | `boolean` | `false` | Abilita l'API di embedding batch | -| `remote.batch.concurrency` | `number` | `2` | Job batch paralleli | +| Chiave | Tipo | Predefinito | Descrizione | +| ----------------------------- | --------- | ----------- | ------------------------------- | +| `remote.batch.enabled` | `boolean` | `false` | Abilita l'API di embeddings in batch | +| `remote.batch.concurrency` | `number` | `2` | Job batch paralleli | | `remote.batch.wait` | `boolean` | `true` | Attende il completamento del batch | -| `remote.batch.pollIntervalMs` | `number` | -- | Intervallo di polling | -| `remote.batch.timeoutMinutes` | `number` | -- | Timeout del batch | +| `remote.batch.pollIntervalMs` | `number` | -- | Intervallo di polling | +| `remote.batch.timeoutMinutes` | `number` | -- | Timeout del batch | -Disponibile per `openai`, `gemini` e `voyage`. Il batch OpenAI è tipicamente -il più veloce e conveniente per grandi backfill. +Disponibile per `openai`, `gemini` e `voyage`. Il batch OpenAI è in genere +il più veloce ed economico per backfill di grandi dimensioni. --- ## Ricerca nella memoria delle sessioni (sperimentale) -Indicizza le trascrizioni delle sessioni e le espone tramite `memory_search`: +Indicizza le trascrizioni delle sessioni e le rende disponibili tramite `memory_search`: -| Chiave | Tipo | Predefinito | Descrizione | -| --------------------------- | ---------- | ------------ | --------------------------------------- | -| `experimental.sessionMemory` | `boolean` | `false` | Abilita l'indicizzazione delle sessioni | -| `sources` | `string[]` | `["memory"]` | Aggiungi `"sessions"` per includere le trascrizioni | -| `sync.sessions.deltaBytes` | `number` | `100000` | Soglia in byte per la reindicizzazione | -| `sync.sessions.deltaMessages` | `number` | `50` | Soglia in messaggi per la reindicizzazione | +| Chiave | Tipo | Predefinito | Descrizione | +| --------------------------- | ---------- | ------------ | ---------------------------------------- | +| `experimental.sessionMemory` | `boolean` | `false` | Abilita l'indicizzazione delle sessioni | +| `sources` | `string[]` | `["memory"]` | Aggiungi `"sessions"` per includere le trascrizioni | +| `sync.sessions.deltaBytes` | `number` | `100000` | Soglia in byte per la reindicizzazione | +| `sync.sessions.deltaMessages` | `number` | `50` | Soglia in messaggi per la reindicizzazione | L'indicizzazione delle sessioni è opt-in e viene eseguita in modo asincrono. I risultati possono essere leggermente -non aggiornati. I log delle sessioni risiedono su disco, quindi considera l'accesso al filesystem come il confine -di fiducia. +obsoleti. I log delle sessioni risiedono su disco, quindi considera l'accesso al filesystem come limite di attendibilità. --- -## Accelerazione vettoriale SQLite (`sqlite-vec`) +## Accelerazione vettoriale SQLite (sqlite-vec) | Chiave | Tipo | Predefinito | Descrizione | | -------------------------- | --------- | ----------- | --------------------------------- | -| `store.vector.enabled` | `boolean` | `true` | Usa sqlite-vec per le query vettoriali | -| `store.vector.extensionPath` | `string` | bundle | Sovrascrive il percorso di sqlite-vec | +| `store.vector.enabled` | `boolean` | `true` | Usa sqlite-vec per le query vettoriali | +| `store.vector.extensionPath` | `string` | bundled | Sovrascrive il percorso di sqlite-vec | -Quando sqlite-vec non è disponibile, OpenClaw torna automaticamente alla +Quando sqlite-vec non è disponibile, OpenClaw passa automaticamente alla similarità coseno in-process. --- ## Archiviazione dell'indice -| Chiave | Tipo | Predefinito | Descrizione | -| --------------------- | -------- | ------------------------------------- | ------------------------------------------- | -| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | Posizione dell'indice (supporta il token `{agentId}`) | -| `store.fts.tokenizer` | `string` | `unicode61` | Tokenizer FTS5 (`unicode61` o `trigram`) | +| Chiave | Tipo | Predefinito | Descrizione | +| ------------------- | -------- | ------------------------------------- | -------------------------------------------- | +| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | Posizione dell'indice (supporta il token `{agentId}`) | +| `store.fts.tokenizer` | `string` | `unicode61` | Tokenizer FTS5 (`unicode61` o `trigram`) | --- @@ -395,40 +396,40 @@ Imposta `memory.backend = "qmd"` per abilitarlo. Tutte le impostazioni QMD si tr | `sessions.retentionDays` | `number` | -- | Conservazione delle trascrizioni | | `sessions.exportDir` | `string` | -- | Directory di esportazione | -OpenClaw preferisce le forme correnti delle raccolte QMD e delle query MCP, ma continua -a far funzionare le release più vecchie di QMD usando il fallback verso i flag legacy delle raccolte `--mask` -e i vecchi nomi degli strumenti MCP quando necessario. +OpenClaw preferisce le forme correnti di raccolta QMD e query MCP, ma mantiene +compatibili anche le versioni precedenti di QMD ripiegando sui flag legacy di raccolta `--mask` +e sui nomi più vecchi degli strumenti MCP quando necessario. -Gli override dei modelli QMD restano sul lato QMD, non nella configurazione OpenClaw. Se hai bisogno di +Le sovrascritture dei modelli QMD restano sul lato QMD, non nella configurazione di OpenClaw. Se devi sovrascrivere globalmente i modelli di QMD, imposta variabili d'ambiente come -`QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` e `QMD_GENERATE_MODEL` nell'ambiente di runtime -del gateway. +`QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` e `QMD_GENERATE_MODEL` nell'ambiente +runtime del Gateway. ### Pianificazione degli aggiornamenti -| Chiave | Tipo | Predefinito | Descrizione | -| ------------------------- | --------- | ----------- | ---------------------------------------- | -| `update.interval` | `string` | `5m` | Intervallo di aggiornamento | -| `update.debounceMs` | `number` | `15000` | Debounce delle modifiche ai file | -| `update.onBoot` | `boolean` | `true` | Aggiorna all'avvio | -| `update.waitForBootSync` | `boolean` | `false` | Blocca l'avvio finché l'aggiornamento non è completato | -| `update.embedInterval` | `string` | -- | Cadenza separata per gli embedding | -| `update.commandTimeoutMs` | `number` | -- | Timeout per i comandi QMD | -| `update.updateTimeoutMs` | `number` | -- | Timeout per le operazioni `qmd update` | -| `update.embedTimeoutMs` | `number` | -- | Timeout per le operazioni `qmd embed` | +| Chiave | Tipo | Predefinito | Descrizione | +| ------------------------- | --------- | ----------- | -------------------------------------- | +| `update.interval` | `string` | `5m` | Intervallo di aggiornamento | +| `update.debounceMs` | `number` | `15000` | Debounce delle modifiche ai file | +| `update.onBoot` | `boolean` | `true` | Aggiorna all'avvio | +| `update.waitForBootSync` | `boolean` | `false` | Blocca l'avvio finché l'aggiornamento non è completo | +| `update.embedInterval` | `string` | -- | Cadenza separata per gli embeddings | +| `update.commandTimeoutMs` | `number` | -- | Timeout per i comandi QMD | +| `update.updateTimeoutMs` | `number` | -- | Timeout per le operazioni di aggiornamento QMD | +| `update.embedTimeoutMs` | `number` | -- | Timeout per le operazioni di embedding QMD | ### Limiti -| Chiave | Tipo | Predefinito | Descrizione | -| ------------------------- | -------- | ----------- | ------------------------------- | +| Chiave | Tipo | Predefinito | Descrizione | +| ------------------------- | -------- | ----------- | ------------------------------ | | `limits.maxResults` | `number` | `6` | Numero massimo di risultati di ricerca | | `limits.maxSnippetChars` | `number` | -- | Limita la lunghezza dello snippet | -| `limits.maxInjectedChars` | `number` | -- | Limita il totale dei caratteri inseriti | -| `limits.timeoutMs` | `number` | `4000` | Timeout della ricerca | +| `limits.maxInjectedChars` | `number` | -- | Limita il totale dei caratteri iniettati | +| `limits.timeoutMs` | `number` | `4000` | Timeout della ricerca | ### Ambito -Controlla quali sessioni possono ricevere i risultati di ricerca QMD. Stesso schema di +Controlla quali sessioni possono ricevere risultati di ricerca QMD. Stesso schema di [`session.sendPolicy`](/it/gateway/configuration-reference#session): ```json5 @@ -447,17 +448,17 @@ Controlla quali sessioni possono ricevere i risultati di ricerca QMD. Stesso sch Il valore predefinito distribuito consente sessioni dirette e di canale, continuando però a negare i gruppi. -Il valore predefinito è solo DM. `match.keyPrefix` confronta la chiave di sessione normalizzata; -`match.rawKeyPrefix` confronta la chiave grezza inclusa `agent::`. +Il valore predefinito è solo DM. `match.keyPrefix` corrisponde alla chiave di sessione normalizzata; +`match.rawKeyPrefix` corrisponde alla chiave grezza inclusa `agent::`. ### Citazioni `memory.citations` si applica a tutti i backend: -| Valore | Comportamento | -| ---------------- | ----------------------------------------------------- | +| Valore | Comportamento | +| ---------------- | -------------------------------------------------- | | `auto` (predefinito) | Include il piè di pagina `Source: ` negli snippet | -| `on` | Include sempre il piè di pagina | +| `on` | Include sempre il piè di pagina | | `off` | Omette il piè di pagina (il percorso viene comunque passato internamente all'agente) | ### Esempio completo QMD @@ -483,22 +484,22 @@ Il valore predefinito è solo DM. `match.keyPrefix` confronta la chiave di sessi --- -## Dreaming (sperimentale) +## Dreaming Dreaming è configurato sotto `plugins.entries.memory-core.config.dreaming`, non sotto `agents.defaults.memorySearch`. -Dreaming viene eseguito come una scansione pianificata unica e usa internamente le fasi light/deep/REM come +Dreaming viene eseguito come una singola scansione pianificata e usa fasi interne light/deep/REM come dettaglio di implementazione. -Per il comportamento concettuale e i comandi slash, vedi [Dreaming](/it/concepts/dreaming). +Per il comportamento concettuale e i comandi slash, consulta [Dreaming](/it/concepts/dreaming). ### Impostazioni utente -| Chiave | Tipo | Predefinito | Descrizione | -| ----------- | --------- | ----------- | --------------------------------------------------- | -| `enabled` | `boolean` | `false` | Abilita o disabilita completamente Dreaming | -| `frequency` | `string` | `0 3 * * *` | Cadenza Cron facoltativa per la scansione completa di Dreaming | +| Chiave | Tipo | Predefinito | Descrizione | +| ----------- | --------- | ----------- | ------------------------------------------------- | +| `enabled` | `boolean` | `false` | Abilita o disabilita completamente Dreaming | +| `frequency` | `string` | `0 3 * * *` | Cadenza Cron opzionale per la scansione completa di Dreaming | ### Esempio @@ -522,5 +523,5 @@ Per il comportamento concettuale e i comandi slash, vedi [Dreaming](/it/concepts Note: - Dreaming scrive lo stato macchina in `memory/.dreams/`. -- Dreaming scrive output narrativo leggibile da umani in `DREAMS.md` (o `dreams.md` esistente). -- La policy delle fasi light/deep/REM e le soglie sono comportamento interno, non configurazione esposta all'utente. +- Dreaming scrive output narrativo leggibile da esseri umani in `DREAMS.md` (o `dreams.md` esistente). +- La policy e le soglie delle fasi light/deep/REM sono comportamenti interni, non configurazione esposta all'utente. diff --git a/docs/it/reference/wizard.md b/docs/it/reference/wizard.md index 63fb20b7c..b371d040c 100644 --- a/docs/it/reference/wizard.md +++ b/docs/it/reference/wizard.md @@ -1,21 +1,21 @@ --- read_when: - - Cerchi uno specifico passaggio o flag dell'onboarding - - Vuoi automatizzare l'onboarding con la modalità non interattiva - - Stai eseguendo il debug del comportamento dell'onboarding + - Ricerca di un passaggio o di una flag di onboarding specifici + - Automatizzare l'onboarding con la modalità non interattiva + - Debug del comportamento di onboarding sidebarTitle: Onboarding Reference -summary: 'Riferimento completo per l''onboarding CLI: ogni passaggio, flag e campo di configurazione' -title: Riferimento dell'onboarding +summary: 'Riferimento completo per l''onboarding della CLI: ogni passaggio, flag e campo di configurazione' +title: Riferimento per l'onboarding x-i18n: - generated_at: "2026-04-07T08:17:58Z" + generated_at: "2026-04-15T14:40:55Z" model: gpt-5.4 provider: openai - source_hash: a142b9ec4323fabb9982d05b64375d2b4a4007dffc910acbee3a38ff871a7236 + source_hash: 1db3ff789422617634e6624f9d12c18b6a6c573721226b9c0fa6f6b7956ef33d source_path: reference/wizard.md workflow: 15 --- -# Riferimento dell'onboarding +# Riferimento per l'onboarding Questo è il riferimento completo per `openclaw onboard`. Per una panoramica di alto livello, vedi [Onboarding (CLI)](/it/start/wizard). @@ -25,112 +25,112 @@ Per una panoramica di alto livello, vedi [Onboarding (CLI)](/it/start/wizard). - Se `~/.openclaw/openclaw.json` esiste, scegli **Mantieni / Modifica / Reimposta**. - - Rieseguire l'onboarding **non** cancella nulla a meno che tu non scelga esplicitamente **Reimposta** + - Eseguire di nuovo l'onboarding **non** cancella nulla a meno che tu non scelga esplicitamente **Reimposta** (o passi `--reset`). - - `--reset` nella CLI usa come valore predefinito `config+creds+sessions`; usa `--reset-scope full` + - L'opzione CLI `--reset` usa per impostazione predefinita `config+creds+sessions`; usa `--reset-scope full` per rimuovere anche il workspace. - - Se la configurazione non è valida o contiene chiavi legacy, il wizard si interrompe e ti chiede + - Se la configurazione non è valida o contiene chiavi legacy, la procedura guidata si interrompe e ti chiede di eseguire `openclaw doctor` prima di continuare. - La reimpostazione usa `trash` (mai `rm`) e offre questi ambiti: - Solo configurazione - Configurazione + credenziali + sessioni - Reimpostazione completa (rimuove anche il workspace) - - - **Chiave API Anthropic**: usa `ANTHROPIC_API_KEY` se presente oppure richiede una chiave, poi la salva per l'uso da parte del daemon. - - **Chiave API Anthropic**: scelta assistente Anthropic preferita in onboarding/configure. - - **Setup-token Anthropic**: ancora disponibile in onboarding/configure, anche se OpenClaw ora preferisce il riuso di Claude CLI quando disponibile. - - **Abbonamento OpenAI Code (Codex) (Codex CLI)**: se esiste `~/.codex/auth.json`, l'onboarding può riutilizzarlo. Le credenziali Codex CLI riutilizzate restano gestite da Codex CLI; alla scadenza OpenClaw rilegge prima quella sorgente e, quando il provider può aggiornarla, riscrive la credenziale aggiornata nello storage Codex invece di assumerne direttamente la gestione. - - **Abbonamento OpenAI Code (Codex) (OAuth)**: flusso browser; incolla `code#state`. - - Imposta `agents.defaults.model` su `openai-codex/gpt-5.4` quando il modello non è impostato oppure è `openai/*`. - - **Chiave API OpenAI**: usa `OPENAI_API_KEY` se presente oppure richiede una chiave, poi la archivia nei profili auth. + + - **Chiave API Anthropic**: usa `ANTHROPIC_API_KEY` se presente oppure richiede una chiave, quindi la salva per l'uso del daemon. + - **Chiave API Anthropic**: scelta preferita dell'assistente Anthropic in onboarding/configurazione. + - **Setup-token Anthropic**: ancora disponibile in onboarding/configurazione, anche se OpenClaw ora preferisce il riutilizzo della CLI Claude quando disponibile. + - **Abbonamento OpenAI Code (Codex) (Codex CLI)**: se `~/.codex/auth.json` esiste, l'onboarding può riutilizzarlo. Le credenziali Codex CLI riutilizzate restano gestite da Codex CLI; alla scadenza OpenClaw rilegge prima quella fonte e, quando il provider può aggiornarla, scrive di nuovo la credenziale aggiornata nello storage di Codex invece di assumerne direttamente la gestione. + - **Abbonamento OpenAI Code (Codex) (OAuth)**: flusso via browser; incolla `code#state`. + - Imposta `agents.defaults.model` su `openai-codex/gpt-5.4` quando il modello non è impostato o è `openai/*`. + - **Chiave API OpenAI**: usa `OPENAI_API_KEY` se presente oppure richiede una chiave, quindi la memorizza nei profili di autenticazione. - Imposta `agents.defaults.model` su `openai/gpt-5.4` quando il modello non è impostato, è `openai/*` oppure `openai-codex/*`. - **Chiave API xAI (Grok)**: richiede `XAI_API_KEY` e configura xAI come provider di modelli. - - **OpenCode**: richiede `OPENCODE_API_KEY` (o `OPENCODE_ZEN_API_KEY`, ottenibile da https://opencode.ai/auth) e ti permette di scegliere il catalogo Zen o Go. - - **Ollama**: richiede l'URL di base di Ollama, offre la modalità **Cloud + Local** o **Local**, rileva i modelli disponibili ed esegue automaticamente il pull del modello locale selezionato quando necessario. + - **OpenCode**: richiede `OPENCODE_API_KEY` (oppure `OPENCODE_ZEN_API_KEY`, ottienila su https://opencode.ai/auth) e ti consente di scegliere il catalogo Zen o Go. + - **Ollama**: propone prima **Cloud + Local**, **Solo cloud** oppure **Solo locale**. `Solo cloud` richiede `OLLAMA_API_KEY` e usa `https://ollama.com`; le modalità con host richiedono l'URL di base di Ollama, rilevano i modelli disponibili e scaricano automaticamente il modello locale selezionato quando necessario; `Cloud + Local` controlla anche se quell'host Ollama ha effettuato l'accesso per l'accesso cloud. - Maggiori dettagli: [Ollama](/it/providers/ollama) - - **Chiave API**: archivia la chiave per te. + - **Chiave API**: memorizza la chiave per te. - **Vercel AI Gateway (proxy multi-modello)**: richiede `AI_GATEWAY_API_KEY`. - Maggiori dettagli: [Vercel AI Gateway](/it/providers/vercel-ai-gateway) - **Cloudflare AI Gateway**: richiede Account ID, Gateway ID e `CLOUDFLARE_AI_GATEWAY_API_KEY`. - Maggiori dettagli: [Cloudflare AI Gateway](/it/providers/cloudflare-ai-gateway) - - **MiniMax**: la configurazione viene scritta automaticamente; il valore predefinito hosted è `MiniMax-M2.7`. - La configurazione con chiave API usa `minimax/...`, e la configurazione OAuth usa + - **MiniMax**: la configurazione viene scritta automaticamente; il valore predefinito ospitato è `MiniMax-M2.7`. + La configurazione con chiave API usa `minimax/...`, mentre la configurazione OAuth usa `minimax-portal/...`. - Maggiori dettagli: [MiniMax](/it/providers/minimax) - **StepFun**: la configurazione viene scritta automaticamente per StepFun standard o Step Plan su endpoint Cina o globali. - - Lo standard include attualmente `step-3.5-flash`, e Step Plan include anche `step-3.5-flash-2603`. + - Standard include attualmente `step-3.5-flash`, e Step Plan include anche `step-3.5-flash-2603`. - Maggiori dettagli: [StepFun](/it/providers/stepfun) - **Synthetic (compatibile con Anthropic)**: richiede `SYNTHETIC_API_KEY`. - Maggiori dettagli: [Synthetic](/it/providers/synthetic) - **Moonshot (Kimi K2)**: la configurazione viene scritta automaticamente. - **Kimi Coding**: la configurazione viene scritta automaticamente. - Maggiori dettagli: [Moonshot AI (Kimi + Kimi Coding)](/it/providers/moonshot) - - **Salta**: nessuna autenticazione ancora configurata. - - Scegli un modello predefinito tra le opzioni rilevate (oppure inserisci manualmente provider/model). Per la migliore qualità e un rischio minore di prompt injection, scegli il modello più potente e di ultima generazione disponibile nel tuo stack provider. - - L'onboarding esegue un controllo del modello e avvisa se il modello configurato è sconosciuto o manca l'autenticazione. - - La modalità di archiviazione predefinita delle chiavi API usa valori in chiaro nei profili auth. Usa `--secret-input-mode ref` per archiviare invece riferimenti basati su env (per esempio `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`). - - I profili auth si trovano in `~/.openclaw/agents//agent/auth-profiles.json` (chiavi API + OAuth). `~/.openclaw/credentials/oauth.json` è legacy e serve solo per l'importazione. + - **Salta**: nessuna autenticazione configurata al momento. + - Scegli un modello predefinito tra le opzioni rilevate (oppure inserisci manualmente provider/modello). Per la migliore qualità e un rischio inferiore di prompt injection, scegli il modello più forte e di ultima generazione disponibile nel tuo stack di provider. + - L'onboarding esegue un controllo del modello e avvisa se il modello configurato è sconosciuto o se manca l'autenticazione. + - La modalità di archiviazione della chiave API usa per impostazione predefinita valori in chiaro nei profili di autenticazione. Usa `--secret-input-mode ref` per memorizzare invece riferimenti basati su variabili di ambiente (ad esempio `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`). + - I profili di autenticazione si trovano in `~/.openclaw/agents//agent/auth-profiles.json` (chiavi API + OAuth). `~/.openclaw/credentials/oauth.json` è legacy e serve solo per l'importazione. - Maggiori dettagli: [/concepts/oauth](/it/concepts/oauth) - Suggerimento per ambienti headless/server: completa OAuth su una macchina con browser, poi copia - l'`auth-profiles.json` di quell'agente (per esempio - `~/.openclaw/agents//agent/auth-profiles.json`, o il percorso corrispondente - `$OPENCLAW_STATE_DIR/...`) sull'host gateway. `credentials/oauth.json` - è solo una sorgente legacy di importazione. + Suggerimento per headless/server: completa OAuth su una macchina con browser, poi copia + `auth-profiles.json` di quell'agente (ad esempio + `~/.openclaw/agents//agent/auth-profiles.json`, oppure il percorso + corrispondente `$OPENCLAW_STATE_DIR/...`) sull'host del gateway. `credentials/oauth.json` + è solo una fonte legacy per l'importazione. - Valore predefinito `~/.openclaw/workspace` (configurabile). - - Inizializza i file workspace necessari per il rituale di bootstrap dell'agente. - - Layout completo del workspace + guida ai backup: [Workspace dell'agente](/it/concepts/agent-workspace) + - Inizializza i file del workspace necessari per il rituale bootstrap dell'agente. + - Layout completo del workspace + guida al backup: [Workspace dell'agente](/it/concepts/agent-workspace) - - Porta, bind, modalità auth, esposizione Tailscale. - - Raccomandazione auth: mantieni **Token** anche per loopback così i client WS locali devono autenticarsi. + - Porta, bind, modalità di autenticazione, esposizione Tailscale. + - Raccomandazione per l'autenticazione: mantieni **Token** anche per loopback, così i client WS locali devono autenticarsi. - In modalità token, la configurazione interattiva offre: - - **Genera/archivia token in chiaro** (predefinito) - - **Usa SecretRef** (opt-in) - - Quickstart riutilizza i SecretRef esistenti di `gateway.auth.token` nei provider `env`, `file` ed `exec` per probe di onboarding/bootstrap della dashboard. - - Se quel SecretRef è configurato ma non può essere risolto, l'onboarding fallisce subito con un chiaro messaggio di correzione invece di degradare silenziosamente l'auth runtime. - - In modalità password, anche la configurazione interattiva supporta l'archiviazione in chiaro o SecretRef. - - Percorso SecretRef del token in modalità non interattiva: `--gateway-token-ref-env `. - - Richiede una variabile env non vuota nell'ambiente del processo di onboarding. + - **Genera/memorizza token in chiaro** (predefinito) + - **Usa SecretRef** (facoltativo) + - Quickstart riutilizza i SecretRef esistenti di `gateway.auth.token` nei provider `env`, `file` ed `exec` per la probe/dashboard bootstrap dell'onboarding. + - Se quel SecretRef è configurato ma non può essere risolto, l'onboarding fallisce subito con un chiaro messaggio di correzione invece di degradare silenziosamente l'autenticazione a runtime. + - In modalità password, la configurazione interattiva supporta anch'essa l'archiviazione in chiaro o SecretRef. + - Percorso SecretRef del token non interattivo: `--gateway-token-ref-env `. + - Richiede una variabile di ambiente non vuota nell'ambiente del processo di onboarding. - Non può essere combinato con `--gateway-token`. - - Disattiva l'autenticazione solo se ti fidi completamente di ogni processo locale. - - I bind non-loopback richiedono comunque l'autenticazione. + - Disabilita l'autenticazione solo se ti fidi completamente di ogni processo locale. + - I bind non loopback richiedono comunque l'autenticazione. - - [WhatsApp](/it/channels/whatsapp): login QR facoltativo. - - [Telegram](/it/channels/telegram): token bot. - - [Discord](/it/channels/discord): token bot. - - [Google Chat](/it/channels/googlechat): JSON dell'account di servizio + audience del webhook. - - [Mattermost](/it/channels/mattermost) (plugin): token bot + URL di base. - - [Signal](/it/channels/signal): installazione facoltativa di `signal-cli` + configurazione account. - - [BlueBubbles](/it/channels/bluebubbles): **consigliato per iMessage**; URL server + password + webhook. - - [iMessage](/it/channels/imessage): percorso legacy `imsg` CLI + accesso al DB. - - Sicurezza DM: il valore predefinito è pairing. Il primo DM invia un codice; approvalo con `openclaw pairing approve ` oppure usa allowlist. + - [WhatsApp](/it/channels/whatsapp): accesso QR facoltativo. + - [Telegram](/it/channels/telegram): token del bot. + - [Discord](/it/channels/discord): token del bot. + - [Google Chat](/it/channels/googlechat): JSON dell'account di servizio + audience del Webhook. + - [Mattermost](/it/channels/mattermost) (Plugin): token del bot + URL di base. + - [Signal](/it/channels/signal): installazione facoltativa di `signal-cli` + configurazione dell'account. + - [BlueBubbles](/it/channels/bluebubbles): **consigliato per iMessage**; URL del server + password + Webhook. + - [iMessage](/it/channels/imessage): percorso della CLI `imsg` legacy + accesso DB. + - Sicurezza dei DM: il valore predefinito è l'abbinamento. Il primo DM invia un codice; approvalo con `openclaw pairing approve ` oppure usa allowlist. - Scegli un provider supportato come Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Perplexity, SearXNG o Tavily (oppure salta). - - I provider basati su API possono usare variabili env o configurazione esistente per una configurazione rapida; i provider senza chiave usano invece i prerequisiti specifici del provider. + - I provider basati su API possono usare variabili di ambiente o configurazione esistente per una configurazione rapida; i provider senza chiave usano invece i prerequisiti specifici del provider. - Salta con `--skip-search`. - Configura in seguito: `openclaw configure --section web`. - macOS: LaunchAgent - - Richiede una sessione utente connessa; per ambienti headless, usa un LaunchDaemon personalizzato (non distribuito). - - Linux (e Windows tramite WSL2): unità systemd utente - - L'onboarding tenta di abilitare lingering tramite `loginctl enable-linger ` così il Gateway resta attivo dopo il logout. - - Può richiedere sudo (scrive in `/var/lib/systemd/linger`); prova prima senza sudo. + - Richiede una sessione utente con accesso effettuato; per ambienti headless, usa un LaunchDaemon personalizzato (non fornito). + - Linux (e Windows tramite WSL2): unità utente systemd + - L'onboarding tenta di abilitare lingering tramite `loginctl enable-linger ` in modo che il Gateway resti attivo dopo il logout. + - Può richiedere sudo (scrive in `/var/lib/systemd/linger`); prima prova senza sudo. - **Selezione del runtime:** Node (consigliato; richiesto per WhatsApp/Telegram). Bun **non è consigliato**. - - Se l'auth token richiede un token e `gateway.auth.token` è gestito da SecretRef, l'installazione del daemon lo valida ma non persiste valori di token risolti in chiaro nei metadati dell'ambiente del servizio supervisor. - - Se l'auth token richiede un token e il SecretRef token configurato non è risolto, l'installazione del daemon viene bloccata con indicazioni operative. - - Se sono configurati sia `gateway.auth.token` sia `gateway.auth.password` e `gateway.auth.mode` non è impostato, l'installazione del daemon viene bloccata finché la modalità non viene impostata esplicitamente. + - Se l'autenticazione token richiede un token e `gateway.auth.token` è gestito da SecretRef, l'installazione del daemon lo convalida ma non persiste i valori del token in chiaro risolti nei metadati dell'ambiente del servizio supervisor. + - Se l'autenticazione token richiede un token e il SecretRef del token configurato non è risolto, l'installazione del daemon viene bloccata con indicazioni operative. + - Se sia `gateway.auth.token` sia `gateway.auth.password` sono configurati e `gateway.auth.mode` non è impostato, l'installazione del daemon viene bloccata finché la modalità non viene impostata esplicitamente. - Avvia il Gateway (se necessario) ed esegue `openclaw health`. - - Suggerimento: `openclaw status --deep` aggiunge la probe live di integrità del gateway all'output di stato, incluse probe dei canali quando supportate (richiede un gateway raggiungibile). + - Suggerimento: `openclaw status --deep` aggiunge l'health probe del gateway live all'output di stato, comprese le probe dei canali quando supportate (richiede un gateway raggiungibile). - Legge le Skills disponibili e controlla i requisiti. @@ -138,13 +138,13 @@ Per una panoramica di alto livello, vedi [Onboarding (CLI)](/it/start/wizard). - Installa dipendenze facoltative (alcune usano Homebrew su macOS). - - Riepilogo + passaggi successivi, incluse app iOS/Android/macOS per funzionalità extra. + - Riepilogo + passaggi successivi, incluse le app iOS/Android/macOS per funzionalità aggiuntive. -Se non viene rilevata alcuna GUI, l'onboarding stampa le istruzioni di port forwarding SSH per la Control UI invece di aprire un browser. -Se mancano gli asset della Control UI, l'onboarding tenta di compilarli; il fallback è `pnpm ui:build` (installa automaticamente le dipendenze UI). +Se non viene rilevata alcuna GUI, l'onboarding stampa le istruzioni per il port-forward SSH della Control UI invece di aprire un browser. +Se mancano le risorse della Control UI, l'onboarding tenta di compilarle; il fallback è `pnpm ui:build` (installa automaticamente le dipendenze della UI). ## Modalità non interattiva @@ -163,9 +163,9 @@ openclaw onboard --non-interactive \ --skip-skills ``` -Aggiungi `--json` per un riepilogo leggibile dalla macchina. +Aggiungi `--json` per un riepilogo leggibile da una macchina. -SecretRef del token gateway in modalità non interattiva: +SecretRef del token Gateway in modalità non interattiva: ```bash export OPENCLAW_GATEWAY_TOKEN="your-token" @@ -182,8 +182,8 @@ openclaw onboard --non-interactive \ `--json` **non** implica la modalità non interattiva. Usa `--non-interactive` (e `--workspace`) per gli script. -Gli esempi di comandi specifici per provider si trovano in [Automazione CLI](/it/start/wizard-cli-automation#provider-specific-examples). -Usa questa pagina di riferimento per la semantica dei flag e l'ordine dei passaggi. +Esempi di comandi specifici per provider si trovano in [Automazione CLI](/it/start/wizard-cli-automation#provider-specific-examples). +Usa questa pagina di riferimento per la semantica delle flag e l'ordine dei passaggi. ### Aggiungere un agente (non interattivo) @@ -196,12 +196,12 @@ openclaw agents add work \ --json ``` -## RPC del wizard del gateway +## RPC della procedura guidata Gateway Il Gateway espone il flusso di onboarding tramite RPC (`wizard.start`, `wizard.next`, `wizard.cancel`, `wizard.status`). I client (app macOS, Control UI) possono visualizzare i passaggi senza reimplementare la logica di onboarding. -## Configurazione Signal (`signal-cli`) +## Configurazione di Signal (signal-cli) L'onboarding può installare `signal-cli` dalle release GitHub: @@ -213,22 +213,22 @@ Note: - Le build JVM richiedono **Java 21**. - Le build native vengono usate quando disponibili. -- Windows usa WSL2; l'installazione di signal-cli segue il flusso Linux dentro WSL. +- Windows usa WSL2; l'installazione di signal-cli segue il flusso Linux all'interno di WSL. -## Cosa scrive il wizard +## Cosa scrive la procedura guidata Campi tipici in `~/.openclaw/openclaw.json`: - `agents.defaults.workspace` - `agents.defaults.model` / `models.providers` (se viene scelto Minimax) -- `tools.profile` (l'onboarding locale usa come predefinito `"coding"` quando non impostato; i valori espliciti esistenti vengono preservati) -- `gateway.*` (mode, bind, auth, tailscale) -- `session.dmScope` (dettagli del comportamento: [Riferimento della configurazione CLI](/it/start/wizard-cli-reference#outputs-and-internals)) +- `tools.profile` (l'onboarding locale usa per impostazione predefinita `"coding"` se non impostato; i valori espliciti esistenti vengono mantenuti) +- `gateway.*` (modalità, bind, autenticazione, Tailscale) +- `session.dmScope` (dettagli sul comportamento: [Riferimento configurazione CLI](/it/start/wizard-cli-reference#outputs-and-internals)) - `channels.telegram.botToken`, `channels.discord.token`, `channels.matrix.*`, `channels.signal.*`, `channels.imessage.*` -- Allowlist dei canali (Slack/Discord/Matrix/Microsoft Teams) quando aderisci durante i prompt (i nomi vengono risolti in ID quando possibile). +- Allowlist dei canali (Slack/Discord/Matrix/Microsoft Teams) quando scegli questa opzione durante i prompt (i nomi vengono risolti in ID quando possibile). - `skills.install.nodeManager` - `setup --node-manager` accetta `npm`, `pnpm` o `bun`. - - La configurazione manuale può comunque usare `yarn` impostando direttamente `skills.install.nodeManager`. + - La configurazione manuale può ancora usare `yarn` impostando direttamente `skills.install.nodeManager`. - `wizard.lastRunAt` - `wizard.lastRunVersion` - `wizard.lastRunCommit` @@ -240,13 +240,13 @@ Campi tipici in `~/.openclaw/openclaw.json`: Le credenziali WhatsApp vengono salvate in `~/.openclaw/credentials/whatsapp//`. Le sessioni vengono archiviate in `~/.openclaw/agents//sessions/`. -Alcuni canali sono distribuiti come plugin. Quando ne scegli uno durante la configurazione, l'onboarding -ti chiederà di installarlo (npm o percorso locale) prima che possa essere configurato. +Alcuni canali vengono distribuiti come Plugin. Quando ne scegli uno durante la configurazione, l'onboarding +ti chiederà di installarlo (npm o un percorso locale) prima che possa essere configurato. ## Documentazione correlata - Panoramica dell'onboarding: [Onboarding (CLI)](/it/start/wizard) - Onboarding dell'app macOS: [Onboarding](/it/start/onboarding) -- Riferimento della configurazione: [Configurazione del gateway](/it/gateway/configuration) +- Riferimento configurazione: [Configurazione del Gateway](/it/gateway/configuration) - Provider: [WhatsApp](/it/channels/whatsapp), [Telegram](/it/channels/telegram), [Discord](/it/channels/discord), [Google Chat](/it/channels/googlechat), [Signal](/it/channels/signal), [BlueBubbles](/it/channels/bluebubbles) (iMessage), [iMessage](/it/channels/imessage) (legacy) - Skills: [Skills](/it/tools/skills), [Configurazione Skills](/it/tools/skills-config) diff --git a/docs/it/start/wizard-cli-reference.md b/docs/it/start/wizard-cli-reference.md index 8cc72d90e..dab601a84 100644 --- a/docs/it/start/wizard-cli-reference.md +++ b/docs/it/start/wizard-cli-reference.md @@ -1,20 +1,20 @@ --- read_when: - - Hai bisogno del comportamento dettagliato di `openclaw onboard` - - Stai eseguendo il debug dei risultati dell'onboarding o integrando client di onboarding + - Hai bisogno di informazioni dettagliate sul comportamento di `openclaw onboard` + - Stai eseguendo il debug dei risultati di onboarding o stai integrando client di onboarding sidebarTitle: CLI reference -summary: Riferimento completo per il flusso di configurazione CLI, setup auth/modello, output e dettagli interni -title: Riferimento della configurazione CLI +summary: Riferimento completo per il flusso di configurazione della CLI, la configurazione di autenticazione/modello, gli output e gli aspetti interni +title: Riferimento per la configurazione della CLI x-i18n: - generated_at: "2026-04-06T03:12:36Z" + generated_at: "2026-04-15T14:41:04Z" model: gpt-5.4 provider: openai - source_hash: 92f379b34a2b48c68335dae4f759117c770f018ec51b275f4f40421c6b3abb23 + source_hash: 61ca679caca3b43fa02388294007f89db22d343e49e10b61d8d118cd8fbb7369 source_path: start/wizard-cli-reference.md workflow: 15 --- -# Riferimento della configurazione CLI +# Riferimento per la configurazione della CLI Questa pagina è il riferimento completo per `openclaw onboard`. Per la guida breve, vedi [Onboarding (CLI)](/it/start/wizard). @@ -23,15 +23,15 @@ Per la guida breve, vedi [Onboarding (CLI)](/it/start/wizard). La modalità locale (predefinita) ti guida attraverso: -- Configurazione del modello e dell'autenticazione (OAuth con abbonamento OpenAI Code, Anthropic Claude CLI o chiave API, oltre alle opzioni MiniMax, GLM, Ollama, Moonshot, StepFun e AI Gateway) -- Posizione dello workspace e file bootstrap -- Impostazioni del gateway (porta, bind, autenticazione, Tailscale) -- Canali e provider (Telegram, WhatsApp, Discord, Google Chat, Mattermost, Signal, BlueBubbles e altri plugin canale bundled) -- Installazione del daemon (LaunchAgent, unità utente systemd o Scheduled Task nativa di Windows con fallback nella cartella Startup) -- Controllo dello stato -- Configurazione delle Skills +- Configurazione del modello e dell'autenticazione (OAuth dell'abbonamento OpenAI Code, Anthropic Claude CLI o chiave API, oltre a opzioni MiniMax, GLM, Ollama, Moonshot, StepFun e AI Gateway) +- Posizione del workspace e file di bootstrap +- Impostazioni del Gateway (porta, bind, auth, tailscale) +- Canali e provider (Telegram, WhatsApp, Discord, Google Chat, Mattermost, Signal, BlueBubbles e altri plugin di canale inclusi) +- Installazione del daemon (LaunchAgent, unità utente systemd o attività pianificata nativa di Windows con fallback nella cartella Startup) +- Controllo dello stato di salute +- Configurazione di Skills -La modalità remota configura questa macchina per connettersi a un gateway altrove. +La modalità remota configura questa macchina per connettersi a un Gateway altrove. Non installa né modifica nulla sull'host remoto. ## Dettagli del flusso locale @@ -39,80 +39,80 @@ Non installa né modifica nulla sull'host remoto. - Se esiste `~/.openclaw/openclaw.json`, scegli Mantieni, Modifica o Reimposta. - - Rieseguire la procedura guidata non cancella nulla a meno che tu non scelga esplicitamente Reimposta (o passi `--reset`). - - `--reset` della CLI usa per impostazione predefinita `config+creds+sessions`; usa `--reset-scope full` per rimuovere anche lo workspace. - - Se la configurazione non è valida o contiene chiavi legacy, la procedura guidata si ferma e ti chiede di eseguire `openclaw doctor` prima di continuare. - - La reimpostazione usa `trash` e offre questi ambiti: + - Eseguire di nuovo la procedura guidata non cancella nulla a meno che tu non scelga esplicitamente Reimposta (o passi `--reset`). + - La CLI `--reset` usa come predefinito `config+creds+sessions`; usa `--reset-scope full` per rimuovere anche il workspace. + - Se la configurazione non è valida o contiene chiavi legacy, la procedura guidata si interrompe e ti chiede di eseguire `openclaw doctor` prima di continuare. + - Reimposta usa `trash` e offre questi ambiti: - Solo configurazione - Configurazione + credenziali + sessioni - - Reimpostazione completa (rimuove anche lo workspace) + - Reimpostazione completa (rimuove anche il workspace) - - La matrice completa delle opzioni è in [Opzioni di autenticazione e modello](#opzioni-di-autenticazione-e-modello). + - La matrice completa delle opzioni è in [Opzioni di autenticazione e modello](#auth-and-model-options). - Predefinito `~/.openclaw/workspace` (configurabile). - - Inserisce i file workspace necessari per il rituale di bootstrap del primo avvio. - - Layout dello workspace: [Agent workspace](/it/concepts/agent-workspace). + - Inizializza i file del workspace necessari per il rituale di bootstrap della prima esecuzione. + - Layout del workspace: [Workspace dell'agente](/it/concepts/agent-workspace). - - Richiede porta, bind, modalità auth ed esposizione Tailscale. - - Consigliato: mantieni abilitata l'autenticazione tramite token anche per loopback in modo che i client WS locali debbano autenticarsi. + - Chiede porta, bind, modalità auth ed esposizione Tailscale. + - Consigliato: mantieni abilitata l'autenticazione tramite token anche per loopback, così i client WS locali devono autenticarsi. - In modalità token, la configurazione interattiva offre: - - **Generate/store plaintext token** (predefinito) - - **Use SecretRef** (opt-in) - - In modalità password, la configurazione interattiva supporta anche l'archiviazione in testo semplice o SecretRef. + - **Genera/memorizza token in chiaro** (predefinito) + - **Usa SecretRef** (opt-in) + - In modalità password, la configurazione interattiva supporta anche la memorizzazione in chiaro o con SecretRef. - Percorso SecretRef del token non interattivo: `--gateway-token-ref-env `. - - Richiede una variabile env non vuota nell'ambiente del processo di onboarding. + - Richiede una variabile d'ambiente non vuota nell'ambiente del processo di onboarding. - Non può essere combinato con `--gateway-token`. - Disabilita l'autenticazione solo se ti fidi completamente di ogni processo locale. - I bind non-loopback richiedono comunque l'autenticazione. - - [WhatsApp](/it/channels/whatsapp): login QR facoltativo + - [WhatsApp](/it/channels/whatsapp): accesso QR opzionale - [Telegram](/it/channels/telegram): token del bot - [Discord](/it/channels/discord): token del bot - - [Google Chat](/it/channels/googlechat): JSON dell'account di servizio + audience webhook - - [Mattermost](/it/channels/mattermost): token del bot + URL base - - [Signal](/it/channels/signal): installazione facoltativa di `signal-cli` + configurazione account - - [BlueBubbles](/it/channels/bluebubbles): consigliato per iMessage; URL server + password + webhook - - [iMessage](/it/channels/imessage): percorso CLI legacy `imsg` + accesso DB - - Sicurezza DM: l'impostazione predefinita è pairing. Il primo DM invia un codice; approvalo con - `openclaw pairing approve ` oppure usa le allowlist. + - [Google Chat](/it/channels/googlechat): JSON dell'account di servizio + audience del webhook + - [Mattermost](/it/channels/mattermost): token del bot + URL di base + - [Signal](/it/channels/signal): installazione opzionale di `signal-cli` + configurazione dell'account + - [BlueBubbles](/it/channels/bluebubbles): consigliato per iMessage; URL del server + password + webhook + - [iMessage](/it/channels/imessage): percorso legacy della CLI `imsg` + accesso al DB + - Sicurezza dei DM: il predefinito è l'abbinamento. Il primo DM invia un codice; approvalo tramite + `openclaw pairing approve ` oppure usa allowlist. - macOS: LaunchAgent - - Richiede una sessione utente con accesso effettuato; per ambienti headless, usa un LaunchDaemon personalizzato (non incluso). + - Richiede una sessione utente con accesso effettuato; per ambienti headless usa un LaunchDaemon personalizzato (non incluso). - Linux e Windows tramite WSL2: unità utente systemd - - La procedura guidata prova `loginctl enable-linger ` in modo che il gateway resti attivo dopo il logout. - - Potrebbe richiedere sudo (scrive `/var/lib/systemd/linger`); prima ci prova senza sudo. - - Windows nativo: Scheduled Task per prima - - Se la creazione del task viene negata, OpenClaw usa come fallback un elemento di accesso nella cartella Startup per utente e avvia immediatamente il gateway. - - Le Scheduled Task restano preferite perché forniscono uno stato del supervisore migliore. + - La procedura guidata tenta `loginctl enable-linger ` così il Gateway resta attivo dopo il logout. + - Potrebbe richiedere sudo (scrive in `/var/lib/systemd/linger`); prova prima senza sudo. + - Windows nativo: prima attività pianificata + - Se la creazione dell'attività viene negata, OpenClaw ripiega su un elemento di accesso nella cartella Startup per utente e avvia immediatamente il Gateway. + - Le attività pianificate restano preferibili perché forniscono uno stato del supervisore migliore. - Selezione del runtime: Node (consigliato; richiesto per WhatsApp e Telegram). Bun non è consigliato. - - - Avvia il gateway (se necessario) ed esegue `openclaw health`. - - `openclaw status --deep` aggiunge la probe live dello stato del gateway all'output di stato, incluse le probe dei canali quando supportate. + + - Avvia il Gateway (se necessario) ed esegue `openclaw health`. + - `openclaw status --deep` aggiunge il probe di stato di salute del Gateway attivo all'output di stato, inclusi i probe dei canali quando supportati. - - Legge le Skills disponibili e controlla i requisiti. - - Ti consente di scegliere il node manager: npm, pnpm o bun. - - Installa le dipendenze facoltative (alcune usano Homebrew su macOS). + - Legge le Skills disponibili e verifica i requisiti. + - Ti permette di scegliere il gestore Node: npm, pnpm o bun. + - Installa dipendenze opzionali (alcune usano Homebrew su macOS). - - Riepilogo e passaggi successivi, incluse le opzioni per app iOS, Android e macOS. + - Riepilogo e passaggi successivi, incluse le opzioni app per iOS, Android e macOS. -Se non viene rilevata alcuna GUI, la procedura guidata stampa istruzioni di port-forward SSH per la Control UI invece di aprire un browser. -Se mancano le risorse della Control UI, la procedura guidata prova a compilarle; il fallback è `pnpm ui:build` (installa automaticamente le dipendenze UI). +Se non viene rilevata alcuna GUI, la procedura guidata stampa le istruzioni di port forwarding SSH per la UI di controllo invece di aprire un browser. +Se mancano le risorse della UI di controllo, la procedura guidata tenta di compilarle; il fallback è `pnpm ui:build` (installa automaticamente le dipendenze della UI). ## Dettagli della modalità remota -La modalità remota configura questa macchina per connettersi a un gateway altrove. +La modalità remota configura questa macchina per connettersi a un Gateway altrove. La modalità remota non installa né modifica nulla sull'host remoto. @@ -120,12 +120,12 @@ La modalità remota non installa né modifica nulla sull'host remoto. Cosa imposti: -- URL del gateway remoto (`ws://...`) -- Token se è richiesta l'autenticazione del gateway remoto (consigliato) +- URL del Gateway remoto (`ws://...`) +- Token se è richiesta l'autenticazione del Gateway remoto (consigliato) -- Se il gateway è solo loopback, usa il tunneling SSH o una tailnet. -- Suggerimenti di rilevamento: +- Se il Gateway è solo loopback, usa tunneling SSH o una tailnet. +- Suggerimenti per il rilevamento: - macOS: Bonjour (`dns-sd`) - Linux: Avahi (`avahi-browse`) @@ -134,32 +134,32 @@ Cosa imposti: - Usa `ANTHROPIC_API_KEY` se presente oppure richiede una chiave, quindi la salva per l'uso da parte del daemon. + Usa `ANTHROPIC_API_KEY` se presente oppure richiede una chiave, quindi la salva per l'uso del daemon. - + Se esiste `~/.codex/auth.json`, la procedura guidata può riutilizzarlo. - Le credenziali della CLI Codex riutilizzate restano gestite dalla CLI Codex; alla scadenza OpenClaw - rilegge prima quella sorgente e, quando il provider può aggiornarla, scrive - la credenziale aggiornata di nuovo nello storage Codex invece di prenderne il controllo - direttamente. + Le credenziali di Codex CLI riutilizzate restano gestite da Codex CLI; alla scadenza OpenClaw + rilegge prima quella sorgente e, quando il provider può aggiornarle, scrive + la credenziale aggiornata di nuovo nell'archivio di Codex invece di assumerne direttamente + la gestione. - Flusso browser; incolla `code#state`. + Flusso nel browser; incolla `code#state`. - Imposta `agents.defaults.model` su `openai-codex/gpt-5.4` quando il modello non è impostato o è `openai/*`. + Imposta `agents.defaults.model` su `openai-codex/gpt-5.4` quando il modello non è impostato oppure è `openai/*`. Usa `OPENAI_API_KEY` se presente oppure richiede una chiave, quindi memorizza la credenziale nei profili auth. - Imposta `agents.defaults.model` su `openai/gpt-5.4` quando il modello non è impostato, è `openai/*` o `openai-codex/*`. + Imposta `agents.defaults.model` su `openai/gpt-5.4` quando il modello non è impostato, è `openai/*` oppure `openai-codex/*`. - Richiede `XAI_API_KEY` e configura xAI come provider del modello. + Richiede `XAI_API_KEY` e configura xAI come provider di modelli. - Richiede `OPENCODE_API_KEY` (oppure `OPENCODE_ZEN_API_KEY`) e ti permette di scegliere il catalogo Zen o Go. + Richiede `OPENCODE_API_KEY` (oppure `OPENCODE_ZEN_API_KEY`) e ti consente di scegliere il catalogo Zen o Go. URL di configurazione: [opencode.ai/auth](https://opencode.ai/auth). @@ -174,12 +174,12 @@ Cosa imposti: Maggiori dettagli: [Cloudflare AI Gateway](/it/providers/cloudflare-ai-gateway). - La configurazione viene scritta automaticamente. Il valore hosted predefinito è `MiniMax-M2.7`; la configurazione con chiave API usa + La configurazione viene scritta automaticamente. L'hosted predefinito è `MiniMax-M2.7`; la configurazione con chiave API usa `minimax/...`, mentre la configurazione OAuth usa `minimax-portal/...`. Maggiori dettagli: [MiniMax](/it/providers/minimax). - La configurazione viene scritta automaticamente per StepFun standard o Step Plan sugli endpoint Cina o globali. + La configurazione viene scritta automaticamente per StepFun standard o Step Plan su endpoint China o global. Standard include attualmente `step-3.5-flash`, e Step Plan include anche `step-3.5-flash-2603`. Maggiori dettagli: [StepFun](/it/providers/stepfun). @@ -187,29 +187,31 @@ Cosa imposti: Richiede `SYNTHETIC_API_KEY`. Maggiori dettagli: [Synthetic](/it/providers/synthetic). - - Richiede URL base (predefinito `http://127.0.0.1:11434`), poi offre modalità Cloud + Local o Local. - Rileva i modelli disponibili e suggerisce i predefiniti. + + Richiede prima `Cloud + Local`, `Solo Cloud` oppure `Solo Local`. + `Solo Cloud` usa `OLLAMA_API_KEY` con `https://ollama.com`. + Le modalità basate su host richiedono l'URL di base (predefinito `http://127.0.0.1:11434`), rilevano i modelli disponibili e suggeriscono i predefiniti. + `Cloud + Local` controlla anche se quell'host Ollama ha effettuato l'accesso per l'accesso cloud. Maggiori dettagli: [Ollama](/it/providers/ollama). - Le configurazioni di Moonshot (Kimi K2) e Kimi Coding vengono scritte automaticamente. + Le configurazioni Moonshot (Kimi K2) e Kimi Coding vengono scritte automaticamente. Maggiori dettagli: [Moonshot AI (Kimi + Kimi Coding)](/it/providers/moonshot). Funziona con endpoint compatibili con OpenAI e compatibili con Anthropic. - L'onboarding interattivo supporta le stesse opzioni di archiviazione della chiave API degli altri flussi di chiave API del provider: - - **Paste API key now** (testo semplice) - - **Use secret reference** (riferimento env o provider configurato, con validazione preflight) + L'onboarding interattivo supporta le stesse scelte di memorizzazione della chiave API degli altri flussi con chiave API del provider: + - **Incolla ora la chiave API** (in chiaro) + - **Usa riferimento segreto** (riferimento env o riferimento del provider configurato, con validazione preliminare) Flag non interattivi: - `--auth-choice custom-api-key` - `--custom-base-url` - `--custom-model-id` - - `--custom-api-key` (facoltativo; fallback a `CUSTOM_API_KEY`) - - `--custom-provider-id` (facoltativo) - - `--custom-compatibility ` (facoltativo; predefinito `openai`) + - `--custom-api-key` (opzionale; usa come fallback `CUSTOM_API_KEY`) + - `--custom-provider-id` (opzionale) + - `--custom-compatibility ` (opzionale; predefinito `openai`) @@ -219,61 +221,61 @@ Cosa imposti: Comportamento del modello: -- Scegli il modello predefinito tra le opzioni rilevate, oppure inserisci manualmente provider e modello. -- Quando l'onboarding parte da una scelta di autenticazione del provider, il selettore del modello preferisce +- Scegli il modello predefinito dalle opzioni rilevate, oppure inserisci manualmente provider e modello. +- Quando l'onboarding inizia da una scelta di autenticazione del provider, il selettore del modello preferisce automaticamente quel provider. Per Volcengine e BytePlus, la stessa preferenza corrisponde anche alle loro varianti coding-plan (`volcengine-plan/*`, `byteplus-plan/*`). - Se quel filtro del provider preferito sarebbe vuoto, il selettore torna al - catalogo completo invece di non mostrare modelli. + catalogo completo invece di non mostrare alcun modello. - La procedura guidata esegue un controllo del modello e avvisa se il modello configurato è sconosciuto o manca l'autenticazione. -Percorsi delle credenziali e dei profili: +Percorsi di credenziali e profili: - Profili auth (chiavi API + OAuth): `~/.openclaw/agents//agent/auth-profiles.json` - Importazione OAuth legacy: `~/.openclaw/credentials/oauth.json` -Modalità di archiviazione delle credenziali: +Modalità di memorizzazione delle credenziali: -- Il comportamento predefinito dell'onboarding salva le chiavi API come valori in testo semplice nei profili auth. -- `--secret-input-mode ref` abilita la modalità riferimento invece dell'archiviazione in testo semplice della chiave. - Nella configurazione interattiva puoi scegliere tra: - - riferimento a variabile di ambiente (ad esempio `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`) - - riferimento a provider configurato (`file` o `exec`) con alias provider + id -- La modalità riferimento interattiva esegue una rapida validazione preflight prima del salvataggio. - - Riferimenti env: convalida il nome della variabile + valore non vuoto nell'ambiente di onboarding corrente. - - Riferimenti provider: convalida la config del provider e risolve l'id richiesto. - - Se il preflight fallisce, l'onboarding mostra l'errore e ti consente di riprovare. -- In modalità non interattiva, `--secret-input-mode ref` è supportato solo con env. - - Imposta la variabile env del provider nell'ambiente del processo di onboarding. - - I flag inline della chiave (ad esempio `--openai-api-key`) richiedono che tale variabile env sia impostata; altrimenti l'onboarding fallisce immediatamente. - - Per i provider personalizzati, la modalità `ref` non interattiva memorizza `models.providers..apiKey` come `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`. - - In quel caso del provider personalizzato, `--custom-api-key` richiede che `CUSTOM_API_KEY` sia impostato; altrimenti l'onboarding fallisce immediatamente. -- Le credenziali auth del gateway supportano scelte testo semplice e SecretRef nella configurazione interattiva: - - Modalità token: **Generate/store plaintext token** (predefinito) oppure **Use SecretRef**. - - Modalità password: testo semplice oppure SecretRef. +- Il comportamento predefinito dell'onboarding salva le chiavi API come valori in chiaro nei profili auth. +- `--secret-input-mode ref` abilita la modalità riferimento invece della memorizzazione della chiave in chiaro. + Nella configurazione interattiva, puoi scegliere: + - riferimento a variabile d'ambiente (ad esempio `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`) + - riferimento a provider configurato (`file` o `exec`) con alias del provider + id +- La modalità riferimento interattiva esegue una rapida validazione preliminare prima del salvataggio. + - Riferimenti env: valida il nome della variabile e il valore non vuoto nell'ambiente di onboarding corrente. + - Riferimenti provider: valida la configurazione del provider e risolve l'id richiesto. + - Se la validazione preliminare fallisce, l'onboarding mostra l'errore e ti consente di riprovare. +- In modalità non interattiva, `--secret-input-mode ref` è supportato solo tramite env. + - Imposta la variabile d'ambiente del provider nell'ambiente del processo di onboarding. + - I flag con chiave inline (ad esempio `--openai-api-key`) richiedono che quella variabile env sia impostata; altrimenti l'onboarding fallisce rapidamente. + - Per i provider personalizzati, la modalità `ref` non interattiva salva `models.providers..apiKey` come `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`. + - In quel caso del provider personalizzato, `--custom-api-key` richiede che `CUSTOM_API_KEY` sia impostato; altrimenti l'onboarding fallisce rapidamente. +- Le credenziali auth del Gateway supportano la scelta tra testo in chiaro e SecretRef nella configurazione interattiva: + - Modalità token: **Genera/memorizza token in chiaro** (predefinito) oppure **Usa SecretRef**. + - Modalità password: testo in chiaro oppure SecretRef. - Percorso SecretRef del token non interattivo: `--gateway-token-ref-env `. -- Le configurazioni esistenti in testo semplice continuano a funzionare senza modifiche. +- Le configurazioni esistenti in chiaro continuano a funzionare senza modifiche. -Suggerimento per ambienti headless e server: completa OAuth su una macchina con browser, poi copia -`auth-profiles.json` di quell'agente (ad esempio -`~/.openclaw/agents//agent/auth-profiles.json`, o il corrispondente -percorso `$OPENCLAW_STATE_DIR/...`) sull'host del gateway. `credentials/oauth.json` -è solo una sorgente legacy per l'importazione. +Suggerimento per ambienti headless e server: completa l'OAuth su una macchina con browser, poi copia +l'`auth-profiles.json` di quell'agente (ad esempio +`~/.openclaw/agents//agent/auth-profiles.json`, oppure il percorso corrispondente +`$OPENCLAW_STATE_DIR/...`) sull'host del Gateway. `credentials/oauth.json` +è solo una sorgente di importazione legacy. -## Output e dettagli interni +## Output e aspetti interni Campi tipici in `~/.openclaw/openclaw.json`: - `agents.defaults.workspace` -- `agents.defaults.model` / `models.providers` (se è stato scelto MiniMax) -- `tools.profile` (l'onboarding locale imposta questo valore su `"coding"` quando non è impostato; i valori espliciti esistenti vengono preservati) +- `agents.defaults.model` / `models.providers` (se viene scelto MiniMax) +- `tools.profile` (l'onboarding locale usa come predefinito `"coding"` se non impostato; i valori espliciti esistenti vengono preservati) - `gateway.*` (mode, bind, auth, tailscale) -- `session.dmScope` (l'onboarding locale imposta questo valore su `per-channel-peer` quando non è impostato; i valori espliciti esistenti vengono preservati) +- `session.dmScope` (l'onboarding locale usa come predefinito `per-channel-peer` se non impostato; i valori espliciti esistenti vengono preservati) - `channels.telegram.botToken`, `channels.discord.token`, `channels.matrix.*`, `channels.signal.*`, `channels.imessage.*` -- Allowlist dei canali (Slack, Discord, Matrix, Microsoft Teams) quando scegli l'opzione durante i prompt (i nomi vengono risolti in ID quando possibile) +- Allowlist dei canali (Slack, Discord, Matrix, Microsoft Teams) quando scegli di abilitarle durante i prompt (i nomi vengono risolti in ID quando possibile) - `skills.install.nodeManager` - Il flag `setup --node-manager` accetta `npm`, `pnpm` o `bun`. - La configurazione manuale può comunque impostare successivamente `skills.install.nodeManager: "yarn"`. @@ -283,28 +285,28 @@ Campi tipici in `~/.openclaw/openclaw.json`: - `wizard.lastRunCommand` - `wizard.lastRunMode` -`openclaw agents add` scrive `agents.list[]` e `bindings` facoltativi. +`openclaw agents add` scrive `agents.list[]` e `bindings` opzionali. -Le credenziali WhatsApp vengono salvate in `~/.openclaw/credentials/whatsapp//`. +Le credenziali di WhatsApp vengono salvate in `~/.openclaw/credentials/whatsapp//`. Le sessioni vengono archiviate in `~/.openclaw/agents//sessions/`. -Alcuni canali vengono distribuiti come plugin. Quando vengono selezionati durante la configurazione, la procedura guidata -richiede di installare il plugin (npm o percorso locale) prima della configurazione del canale. +Alcuni canali sono distribuiti come plugin. Quando vengono selezionati durante la configurazione, la procedura guidata +chiede di installare il Plugin (npm o percorso locale) prima della configurazione del canale. -RPC della procedura guidata del gateway: +RPC della procedura guidata del Gateway: - `wizard.start` - `wizard.next` - `wizard.cancel` - `wizard.status` -I client (app macOS e Control UI) possono renderizzare i passaggi senza reimplementare la logica di onboarding. +I client (app macOS e UI di controllo) possono eseguire il rendering dei passaggi senza reimplementare la logica di onboarding. Comportamento della configurazione di Signal: -- Scarica l'asset di release appropriato +- Scarica l'asset di rilascio appropriato - Lo salva in `~/.openclaw/tools/signal-cli//` - Scrive `channels.signal.cliPath` nella configurazione - Le build JVM richiedono Java 21 @@ -313,6 +315,6 @@ Comportamento della configurazione di Signal: ## Documentazione correlata -- Hub onboarding: [Onboarding (CLI)](/it/start/wizard) -- Automazione e script: [CLI Automation](/it/start/wizard-cli-automation) -- Riferimento comandi: [`openclaw onboard`](/cli/onboard) +- Hub di onboarding: [Onboarding (CLI)](/it/start/wizard) +- Automazione e script: [Automazione CLI](/it/start/wizard-cli-automation) +- Riferimento dei comandi: [`openclaw onboard`](/cli/onboard)