From 37adedfa627119f7528736e332fba5db9fc4dce3 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 10 Apr 2026 08:22:05 +0000 Subject: [PATCH] chore(i18n): refresh it translations --- docs/it/automation/tasks.md | 223 +-- docs/it/concepts/active-memory.md | 612 ++++++ docs/it/concepts/agent-loop.md | 119 +- docs/it/concepts/memory-search.md | 70 +- docs/it/concepts/qa-e2e-automation.md | 112 +- docs/it/gateway/configuration-reference.md | 2035 ++++++++++++++------ docs/it/gateway/protocol.md | 437 +++-- docs/it/help/testing.md | 728 +++---- docs/it/reference/memory-config.md | 312 +-- docs/it/tools/browser.md | 444 +++-- docs/it/tools/exec-approvals.md | 484 ++--- 11 files changed, 3595 insertions(+), 1981 deletions(-) create mode 100644 docs/it/concepts/active-memory.md diff --git a/docs/it/automation/tasks.md b/docs/it/automation/tasks.md index b8ec487e9..77db72fc1 100644 --- a/docs/it/automation/tasks.md +++ b/docs/it/automation/tasks.md @@ -1,42 +1,42 @@ --- read_when: - Ispezione del lavoro in background in corso o completato di recente - - Debug degli errori di consegna per esecuzioni agent distaccate + - Debug delle errori di consegna per esecuzioni di agenti scollegati - Comprendere come le esecuzioni in background si relazionano a sessioni, cron e heartbeat -summary: Monitoraggio delle attività in background per esecuzioni ACP, subagent, processi cron isolati e operazioni CLI +summary: Monitoraggio delle attività in background per esecuzioni ACP, subagenti, processi cron isolati e operazioni CLI title: Attività in background x-i18n: - generated_at: "2026-04-06T03:06:37Z" + generated_at: "2026-04-10T08:13:31Z" model: gpt-5.4 provider: openai - source_hash: 2f56c1ac23237907a090c69c920c09578a2f56f5d8bf750c7f2136c603c8a8ff + source_hash: d7b5ba41f1025e0089986342ce85698bc62f676439c3ccf03f3ed146beb1b1ac source_path: automation/tasks.md workflow: 15 --- # Attività in background -> **Cerchi la pianificazione?** Consulta [Automazione e attività](/it/automation) per scegliere il meccanismo corretto. Questa pagina riguarda il **monitoraggio** del lavoro in background, non la sua pianificazione. +> **Cerchi la pianificazione?** Vedi [Automation & Tasks](/it/automation) per scegliere il meccanismo giusto. Questa pagina copre il **monitoraggio** del lavoro in background, non la sua pianificazione. -Le attività in background monitorano il lavoro che viene eseguito **al di fuori della sessione principale di conversazione**: -esecuzioni ACP, avvii di subagent, esecuzioni isolate di processi cron e operazioni avviate dalla CLI. +Le attività in background tengono traccia del lavoro che viene eseguito **al di fuori della sessione principale della conversazione**: +esecuzioni ACP, avvii di subagenti, esecuzioni isolate di processi cron e operazioni avviate dalla CLI. -Le attività **non** sostituiscono sessioni, processi cron o heartbeat: sono il **registro delle attività** che annota quale lavoro distaccato è avvenuto, quando, e se è andato a buon fine. +Le attività **non** sostituiscono sessioni, processi cron o heartbeat — sono il **registro delle attività** che annota quale lavoro scollegato è avvenuto, quando e se è andato a buon fine. -Non tutte le esecuzioni di agent creano un'attività. I turni heartbeat e la normale chat interattiva non lo fanno. Tutte le esecuzioni cron, gli avvii ACP, gli avvii di subagent e i comandi agent della CLI lo fanno. +Non tutte le esecuzioni dell'agente creano un'attività. I turni heartbeat e la normale chat interattiva no. Tutte le esecuzioni cron, gli avvii ACP, gli avvii di subagenti e i comandi agente della CLI sì. ## In breve -- Le attività sono **record**, non scheduler: cron e heartbeat decidono _quando_ viene eseguito il lavoro, le attività monitorano _cosa è successo_. -- ACP, subagent, tutti i processi cron e le operazioni CLI creano attività. I turni heartbeat no. -- Ogni attività passa attraverso `queued → running → terminal` (succeeded, failed, timed_out, cancelled oppure lost). -- Le attività cron restano attive finché il runtime cron continua a possedere il job; le attività CLI supportate dalla chat restano attive solo finché il relativo contesto di esecuzione è ancora attivo. -- Il completamento è basato su push: il lavoro distaccato può notificare direttamente o risvegliare la sessione richiedente/l'heartbeat quando termina, quindi i loop di polling dello stato di solito non sono l'approccio corretto. -- Le esecuzioni cron isolate e i completamenti dei subagent tentano, nei limiti del possibile, di ripulire le schede/processi del browser tracciati per la loro sessione figlia prima della contabilità finale di pulizia. -- La consegna cron isolata sopprime le risposte intermedie obsolete del parent mentre il lavoro dei subagent discendenti è ancora in fase di completamento, e preferisce l'output finale del discendente quando arriva prima della consegna. -- Le notifiche di completamento vengono consegnate direttamente a un canale o messe in coda per il prossimo heartbeat. +- Le attività sono **record**, non scheduler — cron e heartbeat decidono _quando_ viene eseguito il lavoro, le attività tengono traccia di _cosa è successo_. +- ACP, subagenti, tutti i processi cron e le operazioni CLI creano attività. I turni heartbeat no. +- Ogni attività passa attraverso `queued → running → terminal` (`succeeded`, `failed`, `timed_out`, `cancelled` o `lost`). +- Le attività cron restano attive finché il runtime cron possiede ancora il processo; le attività CLI supportate dalla chat restano attive solo finché il relativo contesto di esecuzione è ancora attivo. +- Il completamento è guidato da push: il lavoro scollegato può notificare direttamente o risvegliare la sessione/heartbeat del richiedente quando termina, quindi i cicli di polling dello stato di solito non sono l'approccio corretto. +- Le esecuzioni cron isolate e i completamenti dei subagenti eseguono, per quanto possibile, la pulizia delle schede/processi del browser tracciati per la loro sessione figlia prima della contabilità finale di pulizia. +- Il recapito cron isolato sopprime le risposte intermedie obsolete del padre mentre il lavoro del subagente discendente è ancora in fase di completamento, e preferisce l'output finale discendente quando arriva prima del recapito. +- Le notifiche di completamento vengono recapitate direttamente a un canale o accodate per il prossimo heartbeat. - `openclaw tasks list` mostra tutte le attività; `openclaw tasks audit` evidenzia i problemi. - I record terminali vengono conservati per 7 giorni, poi eliminati automaticamente. @@ -50,23 +50,23 @@ openclaw tasks list openclaw tasks list --runtime acp openclaw tasks list --status running -# Mostra i dettagli di un'attività specifica (per ID, ID esecuzione o chiave sessione) +# Mostra i dettagli di un'attività specifica (per ID, run ID o chiave sessione) openclaw tasks show # Annulla un'attività in esecuzione (termina la sessione figlia) openclaw tasks cancel -# Modifica il criterio di notifica per un'attività +# Cambia il criterio di notifica per un'attività openclaw tasks notify state_changes -# Esegui un controllo di integrità +# Esegui un audit di integrità openclaw tasks audit # Anteprima o applicazione della manutenzione openclaw tasks maintenance openclaw tasks maintenance --apply -# Ispeziona lo stato di Task Flow +# Ispeziona lo stato di TaskFlow openclaw tasks flow list openclaw tasks flow show openclaw tasks flow cancel @@ -76,82 +76,82 @@ openclaw tasks flow cancel | Origine | Tipo di runtime | Quando viene creato un record attività | Criterio di notifica predefinito | | ---------------------- | --------------- | ------------------------------------------------------ | -------------------------------- | -| Esecuzioni ACP in background | `acp` | Avvio di una sessione ACP figlia | `done_only` | -| Orchestrazione subagent | `subagent` | Avvio di un subagent tramite `sessions_spawn` | `done_only` | -| Processi cron (tutti i tipi) | `cron` | Ogni esecuzione cron (sessione principale e isolata) | `silent` | +| Esecuzioni ACP in background | `acp` | Avvio di una sessione ACP figlia | `done_only` | +| Orchestrazione di subagenti | `subagent` | Avvio di un subagente tramite `sessions_spawn` | `done_only` | +| Processi cron (tutti i tipi) | `cron` | Ogni esecuzione cron (sessione principale e isolata) | `silent` | | Operazioni CLI | `cli` | Comandi `openclaw agent` eseguiti tramite il gateway | `silent` | -| Processi media dell'agent | `cli` | Esecuzioni `video_generate` supportate da sessione | `silent` | +| Processi media dell'agente | `cli` | Esecuzioni `video_generate` supportate dalla sessione | `silent` | -Le attività cron della sessione principale usano per impostazione predefinita il criterio di notifica `silent`: creano record per il monitoraggio ma non generano notifiche. Anche le attività cron isolate usano per impostazione predefinita `silent`, ma sono più visibili perché vengono eseguite nella propria sessione. +Le attività cron della sessione principale usano per impostazione predefinita il criterio di notifica `silent` — creano record per il monitoraggio ma non generano notifiche. Anche le attività cron isolate usano per impostazione predefinita `silent`, ma sono più visibili perché vengono eseguite nella propria sessione. -Anche le esecuzioni `video_generate` supportate da sessione usano il criterio di notifica `silent`. Creano comunque record attività, ma il completamento viene restituito alla sessione agent originale come risveglio interno, così l'agent può scrivere il messaggio di follow-up e allegare personalmente il video completato. Se scegli `tools.media.asyncCompletion.directSend`, i completamenti asincroni di `music_generate` e `video_generate` tentano prima la consegna diretta al canale, per poi ripiegare sul percorso di risveglio della sessione richiedente. +Anche le esecuzioni `video_generate` supportate dalla sessione usano il criterio di notifica `silent`. Continuano a creare record attività, ma il completamento viene restituito alla sessione agente originale come risveglio interno, così l'agente può scrivere il messaggio di follow-up e allegare direttamente il video completato. Se scegli `tools.media.asyncCompletion.directSend`, i completamenti asincroni di `music_generate` e `video_generate` tentano prima il recapito diretto al canale, per poi ripiegare sul percorso di risveglio della sessione richiedente. -Mentre un'attività `video_generate` supportata da sessione è ancora attiva, lo strumento funge anche da protezione: chiamate ripetute a `video_generate` nella stessa sessione restituiscono lo stato dell'attività attiva invece di avviare una seconda generazione concorrente. Usa `action: "status"` quando desideri una ricerca esplicita di avanzamento/stato dal lato agent. +Mentre un'attività `video_generate` supportata dalla sessione è ancora attiva, lo strumento funge anche da guardrail: chiamate ripetute a `video_generate` nella stessa sessione restituiscono lo stato dell'attività attiva invece di avviare una seconda generazione concorrente. Usa `action: "status"` quando vuoi una ricerca esplicita di avanzamento/stato dal lato agente. **Cosa non crea attività:** - Turni heartbeat — sessione principale; vedi [Heartbeat](/it/gateway/heartbeat) -- Normali turni di chat interattiva -- Risposte dirette `/command` +- Turni di chat interattiva normali +- Risposte dirette a `/command` ## Ciclo di vita dell'attività ```mermaid stateDiagram-v2 [*] --> queued - queued --> running : agent starts - running --> succeeded : completes ok - running --> failed : error - running --> timed_out : timeout exceeded - running --> cancelled : operator cancels - queued --> lost : session gone > 5 min - running --> lost : session gone > 5 min + queued --> running : l'agente avvia + running --> succeeded : completamento riuscito + running --> failed : errore + running --> timed_out : timeout superato + running --> cancelled : l'operatore annulla + queued --> lost : sessione assente > 5 min + running --> lost : sessione assente > 5 min ``` -| Stato | Significato | -| ----------- | ------------------------------------------------------------------------- | -| `queued` | Creata, in attesa che l'agent inizi | -| `running` | Il turno dell'agent è in esecuzione attiva | +| Stato | Significato | +| ----------- | -------------------------------------------------------------------------- | +| `queued` | Creata, in attesa che l'agente si avvii | +| `running` | Il turno dell'agente è attivamente in esecuzione | | `succeeded` | Completata con successo | -| `failed` | Completata con un errore | -| `timed_out` | Ha superato il timeout configurato | -| `cancelled` | Interrotta dall'operatore tramite `openclaw tasks cancel` | +| `failed` | Completata con un errore | +| `timed_out` | Ha superato il timeout configurato | +| `cancelled` | Arrestata dall'operatore tramite `openclaw tasks cancel` | | `lost` | Il runtime ha perso lo stato di supporto autorevole dopo un periodo di tolleranza di 5 minuti | -Le transizioni avvengono automaticamente: quando termina l'esecuzione dell'agent associata, lo stato dell'attività si aggiorna di conseguenza. +Le transizioni avvengono automaticamente — quando termina l'esecuzione dell'agente associata, lo stato dell'attività si aggiorna di conseguenza. `lost` dipende dal runtime: - Attività ACP: i metadati della sessione figlia ACP di supporto sono scomparsi. -- Attività subagent: la sessione figlia di supporto è scomparsa dallo store agent di destinazione. -- Attività cron: il runtime cron non monitora più il job come attivo. -- Attività CLI: le attività di sessione figlia isolate usano la sessione figlia; le attività CLI supportate dalla chat usano invece il contesto di esecuzione live, quindi righe residue di sessione canale/gruppo/diretta non le mantengono attive. +- Attività di subagenti: la sessione figlia di supporto è scomparsa dallo store dell'agente di destinazione. +- Attività cron: il runtime cron non tiene più traccia del processo come attivo. +- Attività CLI: le attività isolate della sessione figlia usano la sessione figlia; le attività CLI supportate dalla chat usano invece il contesto di esecuzione live, quindi righe persistenti di sessione di canale/gruppo/diretta non le mantengono attive. -## Consegna e notifiche +## Recapito e notifiche -Quando un'attività raggiunge uno stato terminale, OpenClaw ti notifica. Esistono due percorsi di consegna: +Quando un'attività raggiunge uno stato terminale, OpenClaw ti notifica. Esistono due percorsi di recapito: -**Consegna diretta** — se l'attività ha una destinazione di canale (il `requesterOrigin`), il messaggio di completamento viene inviato direttamente a quel canale (Telegram, Discord, Slack, ecc.). Per i completamenti dei subagent, OpenClaw preserva anche l'instradamento di thread/topic associati quando disponibile e può riempire un `to` / account mancante dalla route memorizzata della sessione richiedente (`lastChannel` / `lastTo` / `lastAccountId`) prima di rinunciare alla consegna diretta. +**Recapito diretto** — se l'attività ha una destinazione di canale (`requesterOrigin`), il messaggio di completamento viene inviato direttamente a quel canale (Telegram, Discord, Slack, ecc.). Per i completamenti dei subagenti, OpenClaw preserva anche l'instradamento di thread/topic associato quando disponibile e può riempire un valore `to` / account mancante dalla route memorizzata della sessione richiedente (`lastChannel` / `lastTo` / `lastAccountId`) prima di rinunciare al recapito diretto. -**Consegna in coda alla sessione** — se la consegna diretta fallisce o non è impostata alcuna origine, l'aggiornamento viene messo in coda come evento di sistema nella sessione del richiedente e compare al prossimo heartbeat. +**Recapito in coda alla sessione** — se il recapito diretto fallisce o non è impostata alcuna origine, l'aggiornamento viene accodato come evento di sistema nella sessione del richiedente e appare al heartbeat successivo. -Il completamento dell'attività attiva un risveglio heartbeat immediato, così puoi vedere rapidamente il risultato: non devi aspettare il prossimo tick heartbeat pianificato. +Il completamento dell'attività attiva un risveglio heartbeat immediato, così vedi rapidamente il risultato — non devi aspettare il successivo tick heartbeat pianificato. -Questo significa che il flusso di lavoro normale è basato su push: avvia una volta il lavoro distaccato, poi lascia che il runtime ti risvegli o ti notifichi al completamento. Interroga lo stato dell'attività solo quando hai bisogno di debug, intervento o di un audit esplicito. +Questo significa che il normale flusso di lavoro è basato su push: avvia una sola volta il lavoro scollegato, poi lascia che il runtime ti risvegli o ti notifichi il completamento. Esegui il polling dello stato dell'attività solo quando ti serve debug, intervento o un audit esplicito. ### Criteri di notifica -Controlla quanto vuoi essere informato su ciascuna attività: +Controlla quante informazioni ricevi per ogni attività: -| Criterio | Cosa viene consegnato | +| Criterio | Cosa viene recapitato | | --------------------- | ------------------------------------------------------------------------- | -| `done_only` (predefinito) | Solo lo stato terminale (succeeded, failed, ecc.) — **questo è il predefinito** | +| `done_only` (predefinito) | Solo lo stato terminale (`succeeded`, `failed`, ecc.) — **questo è il valore predefinito** | | `state_changes` | Ogni transizione di stato e aggiornamento di avanzamento | | `silent` | Nulla | -Modifica il criterio mentre un'attività è in esecuzione: +Cambia il criterio mentre un'attività è in esecuzione: ```bash openclaw tasks notify state_changes @@ -165,7 +165,7 @@ openclaw tasks notify state_changes openclaw tasks list [--runtime ] [--status ] [--json] ``` -Colonne di output: ID attività, Tipo, Stato, Consegna, ID esecuzione, Sessione figlia, Riepilogo. +Colonne di output: ID attività, tipo, stato, recapito, Run ID, sessione figlia, riepilogo. ### `tasks show` @@ -173,7 +173,7 @@ Colonne di output: ID attività, Tipo, Stato, Consegna, ID esecuzione, Sessione openclaw tasks show ``` -Il token di ricerca accetta un ID attività, un ID esecuzione o una chiave sessione. Mostra il record completo, inclusi tempi, stato di consegna, errore e riepilogo terminale. +Il token di ricerca accetta un ID attività, un run ID o una chiave sessione. Mostra il record completo, inclusi tempi, stato del recapito, errore e riepilogo terminale. ### `tasks cancel` @@ -181,7 +181,7 @@ Il token di ricerca accetta un ID attività, un ID esecuzione o una chiave sessi openclaw tasks cancel ``` -Per le attività ACP e subagent, questo termina la sessione figlia. Lo stato passa a `cancelled` e viene inviata una notifica di consegna. +Per le attività ACP e dei subagenti, questo termina la sessione figlia. Per le attività tracciate dalla CLI, l'annullamento viene registrato nel registro delle attività (non esiste un handle di runtime figlio separato). Lo stato passa a `cancelled` e, se applicabile, viene inviata una notifica di recapito. ### `tasks notify` @@ -197,14 +197,14 @@ openclaw tasks audit [--json] Evidenzia problemi operativi. I risultati compaiono anche in `openclaw status` quando vengono rilevati problemi. -| Risultato | Gravità | Trigger | -| -------------------------- | ------- | ----------------------------------------------------- | -| `stale_queued` | warn | In coda da più di 10 minuti | -| `stale_running` | error | In esecuzione da più di 30 minuti | -| `lost` | error | La proprietà dell'attività supportata dal runtime è scomparsa | -| `delivery_failed` | warn | La consegna è fallita e il criterio di notifica non è `silent` | -| `missing_cleanup` | warn | Attività terminale senza timestamp di pulizia | -| `inconsistent_timestamps` | warn | Violazione della timeline (ad esempio terminata prima di iniziare) | +| Risultato | Gravità | Trigger | +| -------------------------- | ------- | ---------------------------------------------------- | +| `stale_queued` | warn | In coda da più di 10 minuti | +| `stale_running` | error | In esecuzione da più di 30 minuti | +| `lost` | error | La proprietà del task supportata dal runtime è scomparsa | +| `delivery_failed` | warn | Il recapito è fallito e il criterio di notifica non è `silent` | +| `missing_cleanup` | warn | Attività terminale senza timestamp di pulizia | +| `inconsistent_timestamps` | warn | Violazione della timeline (ad esempio, terminata prima di iniziare) | ### `tasks maintenance` @@ -213,21 +213,21 @@ openclaw tasks maintenance [--json] openclaw tasks maintenance --apply [--json] ``` -Usa questo comando per visualizzare in anteprima o applicare riconciliazione, marcatura della pulizia ed eliminazione per le attività e lo stato di Task Flow. +Usa questo comando per vedere in anteprima o applicare riconciliazione, marcatura della pulizia ed eliminazione per le attività e lo stato di Task Flow. La riconciliazione dipende dal runtime: -- Le attività ACP/subagent controllano la sessione figlia di supporto. -- Le attività cron controllano se il runtime cron possiede ancora il job. -- Le attività CLI supportate dalla chat controllano il relativo contesto di esecuzione live, non solo la riga della sessione chat. +- Le attività ACP/subagenti controllano la sessione figlia di supporto. +- Le attività cron controllano se il runtime cron possiede ancora il processo. +- Le attività CLI supportate dalla chat controllano il contesto di esecuzione live proprietario, non solo la riga della sessione chat. -Anche la pulizia del completamento dipende dal runtime: +Anche la pulizia al completamento dipende dal runtime: -- Il completamento dei subagent chiude, nei limiti del possibile, le schede/processi del browser tracciati per la sessione figlia prima che prosegua la pulizia dell'annuncio. -- Il completamento cron isolato chiude, nei limiti del possibile, le schede/processi del browser tracciati per la sessione cron prima che l'esecuzione venga completamente smantellata. -- La consegna cron isolata attende, quando necessario, il follow-up dei subagent discendenti e sopprime il testo di conferma del parent ormai obsoleto invece di annunciarlo. -- La consegna del completamento dei subagent preferisce il testo visibile più recente dell'assistente; se è vuoto ripiega sul testo più recente sanitizzato di tool/toolResult, e le esecuzioni di sole chiamate tool terminate per timeout possono essere ridotte a un breve riepilogo di avanzamento parziale. -- Gli errori di pulizia non mascherano il vero esito dell'attività. +- Il completamento dei subagenti chiude, per quanto possibile, le schede/processi del browser tracciati per la sessione figlia prima che continui la pulizia dell'annuncio. +- Il completamento cron isolato chiude, per quanto possibile, le schede/processi del browser tracciati per la sessione cron prima che l'esecuzione venga completamente smantellata. +- Il recapito cron isolato attende il follow-up del subagente discendente quando necessario e sopprime il testo di conferma del padre ormai obsoleto invece di annunciarlo. +- Il recapito del completamento dei subagenti preferisce l'ultimo testo visibile dell'assistente; se è vuoto, ripiega sull'ultimo testo `tool`/`toolResult` sanificato, e le esecuzioni basate solo su chiamate di strumenti andate in timeout possono ridursi a un breve riepilogo del progresso parziale. +- I fallimenti della pulizia non mascherano il reale esito dell'attività. ### `tasks flow list|show|cancel` @@ -237,21 +237,21 @@ openclaw tasks flow show [--json] openclaw tasks flow cancel ``` -Usa questi comandi quando ciò che ti interessa è il Task Flow di orchestrazione piuttosto che un singolo record di attività in background. +Usa questi comandi quando l'elemento che ti interessa è il Task Flow di orchestrazione piuttosto che un singolo record di attività in background. -## Bacheca attività della chat (`/tasks`) +## Bacheca attività chat (`/tasks`) Usa `/tasks` in qualsiasi sessione chat per vedere le attività in background collegate a quella sessione. La bacheca mostra -attività attive e completate di recente con runtime, stato, tempi e dettagli su avanzamento o errore. +attività attive e completate di recente con runtime, stato, tempi e dettagli di avanzamento o errore. -Quando la sessione corrente non ha attività collegate visibili, `/tasks` ripiega sui conteggi attività locali dell'agent -così ottieni comunque una panoramica senza esporre dettagli di altre sessioni. +Quando la sessione corrente non ha attività collegate visibili, `/tasks` ripiega sui conteggi delle attività locali dell'agente +così hai comunque una panoramica senza esporre dettagli di altre sessioni. -Per il registro completo dell'operatore, usa la CLI: `openclaw tasks list`. +Per il registro operativo completo, usa la CLI: `openclaw tasks list`. -## Integrazione stato (pressione attività) +## Integrazione dello stato (pressione delle attività) -`openclaw status` include un riepilogo immediato delle attività: +`openclaw status` include un riepilogo delle attività immediatamente consultabile: ``` Tasks: 3 queued · 2 running · 1 issues @@ -259,16 +259,17 @@ Tasks: 3 queued · 2 running · 1 issues Il riepilogo riporta: -- **active** — conteggio di `queued` + `running` -- **failures** — conteggio di `failed` + `timed_out` + `lost` -- **byRuntime** — ripartizione per `acp`, `subagent`, `cron`, `cli` +- **active** — numero di `queued` + `running` +- **failures** — numero di `failed` + `timed_out` + `lost` +- **byRuntime** — suddivisione per `acp`, `subagent`, `cron`, `cli` -Sia `/status` sia lo strumento `session_status` usano uno snapshot delle attività che tiene conto della pulizia: si dà priorità alle attività attive, le righe completate obsolete vengono nascoste e i guasti recenti emergono solo quando non rimane lavoro attivo. -Questo mantiene la scheda di stato concentrata su ciò che conta in questo momento. +Sia `/status` sia lo strumento `session_status` usano uno snapshot delle attività consapevole della pulizia: vengono privilegiate le attività attive, +le righe completate obsolete vengono nascoste e gli errori recenti emergono solo quando non resta alcun lavoro attivo. +In questo modo la scheda di stato resta focalizzata su ciò che conta in questo momento. ## Archiviazione e manutenzione -### Dove si trovano le attività +### Dove risiedono le attività I record delle attività vengono mantenuti in SQLite in: @@ -276,50 +277,50 @@ I record delle attività vengono mantenuti in SQLite in: $OPENCLAW_STATE_DIR/tasks/runs.sqlite ``` -Il registro viene caricato in memoria all'avvio del gateway e sincronizza le scritture su SQLite per garantire la durabilità tra i riavvii. +Il registro viene caricato in memoria all'avvio del gateway e sincronizza le scritture su SQLite per garantire la persistenza attraverso i riavvii. ### Manutenzione automatica -Uno sweeper viene eseguito ogni **60 secondi** e gestisce tre aspetti: +Un processo di sweep viene eseguito ogni **60 secondi** e gestisce tre aspetti: -1. **Riconciliazione** — controlla se le attività attive hanno ancora un supporto runtime autorevole. Le attività ACP/subagent usano lo stato della sessione figlia, le attività cron usano la proprietà del job attivo e le attività CLI supportate dalla chat usano il relativo contesto di esecuzione. Se questo stato di supporto manca per più di 5 minuti, l'attività viene contrassegnata come `lost`. -2. **Marcatura della pulizia** — imposta un timestamp `cleanupAfter` sulle attività terminali (`endedAt + 7 days`). -3. **Eliminazione** — cancella i record oltre la data `cleanupAfter`. +1. **Riconciliazione** — verifica se le attività attive hanno ancora un supporto autorevole nel runtime. Le attività ACP/subagenti usano lo stato della sessione figlia, le attività cron usano la proprietà del job attivo e le attività CLI supportate dalla chat usano il contesto di esecuzione proprietario. Se quello stato di supporto manca per più di 5 minuti, l'attività viene contrassegnata come `lost`. +2. **Marcatura della pulizia** — imposta un timestamp `cleanupAfter` sulle attività terminali (`endedAt` + 7 giorni). +3. **Eliminazione** — elimina i record che hanno superato la data `cleanupAfter`. -**Conservazione**: i record delle attività terminali vengono mantenuti per **7 giorni**, poi eliminati automaticamente. Non è richiesta alcuna configurazione. +**Conservazione**: i record delle attività terminali vengono mantenuti per **7 giorni**, poi eliminati automaticamente. Non è necessaria alcuna configurazione. ## Come le attività si relazionano ad altri sistemi ### Attività e Task Flow -[Task Flow](/it/automation/taskflow) è il livello di orchestrazione dei flussi sopra le attività in background. Un singolo flusso può coordinare più attività nel corso della sua durata usando modalità di sincronizzazione gestite o mirror. Usa `openclaw tasks` per ispezionare i singoli record attività e `openclaw tasks flow` per ispezionare il flusso di orchestrazione. +[Task Flow](/it/automation/taskflow) è il livello di orchestrazione dei flussi sopra le attività in background. Un singolo flusso può coordinare più attività nel corso del suo ciclo di vita usando modalità di sincronizzazione gestite o mirror. Usa `openclaw tasks` per ispezionare i singoli record delle attività e `openclaw tasks flow` per ispezionare il flusso di orchestrazione. -Consulta [Task Flow](/it/automation/taskflow) per i dettagli. +Vedi [Task Flow](/it/automation/taskflow) per i dettagli. ### Attività e cron -Una **definizione** di job cron si trova in `~/.openclaw/cron/jobs.json`. **Ogni** esecuzione cron crea un record attività, sia nella sessione principale sia in isolamento. Le attività cron della sessione principale usano per impostazione predefinita il criterio di notifica `silent`, così monitorano senza generare notifiche. +Una **definizione** di job cron risiede in `~/.openclaw/cron/jobs.json`. **Ogni** esecuzione cron crea un record attività — sia per la sessione principale sia per quelle isolate. Le attività cron della sessione principale usano per impostazione predefinita il criterio di notifica `silent`, così vengono tracciate senza generare notifiche. -Consulta [Processi cron](/it/automation/cron-jobs). +Vedi [Cron Jobs](/it/automation/cron-jobs). ### Attività e heartbeat -Le esecuzioni heartbeat sono turni della sessione principale: non creano record attività. Quando un'attività viene completata, può attivare un risveglio heartbeat così puoi vedere rapidamente il risultato. +Le esecuzioni heartbeat sono turni della sessione principale — non creano record attività. Quando un'attività termina, può attivare un risveglio heartbeat così vedi il risultato rapidamente. -Consulta [Heartbeat](/it/gateway/heartbeat). +Vedi [Heartbeat](/it/gateway/heartbeat). ### Attività e sessioni -Un'attività può fare riferimento a una `childSessionKey` (dove viene eseguito il lavoro) e a una `requesterSessionKey` (chi l'ha avviata). Le sessioni sono il contesto della conversazione; le attività sono il monitoraggio dell'attività sopra di esse. +Un'attività può fare riferimento a una `childSessionKey` (dove viene eseguito il lavoro) e a una `requesterSessionKey` (chi l'ha avviata). Le sessioni sono il contesto della conversazione; le attività sono il tracciamento dell'attività costruito sopra quel contesto. -### Attività ed esecuzioni agent +### Attività ed esecuzioni dell'agente -Il `runId` di un'attività collega l'esecuzione agent che sta svolgendo il lavoro. Gli eventi del ciclo di vita dell'agent (inizio, fine, errore) aggiornano automaticamente lo stato dell'attività: non devi gestire manualmente il ciclo di vita. +Il `runId` di un'attività collega l'esecuzione dell'agente che sta svolgendo il lavoro. Gli eventi del ciclo di vita dell'agente (avvio, fine, errore) aggiornano automaticamente lo stato dell'attività — non devi gestire manualmente il ciclo di vita. ## Correlati -- [Automazione e attività](/it/automation) — tutti i meccanismi di automazione in sintesi +- [Automation & Tasks](/it/automation) — tutti i meccanismi di automazione in sintesi - [Task Flow](/it/automation/taskflow) — orchestrazione dei flussi sopra le attività -- [Attività pianificate](/it/automation/cron-jobs) — pianificazione del lavoro in background +- [Scheduled Tasks](/it/automation/cron-jobs) — pianificazione del lavoro in background - [Heartbeat](/it/gateway/heartbeat) — turni periodici della sessione principale -- [CLI: Tasks](/cli/index#tasks) — riferimento ai comandi CLI +- [CLI: Tasks](/cli/index#tasks) — riferimento dei comandi CLI diff --git a/docs/it/concepts/active-memory.md b/docs/it/concepts/active-memory.md new file mode 100644 index 000000000..9a15fa9da --- /dev/null +++ b/docs/it/concepts/active-memory.md @@ -0,0 +1,612 @@ +--- +read_when: + - Vuoi capire a cosa serve la memoria attiva + - Vuoi attivare la memoria attiva per un agente conversazionale + - Vuoi regolare il comportamento della memoria attiva senza abilitarla ovunque +summary: Un sotto-agente di memoria bloccante di proprietà del plugin che inserisce la memoria pertinente nelle sessioni di chat interattive +title: Memoria attiva +x-i18n: + generated_at: "2026-04-10T08:13:33Z" + model: gpt-5.4 + provider: openai + source_hash: 6a51437df4ae4d9d57764601dfcfcdadb269e2895bf49dc82b9f496c1b3cb341 + source_path: concepts/active-memory.md + workflow: 15 +--- + +# Memoria attiva + +La memoria attiva è un sotto-agente di memoria bloccante opzionale di proprietà del plugin che viene eseguito +prima della risposta principale per le sessioni conversazionali idonee. + +Esiste perché la maggior parte dei sistemi di memoria è capace ma reattiva. Si affida +all'agente principale per decidere quando cercare nella memoria, oppure all'utente per dire cose +come "ricorda questo" o "cerca nella memoria". A quel punto, il momento in cui la memoria avrebbe +reso la risposta naturale è già passato. + +La memoria attiva offre al sistema una possibilità limitata di far emergere memoria pertinente +prima che venga generata la risposta principale. + +## Incolla questo nel tuo agente + +Incolla questo nel tuo agente se vuoi abilitare la memoria attiva con una +configurazione autonoma e sicura per impostazione predefinita: + +```json5 +{ + plugins: { + entries: { + "active-memory": { + enabled: true, + config: { + enabled: true, + agents: ["main"], + allowedChatTypes: ["direct"], + modelFallbackPolicy: "default-remote", + queryMode: "recent", + promptStyle: "balanced", + timeoutMs: 15000, + maxSummaryChars: 220, + persistTranscripts: false, + logging: true, + }, + }, + }, + }, +} +``` + +Questo attiva il plugin per l'agente `main`, lo mantiene limitato per impostazione predefinita alle +sessioni in stile messaggio diretto, gli consente di ereditare prima il modello della sessione corrente e +consente comunque il fallback remoto integrato se non è disponibile alcun modello esplicito o ereditato. + +Dopo, riavvia il gateway: + +```bash +node scripts/run-node.mjs gateway --profile dev +``` + +Per ispezionarlo in tempo reale in una conversazione: + +```text +/verbose on +``` + +## Attiva la memoria attiva + +La configurazione più sicura è: + +1. abilitare il plugin +2. scegliere come target un agente conversazionale +3. mantenere il logging attivo solo durante la regolazione + +Inizia con questo in `openclaw.json`: + +```json5 +{ + plugins: { + entries: { + "active-memory": { + enabled: true, + config: { + agents: ["main"], + allowedChatTypes: ["direct"], + modelFallbackPolicy: "default-remote", + queryMode: "recent", + promptStyle: "balanced", + timeoutMs: 15000, + maxSummaryChars: 220, + persistTranscripts: false, + logging: true, + }, + }, + }, + }, +} +``` + +Poi riavvia il gateway: + +```bash +node scripts/run-node.mjs gateway --profile dev +``` + +Cosa significa: + +- `plugins.entries.active-memory.enabled: true` attiva il plugin +- `config.agents: ["main"]` abilita la memoria attiva solo per l'agente `main` +- `config.allowedChatTypes: ["direct"]` mantiene la memoria attiva abilitata solo per impostazione predefinita per le sessioni in stile messaggio diretto +- se `config.model` non è impostato, la memoria attiva eredita prima il modello della sessione corrente +- `config.modelFallbackPolicy: "default-remote"` mantiene come impostazione predefinita il fallback remoto integrato quando non è disponibile alcun modello esplicito o ereditato +- `config.promptStyle: "balanced"` usa lo stile di prompt predefinito per uso generale per la modalità `recent` +- la memoria attiva viene comunque eseguita solo su sessioni di chat persistenti interattive idonee + +## Come vederla + +La memoria attiva inserisce contesto di sistema nascosto per il modello. Non espone +tag raw `...` al client. + +## Interruttore della sessione + +Usa il comando del plugin quando vuoi mettere in pausa o riprendere la memoria attiva per la +sessione di chat corrente senza modificare la configurazione: + +```text +/active-memory status +/active-memory off +/active-memory on +``` + +Questo è limitato alla sessione. Non modifica +`plugins.entries.active-memory.enabled`, il targeting dell'agente o altre +configurazioni globali. + +Se vuoi che il comando scriva la configurazione e metta in pausa o riprenda la memoria attiva per +tutte le sessioni, usa la forma globale esplicita: + +```text +/active-memory status --global +/active-memory off --global +/active-memory on --global +``` + +La forma globale scrive `plugins.entries.active-memory.config.enabled`. Lascia +`plugins.entries.active-memory.enabled` attivo in modo che il comando resti disponibile per +riattivare la memoria attiva in seguito. + +Se vuoi vedere cosa sta facendo la memoria attiva in una sessione in tempo reale, attiva la modalità +verbose per quella sessione: + +```text +/verbose on +``` + +Con verbose abilitato, OpenClaw può mostrare: + +- una riga di stato della memoria attiva come `Active Memory: ok 842ms recent 34 chars` +- un riepilogo di debug leggibile come `Active Memory Debug: Lemon pepper wings with blue cheese.` + +Queste righe derivano dallo stesso passaggio della memoria attiva che alimenta il contesto di +sistema nascosto, ma sono formattate per le persone invece di esporre markup raw del prompt. + +Per impostazione predefinita, la trascrizione del sotto-agente di memoria bloccante è temporanea e viene eliminata +dopo il completamento dell'esecuzione. + +Flusso di esempio: + +```text +/verbose on +quali ali dovrei ordinare? +``` + +Forma prevista della risposta visibile: + +```text +...normale risposta dell'assistente... + +🧩 Active Memory: ok 842ms recent 34 chars +🔎 Active Memory Debug: Lemon pepper wings with blue cheese. +``` + +## Quando viene eseguita + +La memoria attiva usa due criteri: + +1. **Adesione esplicita nella configurazione** + Il plugin deve essere abilitato e l'id dell'agente corrente deve comparire in + `plugins.entries.active-memory.config.agents`. +2. **Idoneità rigorosa in fase di esecuzione** + Anche quando è abilitata e selezionata, la memoria attiva viene eseguita solo per + sessioni di chat persistenti interattive idonee. + +La regola effettiva è: + +```text +plugin abilitato ++ +id agente selezionato ++ +tipo di chat consentito ++ +sessione di chat persistente interattiva idonea += +la memoria attiva viene eseguita +``` + +Se uno qualsiasi di questi fallisce, la memoria attiva non viene eseguita. + +## Tipi di sessione + +`config.allowedChatTypes` controlla quali tipi di conversazioni possono eseguire la Memoria +attiva. + +Il valore predefinito è: + +```json5 +allowedChatTypes: ["direct"] +``` + +Questo significa che la Memoria attiva viene eseguita per impostazione predefinita nelle sessioni in stile messaggio diretto, ma +non nelle sessioni di gruppo o di canale a meno che tu non le abiliti esplicitamente. + +Esempi: + +```json5 +allowedChatTypes: ["direct"] +``` + +```json5 +allowedChatTypes: ["direct", "group"] +``` + +```json5 +allowedChatTypes: ["direct", "group", "channel"] +``` + +## Dove viene eseguita + +La memoria attiva è una funzionalità di arricchimento conversazionale, non una +funzionalità di inferenza valida per tutta la piattaforma. + +| Superficie | Esegue la memoria attiva? | +| ------------------------------------------------------------------- | ------------------------------------------------------- | +| Sessioni persistenti di chat in Control UI / web chat | Sì, se il plugin è abilitato e l'agente è selezionato | +| Altre sessioni di canale interattive sullo stesso percorso di chat persistente | Sì, se il plugin è abilitato e l'agente è selezionato | +| Esecuzioni headless one-shot | No | +| Esecuzioni heartbeat/background | No | +| Percorsi interni generici `agent-command` | No | +| Esecuzione di sotto-agenti/helper interni | No | + +## Perché usarla + +Usa la memoria attiva quando: + +- la sessione è persistente e rivolta all'utente +- l'agente ha una memoria a lungo termine significativa da cercare +- continuità e personalizzazione contano più del puro determinismo del prompt + +Funziona particolarmente bene per: + +- preferenze stabili +- abitudini ricorrenti +- contesto utente a lungo termine che dovrebbe emergere in modo naturale + +È poco adatta per: + +- automazione +- worker interni +- attività API one-shot +- contesti in cui una personalizzazione nascosta sarebbe sorprendente + +## Come funziona + +La forma di esecuzione è: + +```mermaid +flowchart LR + U["Messaggio utente"] --> Q["Crea query di memoria"] + Q --> R["Sotto-agente di memoria bloccante della memoria attiva"] + R -->|NONE or empty| M["Risposta principale"] + R -->|relevant summary| I["Aggiungi contesto di sistema nascosto active_memory_plugin"] + I --> M["Risposta principale"] +``` + +Il sotto-agente di memoria bloccante può usare solo: + +- `memory_search` +- `memory_get` + +Se la connessione è debole, dovrebbe restituire `NONE`. + +## Modalità di query + +`config.queryMode` controlla quanta parte della conversazione vede il sotto-agente di memoria bloccante. + +## Stili di prompt + +`config.promptStyle` controlla quanto il sotto-agente di memoria bloccante sia +propenso o rigoroso quando decide se restituire memoria. + +Stili disponibili: + +- `balanced`: valore predefinito per uso generale per la modalità `recent` +- `strict`: il meno propenso; ideale quando vuoi pochissima influenza dal contesto vicino +- `contextual`: il più favorevole alla continuità; ideale quando la cronologia della conversazione dovrebbe contare di più +- `recall-heavy`: più disposto a far emergere memoria anche con corrispondenze meno forti ma comunque plausibili +- `precision-heavy`: preferisce in modo aggressivo `NONE` a meno che la corrispondenza non sia ovvia +- `preference-only`: ottimizzato per preferiti, abitudini, routine, gusti e fatti personali ricorrenti + +Mappatura predefinita quando `config.promptStyle` non è impostato: + +```text +message -> strict +recent -> balanced +full -> contextual +``` + +Se imposti `config.promptStyle` esplicitamente, quell'override prevale. + +Esempio: + +```json5 +promptStyle: "preference-only" +``` + +## Criterio di fallback del modello + +Se `config.model` non è impostato, la Memoria attiva prova a risolvere un modello in questo ordine: + +```text +modello esplicito del plugin +-> modello della sessione corrente +-> modello primario dell'agente +-> fallback remoto integrato opzionale +``` + +`config.modelFallbackPolicy` controlla l'ultimo passaggio. + +Valore predefinito: + +```json5 +modelFallbackPolicy: "default-remote" +``` + +Altra opzione: + +```json5 +modelFallbackPolicy: "resolved-only" +``` + +Usa `resolved-only` se vuoi che la Memoria attiva salti il recupero invece di usare +il valore predefinito remoto integrato quando non è disponibile alcun modello esplicito o +ereditato. + +## Meccanismi di uscita avanzati + +Queste opzioni intenzionalmente non fanno parte della configurazione consigliata. + +`config.thinking` può sostituire il livello di thinking del sotto-agente di memoria bloccante: + +```json5 +thinking: "medium" +``` + +Valore predefinito: + +```json5 +thinking: "off" +``` + +Non abilitarlo per impostazione predefinita. La Memoria attiva viene eseguita nel percorso della risposta, quindi tempo di +thinking aggiuntivo aumenta direttamente la latenza visibile all'utente. + +`config.promptAppend` aggiunge istruzioni supplementari per l'operatore dopo il prompt predefinito della Memoria +attiva e prima del contesto della conversazione: + +```json5 +promptAppend: "Dai priorità alle preferenze stabili a lungo termine rispetto agli eventi una tantum." +``` + +`config.promptOverride` sostituisce il prompt predefinito della Memoria attiva. OpenClaw +continua comunque ad aggiungere dopo il contesto della conversazione: + +```json5 +promptOverride: "Sei un agente di ricerca della memoria. Restituisci NONE o un fatto utente compatto." +``` + +La personalizzazione del prompt non è consigliata a meno che tu non stia testando deliberatamente un +contratto di recupero diverso. Il prompt predefinito è regolato per restituire `NONE` +oppure un contesto compatto di fatti utente per il modello principale. + +### `message` + +Viene inviato solo l'ultimo messaggio dell'utente. + +```text +Solo l'ultimo messaggio dell'utente +``` + +Usalo quando: + +- vuoi il comportamento più veloce +- vuoi il bias più forte verso il recupero di preferenze stabili +- i turni successivi non hanno bisogno del contesto conversazionale + +Timeout consigliato: + +- inizia intorno a `3000` a `5000` ms + +### `recent` + +Vengono inviati l'ultimo messaggio dell'utente più una piccola coda conversazionale recente. + +```text +Coda recente della conversazione: +user: ... +assistant: ... +user: ... + +Ultimo messaggio dell'utente: +... +``` + +Usalo quando: + +- vuoi un miglior equilibrio tra velocità e ancoraggio conversazionale +- le domande di follow-up spesso dipendono dagli ultimi pochi turni + +Timeout consigliato: + +- inizia intorno a `15000` ms + +### `full` + +L'intera conversazione viene inviata al sotto-agente di memoria bloccante. + +```text +Contesto completo della conversazione: +user: ... +assistant: ... +user: ... +... +``` + +Usalo quando: + +- la massima qualità del recupero conta più della latenza +- la conversazione contiene impostazioni importanti molto indietro nel thread + +Timeout consigliato: + +- aumentalo in modo significativo rispetto a `message` o `recent` +- inizia intorno a `15000` ms o più, a seconda della dimensione del thread + +In generale, il timeout dovrebbe aumentare con la dimensione del contesto: + +```text +message < recent < full +``` + +## Persistenza della trascrizione + +Le esecuzioni del sotto-agente di memoria bloccante della memoria attiva creano una vera trascrizione `session.jsonl` durante la chiamata del sotto-agente di memoria bloccante. + +Per impostazione predefinita, quella trascrizione è temporanea: + +- viene scritta in una directory temporanea +- viene usata solo per l'esecuzione del sotto-agente di memoria bloccante +- viene eliminata immediatamente dopo la fine dell'esecuzione + +Se vuoi conservare su disco quelle trascrizioni del sotto-agente di memoria bloccante per debug o +ispezione, attiva esplicitamente la persistenza: + +```json5 +{ + plugins: { + entries: { + "active-memory": { + enabled: true, + config: { + agents: ["main"], + persistTranscripts: true, + transcriptDir: "active-memory", + }, + }, + }, + }, +} +``` + +Quando è abilitata, la memoria attiva archivia le trascrizioni in una directory separata sotto la +cartella delle sessioni dell'agente di destinazione, non nel percorso principale della trascrizione +della conversazione utente. + +Il layout predefinito è, concettualmente: + +```text +agents//sessions/active-memory/.jsonl +``` + +Puoi modificare la sottodirectory relativa con `config.transcriptDir`. + +Usalo con attenzione: + +- le trascrizioni del sotto-agente di memoria bloccante possono accumularsi rapidamente nelle sessioni molto attive +- la modalità di query `full` può duplicare molto contesto conversazionale +- queste trascrizioni contengono contesto nascosto del prompt e memorie recuperate + +## Configurazione + +Tutta la configurazione della memoria attiva si trova in: + +```text +plugins.entries.active-memory +``` + +I campi più importanti sono: + +| Chiave | Tipo | Significato | +| --------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | +| `enabled` | `boolean` | Abilita il plugin stesso | +| `config.agents` | `string[]` | ID agente che possono usare la memoria attiva | +| `config.model` | `string` | Riferimento facoltativo al modello del sotto-agente di memoria bloccante; se non è impostato, la memoria attiva usa il modello della sessione corrente | +| `config.queryMode` | `"message" \| "recent" \| "full"` | Controlla quanta parte della conversazione vede il sotto-agente di memoria bloccante | +| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | Controlla quanto il sotto-agente di memoria bloccante sia propenso o rigoroso nel decidere se restituire memoria | +| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | Override avanzato del thinking per il sotto-agente di memoria bloccante; valore predefinito `off` per velocità | +| `config.promptOverride` | `string` | Sostituzione avanzata completa del prompt; non consigliata per l'uso normale | +| `config.promptAppend` | `string` | Istruzioni supplementari avanzate aggiunte al prompt predefinito o sostituito | +| `config.timeoutMs` | `number` | Timeout rigido per il sotto-agente di memoria bloccante | +| `config.maxSummaryChars` | `number` | Numero massimo totale di caratteri consentiti nel riepilogo di active-memory | +| `config.logging` | `boolean` | Emette log della memoria attiva durante la regolazione | +| `config.persistTranscripts` | `boolean` | Mantiene su disco le trascrizioni del sotto-agente di memoria bloccante invece di eliminare i file temporanei | +| `config.transcriptDir` | `string` | Directory relativa delle trascrizioni del sotto-agente di memoria bloccante sotto la cartella delle sessioni dell'agente | + +Campi utili per la regolazione: + +| Chiave | Tipo | Significato | +| ----------------------------- | -------- | ----------------------------------------------------------------- | +| `config.maxSummaryChars` | `number` | Numero massimo totale di caratteri consentiti nel riepilogo di active-memory | +| `config.recentUserTurns` | `number` | Turni utente precedenti da includere quando `queryMode` è `recent` | +| `config.recentAssistantTurns` | `number` | Turni assistente precedenti da includere quando `queryMode` è `recent` | +| `config.recentUserChars` | `number` | Numero massimo di caratteri per turno utente recente | +| `config.recentAssistantChars` | `number` | Numero massimo di caratteri per turno assistente recente | +| `config.cacheTtlMs` | `number` | Riutilizzo della cache per query identiche ripetute | + +## Configurazione consigliata + +Inizia con `recent`. + +```json5 +{ + plugins: { + entries: { + "active-memory": { + enabled: true, + config: { + agents: ["main"], + queryMode: "recent", + promptStyle: "balanced", + timeoutMs: 15000, + maxSummaryChars: 220, + logging: true, + }, + }, + }, + }, +} +``` + +Se vuoi ispezionare il comportamento in tempo reale durante la regolazione, usa `/verbose on` nella +sessione invece di cercare un comando di debug separato per active-memory. + +Poi passa a: + +- `message` se vuoi una latenza inferiore +- `full` se decidi che il contesto aggiuntivo vale un sotto-agente di memoria bloccante più lento + +## Debug + +Se la memoria attiva non compare dove ti aspetti: + +1. Conferma che il plugin sia abilitato in `plugins.entries.active-memory.enabled`. +2. Conferma che l'ID dell'agente corrente sia elencato in `config.agents`. +3. Conferma che il test avvenga tramite una sessione di chat persistente interattiva. +4. Attiva `config.logging: true` e osserva i log del gateway. +5. Verifica che la ricerca in memoria funzioni con `openclaw memory status --deep`. + +Se i risultati di memoria sono troppo rumorosi, restringi: + +- `maxSummaryChars` + +Se la memoria attiva è troppo lenta: + +- riduci `queryMode` +- riduci `timeoutMs` +- riduci il numero di turni recenti +- riduci i limiti di caratteri per turno + +## Pagine correlate + +- [Ricerca nella memoria](/it/concepts/memory-search) +- [Riferimento della configurazione della memoria](/it/reference/memory-config) +- [Configurazione del Plugin SDK](/it/plugins/sdk-setup) diff --git a/docs/it/concepts/agent-loop.md b/docs/it/concepts/agent-loop.md index 42495c856..e0bccd80b 100644 --- a/docs/it/concepts/agent-loop.md +++ b/docs/it/concepts/agent-loop.md @@ -1,73 +1,73 @@ --- read_when: - - Hai bisogno di una panoramica esatta del loop dell'agente o degli eventi del ciclo di vita + - Hai bisogno di una guida dettagliata esatta del loop dell'agente o degli eventi del ciclo di vita summary: Ciclo di vita del loop dell'agente, stream e semantica di attesa title: Loop dell'agente x-i18n: - generated_at: "2026-04-09T01:27:50Z" + generated_at: "2026-04-10T08:13:32Z" model: gpt-5.4 provider: openai - source_hash: 32d3a73df8dabf449211a6183a70dcfd2a9b6f584dc76d0c4c9147582b2ca6a1 + source_hash: b6831a5b11e9100e49f650feca51ab44a2bef242ce1b5db2766d0b3b5c5ba729 source_path: concepts/agent-loop.md workflow: 15 --- # Loop dell'agente (OpenClaw) -Un loop agentico è l'esecuzione completa “reale” di un agente: acquisizione → assemblaggio del contesto → inferenza del modello → +Un loop agentico è l'esecuzione completa e “reale” di un agente: acquisizione → assemblaggio del contesto → inferenza del modello → esecuzione degli strumenti → risposte in streaming → persistenza. È il percorso autorevole che trasforma un messaggio in azioni e in una risposta finale, mantenendo coerente lo stato della sessione. In OpenClaw, un loop è una singola esecuzione serializzata per sessione che emette eventi di ciclo di vita e di stream -mentre il modello ragiona, chiama strumenti e trasmette output in streaming. Questo documento spiega come questo loop autentico -è collegato end-to-end. +mentre il modello elabora, chiama strumenti e trasmette l'output in streaming. Questo documento spiega come questo loop autentico è +collegato end-to-end. ## Punti di ingresso -- RPC Gateway: `agent` e `agent.wait`. +- Gateway RPC: `agent` e `agent.wait`. - CLI: comando `agent`. ## Come funziona (panoramica) -1. L'RPC `agent` valida i parametri, risolve la sessione (sessionKey/sessionId), rende persistenti i metadati della sessione, restituisce immediatamente `{ runId, acceptedAt }`. +1. L'RPC `agent` convalida i parametri, risolve la sessione (sessionKey/sessionId), persiste i metadati della sessione e restituisce immediatamente `{ runId, acceptedAt }`. 2. `agentCommand` esegue l'agente: - - risolve il modello + i valori predefiniti di thinking/verbose + - risolve i valori predefiniti di model + thinking/verbose - carica lo snapshot delle Skills - - chiama `runEmbeddedPiAgent` (runtime pi-agent-core) - - emette **fine/errore del ciclo di vita** se il loop incorporato non ne emette uno + - chiama `runEmbeddedPiAgent` (runtime di pi-agent-core) + - emette **lifecycle end/error** se il loop incorporato non ne emette uno 3. `runEmbeddedPiAgent`: - - serializza le esecuzioni tramite code per sessione e globali - - risolve il profilo di modello + autenticazione e costruisce la sessione pi - - si sottoscrive agli eventi pi e trasmette in streaming i delta dell'assistente/degli strumenti + - serializza le esecuzioni tramite code per-sessione e globali + - risolve il profilo model + auth e costruisce la sessione pi + - si sottoscrive agli eventi pi e trasmette in streaming i delta assistant/tool - applica il timeout -> interrompe l'esecuzione se superato - - restituisce payload + metadati di utilizzo + - restituisce payload e metadati di utilizzo 4. `subscribeEmbeddedPiSession` collega gli eventi di pi-agent-core allo stream `agent` di OpenClaw: - eventi degli strumenti => `stream: "tool"` - delta dell'assistente => `stream: "assistant"` - eventi del ciclo di vita => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`) 5. `agent.wait` usa `waitForAgentRun`: - - attende la **fine/errore del ciclo di vita** per `runId` + - attende **lifecycle end/error** per `runId` - restituisce `{ status: ok|error|timeout, startedAt, endedAt, error? }` ## Accodamento + concorrenza -- Le esecuzioni sono serializzate per chiave di sessione (corsia della sessione) e facoltativamente tramite una corsia globale. -- Questo evita race tra strumenti/sessione e mantiene coerente la cronologia della sessione. +- Le esecuzioni sono serializzate per chiave di sessione (corsia di sessione) e facoltativamente tramite una corsia globale. +- Questo previene race condition tra strumenti/sessioni e mantiene coerente la cronologia della sessione. - I canali di messaggistica possono scegliere modalità di coda (collect/steer/followup) che alimentano questo sistema di corsie. - Vedi [Coda dei comandi](/it/concepts/queue). + Vedi [Command Queue](/it/concepts/queue). -## Preparazione della sessione + workspace +## Preparazione di sessione + workspace -- Il workspace viene risolto e creato; le esecuzioni in sandbox possono reindirizzare a una root del workspace sandbox. -- Le Skills vengono caricate (o riutilizzate da uno snapshot) e iniettate nell'ambiente e nel prompt. -- I file bootstrap/contesto vengono risolti e iniettati nel report del prompt di sistema. +- Il workspace viene risolto e creato; le esecuzioni sandboxed possono reindirizzare a una radice workspace sandbox. +- Le Skills vengono caricate (o riutilizzate da uno snapshot) e iniettate nell'env e nel prompt. +- I file bootstrap/context vengono risolti e iniettati nel report del prompt di sistema. - Viene acquisito un lock di scrittura della sessione; `SessionManager` viene aperto e preparato prima dello streaming. ## Assemblaggio del prompt + prompt di sistema -- Il prompt di sistema viene costruito a partire dal prompt di base di OpenClaw, dal prompt delle Skills, dal contesto bootstrap e dagli override per esecuzione. +- Il prompt di sistema viene costruito a partire dal prompt base di OpenClaw, dal prompt delle Skills, dal contesto bootstrap e dagli override per esecuzione. - Vengono applicati i limiti specifici del modello e i token di riserva per la compattazione. -- Vedi [Prompt di sistema](/it/concepts/system-prompt) per ciò che vede il modello. +- Vedi [System prompt](/it/concepts/system-prompt) per sapere cosa vede il modello. ## Punti di hook (dove puoi intercettare) @@ -78,46 +78,46 @@ OpenClaw ha due sistemi di hook: ### Hook interni (hook del Gateway) -- **`agent:bootstrap`**: viene eseguito durante la costruzione dei file bootstrap prima che il prompt di sistema sia finalizzato. +- **`agent:bootstrap`**: viene eseguito durante la costruzione dei file bootstrap prima che il prompt di sistema venga finalizzato. Usalo per aggiungere/rimuovere file di contesto bootstrap. -- **Hook dei comandi**: `/new`, `/reset`, `/stop` e altri eventi dei comandi (vedi la documentazione Hooks). +- **Hook di comando**: `/new`, `/reset`, `/stop` e altri eventi di comando (vedi il documento Hooks). Vedi [Hooks](/it/automation/hooks) per configurazione ed esempi. -### Hook plugin (ciclo di vita dell'agente + del gateway) +### Hook plugin (ciclo di vita di agente + gateway) Questi vengono eseguiti all'interno del loop dell'agente o della pipeline del gateway: -- **`before_model_resolve`**: viene eseguito prima della sessione (senza `messages`) per sovrascrivere in modo deterministico provider/modello prima della risoluzione del modello. -- **`before_prompt_build`**: viene eseguito dopo il caricamento della sessione (con `messages`) per iniettare `prependContext`, `systemPrompt`, `prependSystemContext` o `appendSystemContext` prima dell'invio del prompt. Usa `prependContext` per testo dinamico per turno e i campi di contesto di sistema per indicazioni stabili che devono trovarsi nello spazio del prompt di sistema. +- **`before_model_resolve`**: viene eseguito prima della sessione (senza `messages`) per sovrascrivere in modo deterministico provider/model prima della risoluzione del modello. +- **`before_prompt_build`**: viene eseguito dopo il caricamento della sessione (con `messages`) per iniettare `prependContext`, `systemPrompt`, `prependSystemContext` o `appendSystemContext` prima dell'invio del prompt. Usa `prependContext` per testo dinamico per-turno e i campi di contesto di sistema per indicazioni stabili che dovrebbero stare nello spazio del prompt di sistema. - **`before_agent_start`**: hook di compatibilità legacy che può essere eseguito in una delle due fasi; preferisci gli hook espliciti sopra. -- **`before_agent_reply`**: viene eseguito dopo le azioni inline e prima della chiamata all'LLM, consentendo a un plugin di prendersi carico del turno e restituire una risposta sintetica o silenziare completamente il turno. -- **`agent_end`**: ispeziona l'elenco finale dei messaggi e i metadati di esecuzione dopo il completamento. +- **`before_agent_reply`**: viene eseguito dopo le azioni inline e prima della chiamata LLM, permettendo a un plugin di prendere in carico il turno e restituire una risposta sintetica o silenziare completamente il turno. +- **`agent_end`**: ispeziona l'elenco finale dei messaggi e i metadati dell'esecuzione dopo il completamento. - **`before_compaction` / `after_compaction`**: osserva o annota i cicli di compattazione. - **`before_tool_call` / `after_tool_call`**: intercetta parametri/risultati degli strumenti. -- **`before_install`**: ispeziona i risultati della scansione integrata e può facoltativamente bloccare installazioni di Skills o plugin. +- **`before_install`**: ispeziona i risultati della scansione integrata e può facoltativamente bloccare installazioni di skill o plugin. - **`tool_result_persist`**: trasforma in modo sincrono i risultati degli strumenti prima che vengano scritti nella trascrizione della sessione. - **`message_received` / `message_sending` / `message_sent`**: hook per messaggi in ingresso + in uscita. - **`session_start` / `session_end`**: confini del ciclo di vita della sessione. - **`gateway_start` / `gateway_stop`**: eventi del ciclo di vita del gateway. -Regole decisionali degli hook per le protezioni in uscita/degli strumenti: +Regole decisionali degli hook per le protezioni su uscita/strumenti: -- `before_tool_call`: `{ block: true }` è terminale e interrompe i gestori a priorità inferiore. -- `before_tool_call`: `{ block: false }` non ha effetto e non annulla un blocco precedente. -- `before_install`: `{ block: true }` è terminale e interrompe i gestori a priorità inferiore. -- `before_install`: `{ block: false }` non ha effetto e non annulla un blocco precedente. -- `message_sending`: `{ cancel: true }` è terminale e interrompe i gestori a priorità inferiore. -- `message_sending`: `{ cancel: false }` non ha effetto e non annulla una cancellazione precedente. +- `before_tool_call`: `{ block: true }` è terminale e interrompe gli handler con priorità inferiore. +- `before_tool_call`: `{ block: false }` è un no-op e non annulla un blocco precedente. +- `before_install`: `{ block: true }` è terminale e interrompe gli handler con priorità inferiore. +- `before_install`: `{ block: false }` è un no-op e non annulla un blocco precedente. +- `message_sending`: `{ cancel: true }` è terminale e interrompe gli handler con priorità inferiore. +- `message_sending`: `{ cancel: false }` è un no-op e non annulla una cancellazione precedente. -Vedi [Hook plugin](/it/plugins/architecture#provider-runtime-hooks) per l'API degli hook e i dettagli di registrazione. +Vedi [Plugin hooks](/it/plugins/architecture#provider-runtime-hooks) per l'API degli hook e i dettagli di registrazione. ## Streaming + risposte parziali - I delta dell'assistente vengono trasmessi in streaming da pi-agent-core ed emessi come eventi `assistant`. - Lo streaming a blocchi può emettere risposte parziali su `text_end` o `message_end`. - Lo streaming del ragionamento può essere emesso come stream separato o come risposte a blocchi. -- Vedi [Streaming](/it/concepts/streaming) per il comportamento di suddivisione in chunk e delle risposte a blocchi. +- Vedi [Streaming](/it/concepts/streaming) per il comportamento di chunking e delle risposte a blocchi. ## Esecuzione degli strumenti + strumenti di messaggistica @@ -130,21 +130,20 @@ Vedi [Hook plugin](/it/plugins/architecture#provider-runtime-hooks) per l'API de - I payload finali vengono assemblati da: - testo dell'assistente (e ragionamento facoltativo) - riepiloghi inline degli strumenti (quando verbose + consentito) - - testo di errore dell'assistente quando il modello restituisce un errore + - testo di errore dell'assistente quando il modello genera un errore - Il token silenzioso esatto `NO_REPLY` / `no_reply` viene filtrato dai payload in uscita. - I duplicati degli strumenti di messaggistica vengono rimossi dall'elenco finale dei payload. -- Se non rimangono payload renderizzabili e uno strumento ha restituito un errore, viene emessa - una risposta di fallback per l'errore dello strumento +- Se non rimangono payload renderizzabili e uno strumento ha generato un errore, viene emessa una risposta di fallback per l'errore dello strumento (a meno che uno strumento di messaggistica abbia già inviato una risposta visibile all'utente). -## Compattazione + tentativi +## Compattazione + retry -- La compattazione automatica emette eventi di stream `compaction` e può attivare un nuovo tentativo. -- Al nuovo tentativo, i buffer in memoria e i riepiloghi degli strumenti vengono reimpostati per evitare output duplicati. -- Vedi [Compattazione](/it/concepts/compaction) per la pipeline di compattazione. +- La compattazione automatica emette eventi di stream `compaction` e può attivare un retry. +- Al retry, i buffer in memoria e i riepiloghi degli strumenti vengono reimpostati per evitare output duplicato. +- Vedi [Compaction](/it/concepts/compaction) per la pipeline di compattazione. -## Stream di eventi (attualmente) +## Stream di eventi (oggi) - `lifecycle`: emesso da `subscribeEmbeddedPiSession` (e come fallback da `agentCommand`) - `assistant`: delta in streaming da pi-agent-core @@ -152,26 +151,26 @@ Vedi [Hook plugin](/it/plugins/architecture#provider-runtime-hooks) per l'API de ## Gestione del canale chat -- I delta dell'assistente vengono inseriti in buffer in messaggi chat `delta`. -- Un `final` della chat viene emesso alla **fine/errore del ciclo di vita**. +- I delta dell'assistente vengono bufferizzati in messaggi chat `delta`. +- Un `final` della chat viene emesso su **lifecycle end/error**. ## Timeout -- Valore predefinito di `agent.wait`: 30s (solo l'attesa). Il parametro `timeoutMs` esegue l'override. -- Runtime dell'agente: `agents.defaults.timeoutSeconds` predefinito 172800s (48 ore); applicato nel timer di interruzione di `runEmbeddedPiAgent`. -- Timeout di inattività dell'LLM: `agents.defaults.llm.idleTimeoutSeconds` interrompe una richiesta al modello quando non arrivano chunk di risposta prima della finestra di inattività. Impostalo esplicitamente per modelli locali lenti o provider di ragionamento/chiamata strumenti; impostalo a 0 per disabilitarlo. Se non è impostato, OpenClaw usa `agents.defaults.timeoutSeconds` se configurato, altrimenti 60s. Le esecuzioni attivate da cron senza un timeout esplicito dell'LLM o dell'agente disabilitano il watchdog di inattività e si affidano al timeout esterno del cron. +- Valore predefinito di `agent.wait`: 30s (solo per l'attesa). Il parametro `timeoutMs` lo sovrascrive. +- Runtime dell'agente: valore predefinito `agents.defaults.timeoutSeconds` 172800s (48 ore); applicato nel timer di interruzione di `runEmbeddedPiAgent`. +- Timeout di inattività LLM: `agents.defaults.llm.idleTimeoutSeconds` interrompe una richiesta al modello quando non arrivano chunk di risposta prima della finestra di inattività. Impostalo esplicitamente per modelli locali lenti o provider di ragionamento/chiamata strumenti; impostalo a 0 per disabilitarlo. Se non è impostato, OpenClaw usa `agents.defaults.timeoutSeconds` quando configurato, altrimenti 120s. Le esecuzioni attivate da cron senza timeout LLM o dell'agente esplicito disabilitano il watchdog di inattività e si affidano al timeout esterno del cron. ## Dove le cose possono terminare in anticipo - Timeout dell'agente (interruzione) - AbortSignal (annullamento) -- Disconnessione del gateway o timeout RPC -- Timeout di `agent.wait` (solo attesa, non arresta l'agente) +- Disconnessione del Gateway o timeout RPC +- Timeout di `agent.wait` (solo attesa, non ferma l'agente) ## Correlati -- [Strumenti](/it/tools) — strumenti dell'agente disponibili +- [Tools](/it/tools) — strumenti dell'agente disponibili - [Hooks](/it/automation/hooks) — script guidati da eventi attivati dagli eventi del ciclo di vita dell'agente -- [Compattazione](/it/concepts/compaction) — come vengono riepilogate le conversazioni lunghe -- [Approvazioni Exec](/it/tools/exec-approvals) — controlli di approvazione per i comandi shell +- [Compaction](/it/concepts/compaction) — come vengono riepilogate le conversazioni lunghe +- [Exec Approvals](/it/tools/exec-approvals) — controlli di approvazione per i comandi shell - [Thinking](/it/tools/thinking) — configurazione del livello di thinking/ragionamento diff --git a/docs/it/concepts/memory-search.md b/docs/it/concepts/memory-search.md index 7be61a189..ddc092858 100644 --- a/docs/it/concepts/memory-search.md +++ b/docs/it/concepts/memory-search.md @@ -3,27 +3,27 @@ read_when: - Vuoi capire come funziona `memory_search` - Vuoi scegliere un provider di embedding - Vuoi ottimizzare la qualità della ricerca -summary: Come la ricerca della memoria trova note pertinenti usando embeddings e recupero ibrido -title: Memory Search +summary: Come la ricerca nella memoria trova note pertinenti usando embeddings e recupero ibrido +title: Ricerca nella memoria x-i18n: - generated_at: "2026-04-06T03:06:32Z" + generated_at: "2026-04-10T08:13:31Z" model: gpt-5.4 provider: openai - source_hash: b6541cd702bff41f9a468dad75ea438b70c44db7c65a4b793cbacaf9e583c7e9 + source_hash: ca0237f4f1ee69dcbfb12e6e9527a53e368c0bf9b429e506831d4af2f3a3ac6f source_path: concepts/memory-search.md workflow: 15 --- -# Memory Search +# Ricerca nella memoria -`memory_search` trova note pertinenti nei tuoi file di memoria, anche quando la -formulazione è diversa dal testo originale. Funziona indicizzando la memoria in piccoli -blocchi e cercandoli usando embeddings, parole chiave o entrambi. +`memory_search` trova note pertinenti dai tuoi file di memoria, anche quando la +formulazione è diversa dal testo originale. Funziona indicizzando la memoria in +piccoli blocchi e cercandoli tramite embeddings, parole chiave o entrambi. ## Avvio rapido Se hai configurato una chiave API OpenAI, Gemini, Voyage o Mistral, la ricerca -della memoria funziona automaticamente. Per impostare esplicitamente un provider: +nella memoria funziona automaticamente. Per impostare esplicitamente un provider: ```json5 { @@ -37,8 +37,8 @@ della memoria funziona automaticamente. Per impostare esplicitamente un provider } ``` -Per embedding locali senza chiave API, usa `provider: "local"` (richiede -node-llama-cpp). +Per embeddings locali senza chiave API, usa `provider: "local"` (richiede +`node-llama-cpp`). ## Provider supportati @@ -50,11 +50,11 @@ node-llama-cpp). | Mistral | `mistral` | Sì | Rilevato automaticamente | | Bedrock | `bedrock` | No | Rilevato automaticamente quando la catena di credenziali AWS viene risolta | | Ollama | `ollama` | No | Locale, deve essere impostato esplicitamente | -| Local | `local` | No | Modello GGUF, download di circa 0,6 GB | +| Local | `local` | No | Modello GGUF, download di ~0,6 GB | ## Come funziona la ricerca -OpenClaw esegue in parallelo due percorsi di recupero e ne unisce i risultati: +OpenClaw esegue due percorsi di recupero in parallelo e unisce i risultati: ```mermaid flowchart LR @@ -72,31 +72,33 @@ flowchart LR - **Ricerca per parole chiave BM25** trova corrispondenze esatte (ID, stringhe di errore, chiavi di configurazione). -Se è disponibile un solo percorso (niente embeddings o niente FTS), viene eseguito solo l'altro. +Se è disponibile solo un percorso (nessun embeddings o nessun FTS), l'altro viene eseguito da solo. ## Migliorare la qualità della ricerca -Due funzionalità facoltative aiutano quando hai una cronologia ampia di note: +Due funzionalità opzionali aiutano quando hai una cronologia delle note molto ampia: ### Decadimento temporale -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 il 50% del -suo peso originale. I file sempreverdi 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 il 50% del suo peso originale. I file sempre validi come +`MEMORY.md` non subiscono mai decadimento. -Abilita il decadimento temporale se il tuo agente ha mesi di note giornaliere e informazioni obsolete -continuano a superare nel ranking il contesto recente. +Abilita il decadimento temporale se il tuo agente ha mesi di note quotidiane e +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 -garantisce che i risultati principali coprano argomenti diversi invece di ripetersi. +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. -Abilita MMR se `memory_search` continua a restituire snippet quasi duplicati da -note giornaliere diverse. +Abilita MMR se `memory_search` continua a restituire frammenti quasi duplicati +provenienti da note quotidiane diverse. ### Abilita entrambi @@ -120,15 +122,16 @@ note giornaliere diverse. ## Memoria multimodale -Con Gemini Embedding 2, puoi indicizzare file di immagini e audio insieme al -Markdown. Le query di ricerca restano testuali, ma corrispondono a contenuti visivi e audio. -Per la configurazione, vedi il [Riferimento della configurazione della memoria](/it/reference/memory-config). +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. Vedi il [riferimento della configurazione della memoria](/it/reference/memory-config) per +la configurazione. -## Ricerca nella memoria della sessione +## Ricerca nella memoria di sessione -Puoi facoltativamente indicizzare le trascrizioni delle sessioni in modo che `memory_search` possa recuperare -conversazioni precedenti. Questa funzionalità è opt-in tramite -`memorySearch.experimental.sessionMemory`. Vedi il +Puoi facoltativamente indicizzare le trascrizioni delle sessioni così che +`memory_search` possa richiamare conversazioni precedenti. Questa opzione è +attivabile tramite `memorySearch.experimental.sessionMemory`. Vedi il [riferimento della configurazione](/it/reference/memory-config) per i dettagli. ## Risoluzione dei problemi @@ -142,7 +145,8 @@ conversazioni precedenti. Questa funzionalità è opt-in tramite **Testo CJK non trovato?** Ricostruisci l'indice FTS con `openclaw memory index --force`. -## Ulteriori letture +## Approfondimenti -- [Memory](/it/concepts/memory) -- layout dei file, backend, strumenti +- [Memoria attiva](/it/concepts/active-memory) -- memoria del sub-agente per sessioni di chat interattive +- [Memoria](/it/concepts/memory) -- layout dei file, backend, strumenti - [Riferimento della configurazione della memoria](/it/reference/memory-config) -- tutte le opzioni di configurazione diff --git a/docs/it/concepts/qa-e2e-automation.md b/docs/it/concepts/qa-e2e-automation.md index 4c0bb68c5..d9386091d 100644 --- a/docs/it/concepts/qa-e2e-automation.md +++ b/docs/it/concepts/qa-e2e-automation.md @@ -1,23 +1,24 @@ --- read_when: - - Estensione di qa-lab o qa-channel - - Aggiunta di scenari QA supportati dal repository - - Creazione di un'automazione QA con maggiore realismo attorno alla dashboard Gateway -summary: Struttura dell'automazione QA privata per qa-lab, qa-channel, scenari seed e report di protocollo -title: Automazione QA E2E + - Estendere qa-lab o qa-channel + - Aggiungere scenari QA supportati dal repository + - Creare un'automazione QA con maggiore realismo attorno alla dashboard del Gateway +summary: Struttura dell'automazione QA privata per qa-lab, qa-channel, scenari inizializzati e report di protocollo +title: Automazione QA end-to-end x-i18n: - generated_at: "2026-04-09T01:27:42Z" + generated_at: "2026-04-10T08:13:32Z" model: gpt-5.4 provider: openai - source_hash: c922607d67e0f3a2489ac82bc9f510f7294ced039c1014c15b676d826441d833 + source_hash: 357d6698304ff7a8c4aa8a7be97f684d50f72b524740050aa761ac0ee68266de source_path: concepts/qa-e2e-automation.md workflow: 15 --- -# Automazione QA E2E +# Automazione QA end-to-end -Lo stack QA privato è pensato per testare OpenClaw in un modo più realistico, -simile a un canale, rispetto a quanto possa fare un singolo test unitario. +Lo stack QA privato è pensato per testare OpenClaw in modo più realistico, +con una forma simile a quella di un canale, rispetto a quanto possa fare un +singolo test unitario. Componenti attuali: @@ -25,12 +26,12 @@ Componenti attuali: reazione, modifica ed eliminazione. - `extensions/qa-lab`: interfaccia utente di debug e bus QA per osservare la trascrizione, iniettare messaggi in ingresso ed esportare un report Markdown. -- `qa/`: risorse seed supportate dal repository per l'attività iniziale e gli +- `qa/`: risorse seed supportate dal repository per il task iniziale e gli scenari QA di base. -L'attuale flusso dell'operatore QA è un sito QA a due pannelli: +L'attuale flusso operativo QA è un sito QA a due pannelli: -- Sinistra: dashboard Gateway (Control UI) con l'agente. +- Sinistra: dashboard del Gateway (Control UI) con l'agente. - Destra: QA Lab, che mostra la trascrizione in stile Slack e il piano dello scenario. Eseguilo con: @@ -39,12 +40,12 @@ Eseguilo con: pnpm qa:lab:up ``` -Questo compila il sito QA, avvia la corsia gateway supportata da Docker ed espone la -pagina QA Lab in cui un operatore o un ciclo di automazione può assegnare all'agente una -missione QA, osservare il comportamento reale del canale e registrare ciò che ha -funzionato, ciò che non ha funzionato o ciò che è rimasto bloccato. +Questo compila il sito QA, avvia la lane del gateway supportata da Docker ed espone la +pagina QA Lab dove un operatore o un loop di automazione può assegnare all'agente una +missione QA, osservare il comportamento reale del canale e registrare cosa ha funzionato, +cosa è fallito o cosa è rimasto bloccato. -Per un'iterazione più rapida dell'interfaccia utente di QA Lab senza ricompilare ogni volta l'immagine Docker, +Per iterare più velocemente sull'interfaccia utente di QA Lab senza ricompilare ogni volta l'immagine Docker, avvia lo stack con un bundle QA Lab montato tramite bind: ```bash @@ -56,9 +57,24 @@ pnpm qa:lab:watch `qa:lab:up:fast` mantiene i servizi Docker su un'immagine precompilata e monta tramite bind `extensions/qa-lab/web/dist` nel container `qa-lab`. `qa:lab:watch` -ricompila quel bundle a ogni modifica e il browser si ricarica automaticamente quando cambia l'hash +ricompila quel bundle a ogni modifica, e il browser si ricarica automaticamente quando cambia l'hash delle risorse di QA Lab. +Per una lane VM Linux usa e getta senza introdurre Docker nel percorso QA, esegui: + +```bash +pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline +``` + +Questo avvia una nuova guest Multipass, installa le dipendenze, compila OpenClaw all'interno della guest, +esegue `qa suite`, quindi copia il normale report QA e il riepilogo in `.artifacts/qa-e2e/...` +sull'host. +Riutilizza lo stesso comportamento di selezione dello scenario di `qa suite` sull'host. +Le esecuzioni live inoltrano gli input di autenticazione QA supportati e pratici per la +guest: chiavi provider basate su env, il percorso della configurazione del provider live QA e +`CODEX_HOME` quando presente. Mantieni `--output-dir` sotto la root del repository in modo che la guest +possa scrivere di nuovo attraverso il workspace montato. + ## Seed supportati dal repository Le risorse seed si trovano in `qa/`: @@ -66,30 +82,30 @@ Le risorse seed si trovano in `qa/`: - `qa/scenarios/index.md` - `qa/scenarios/*.md` -Sono intenzionalmente in git in modo che il piano QA sia visibile sia agli esseri umani sia +Questi file sono intenzionalmente presenti in git in modo che il piano QA sia visibile sia agli esseri umani sia all'agente. L'elenco di base dovrebbe rimanere abbastanza ampio da coprire: -- chat DM e di canale +- chat in DM e nei canali - comportamento dei thread - ciclo di vita delle azioni sui messaggi - callback cron - richiamo della memoria - cambio modello -- passaggio a sottoagente +- handoff a subagente - lettura del repository e della documentazione -- una piccola attività di build come Lobster Invaders +- un piccolo task di build come Lobster Invaders ## Reportistica -`qa-lab` esporta un report di protocollo Markdown dalla timeline osservata del bus. -Il report dovrebbe rispondere a queste domande: +`qa-lab` esporta un report di protocollo Markdown dalla timeline del bus osservato. +Il report dovrebbe rispondere a: -- Che cosa ha funzionato -- Che cosa non ha funzionato -- Che cosa è rimasto bloccato +- Cosa ha funzionato +- Cosa è fallito +- Cosa è rimasto bloccato - Quali scenari di follow-up vale la pena aggiungere -Per verifiche di carattere e stile, esegui lo stesso scenario su più riferimenti di modelli live +Per i controlli di carattere e stile, esegui lo stesso scenario su più riferimenti di modelli live e scrivi un report Markdown valutato: ```bash @@ -109,31 +125,31 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -Il comando esegue processi figli del gateway QA locale, non Docker. Gli scenari di character eval +Il comando esegue processi figli locali del gateway QA, non Docker. Gli scenari di valutazione del carattere dovrebbero impostare la persona tramite `SOUL.md`, quindi eseguire normali turni utente -come chat, aiuto per il workspace e piccole attività sui file. Al modello candidato -non dovrebbe essere detto che è in fase di valutazione. Il comando conserva ogni -trascrizione completa, registra statistiche di esecuzione di base, quindi chiede ai modelli giudice in modalità fast con -ragionamento `xhigh` di classificare le esecuzioni in base a naturalezza, vibe e umorismo. +come chat, assistenza sul workspace e piccoli task sui file. Al modello candidato non +dovrebbe essere detto che è in fase di valutazione. Il comando preserva ogni trascrizione completa, +registra statistiche di base sull'esecuzione, quindi chiede ai modelli giudice in modalità fast con +ragionamento `xhigh` di classificare le esecuzioni per naturalezza, vibe e umorismo. Usa `--blind-judge-models` quando confronti provider: il prompt del giudice riceve comunque -ogni trascrizione e stato di esecuzione, ma i riferimenti dei candidati vengono sostituiti con -etichette neutrali come `candidate-01`; il report riconduce le classifiche ai riferimenti reali dopo +ogni trascrizione e stato di esecuzione, ma i riferimenti dei candidati vengono sostituiti con etichette +neutrali come `candidate-01`; il report riconduce le classifiche ai riferimenti reali dopo il parsing. -Le esecuzioni candidate usano per impostazione predefinita `high` thinking, con `xhigh` per i modelli OpenAI che +Le esecuzioni dei candidati usano per impostazione predefinita il livello di ragionamento `high`, con `xhigh` per i modelli OpenAI che lo supportano. Sostituisci un candidato specifico inline con -`--model provider/model,thinking=`. `--thinking ` imposta comunque un -fallback globale, e la forma precedente `--model-thinking ` viene -mantenuta per compatibilità. -I riferimenti candidati OpenAI usano per impostazione predefinita la modalità fast in modo che venga utilizzata l'elaborazione prioritaria dove +`--model provider/model,thinking=`. `--thinking ` continua a impostare un +fallback globale, e la forma meno recente `--model-thinking ` viene mantenuta +per compatibilità. +I riferimenti candidati OpenAI usano per impostazione predefinita la modalità fast in modo che venga usata l'elaborazione prioritaria dove il provider la supporta. Aggiungi `,fast`, `,no-fast` o `,fast=false` inline quando un -singolo candidato o giudice necessita di una sostituzione. Passa `--fast` solo quando vuoi -forzare la modalità fast per ogni modello candidato. Le durate di candidati e giudici vengono -registrate nel report per l'analisi comparativa, ma i prompt dei giudici indicano esplicitamente +singolo candidato o giudice richiede una sostituzione. Passa `--fast` solo quando vuoi +forzare la modalità fast per ogni modello candidato. Le durate dei candidati e dei giudici vengono +registrate nel report per l'analisi comparativa, ma i prompt dei giudici dicono esplicitamente di non classificare in base alla velocità. -Sia le esecuzioni dei modelli candidati sia quelle dei modelli giudice usano per impostazione predefinita una concorrenza pari a 16. Riduci -`--concurrency` o `--judge-concurrency` quando i limiti del provider o il carico del gateway locale +Le esecuzioni dei modelli candidati e giudici usano entrambe per impostazione predefinita una concorrenza di 16. +Riduci `--concurrency` o `--judge-concurrency` quando i limiti del provider o la pressione sul gateway locale rendono un'esecuzione troppo rumorosa. -Quando non viene passato alcun candidato `--model`, il character eval usa per impostazione predefinita +Quando non viene passato alcun `--model` candidato, la valutazione del carattere usa per impostazione predefinita `openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, `moonshot/kimi-k2.5` e @@ -145,5 +161,5 @@ Quando non viene passato alcun `--judge-model`, i giudici usano per impostazione ## Documentazione correlata - [Testing](/it/help/testing) -- [QA Channel](/it/channels/qa-channel) +- [Canale QA](/it/channels/qa-channel) - [Dashboard](/web/dashboard) diff --git a/docs/it/gateway/configuration-reference.md b/docs/it/gateway/configuration-reference.md index 34e9b7dea..c1a780d7d 100644 --- a/docs/it/gateway/configuration-reference.md +++ b/docs/it/gateway/configuration-reference.md @@ -1,37 +1,37 @@ --- read_when: - - Ti servono semantiche o valori predefiniti esatti a livello di singolo campo di configurazione - - Stai convalidando blocchi di configurazione di canali, modelli, gateway o strumenti -summary: Riferimento della configurazione del Gateway per chiavi, valori predefiniti e link ai riferimenti dedicati dei sottosistemi principali di OpenClaw + - Hai bisogno della semantica esatta della configurazione a livello di campo 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 link ai riferimenti dedicati dei sottosistemi title: Riferimento della configurazione x-i18n: - generated_at: "2026-04-09T01:33:04Z" + generated_at: "2026-04-10T08:13:31Z" model: gpt-5.4 provider: openai - source_hash: a9d6d0c542b9874809491978fdcf8e1a7bb35a4873db56aa797963d03af4453c + source_hash: c6aa34e3a9096c4dabef26b9cdfda4bd7693e16da43a88c1641cfad8ba1ec237 source_path: gateway/configuration-reference.md workflow: 15 --- # Riferimento della configurazione -Riferimento della configurazione principale per `~/.openclaw/openclaw.json`. Per una panoramica orientata alle attività, vedi [Configuration](/it/gateway/configuration). +Riferimento della configurazione principale per `~/.openclaw/openclaw.json`. Per una panoramica orientata alle attività, vedi [Configurazione](/it/gateway/configuration). -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 o ogni parametro avanzato di memoria/QMD in un'unica pagina. +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** tenta di incorporare in linea in un'unica pagina ogni catalogo di comandi posseduto da canali/plugin o ogni impostazione approfondita di memoria/QMD. -Fonte di verità nel codice: +Fonte del codice: -- `openclaw config schema` stampa lo Schema JSON attivo usato per la convalida e il Control UI, con i metadati di bundled/plugin/channel uniti quando disponibili -- `config.schema.lookup` restituisce un nodo di schema circoscritto a un percorso per strumenti di approfondimento -- `pnpm config:docs:check` / `pnpm config:docs:gen` convalidano l'hash di baseline dei documenti di configurazione rispetto alla superficie di 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 singolo nodo dello schema con ambito di percorso per gli strumenti di approfondimento +- `pnpm config:docs:check` / `pnpm config:docs:gen` convalidano l'hash di baseline dei documenti di configurazione rispetto alla superficie attuale dello schema Riferimenti approfonditi dedicati: -- [Memory configuration reference](/it/reference/memory-config) per `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` e la configurazione dreaming sotto `plugins.entries.memory-core.config.dreaming` -- [Slash Commands](/it/tools/slash-commands) per il catalogo di comandi integrato + bundled attuale -- pagine del canale/plugin proprietario per le superfici di comando specifiche del canale +- [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` +- [Comandi Slash](/it/tools/slash-commands) per il catalogo attuale dei comandi built-in + bundled +- pagine del canale/plugin proprietario per le superfici di comandi specifiche del canale -Il formato di configurazione è **JSON5** (commenti + virgole finali consentiti). Tutti i campi sono facoltativi — OpenClaw usa valori predefiniti sicuri quando omessi. +Il formato della configurazione è **JSON5** (commenti + virgole finali consentiti). Tutti i campi sono facoltativi: OpenClaw usa valori predefiniti sicuri quando vengono omessi. --- @@ -39,32 +39,32 @@ Il formato di configurazione è **JSON5** (commenti + virgole finali consentiti) Ogni canale si avvia automaticamente quando la sua sezione di configurazione esiste (a meno che `enabled: false`). -### Accesso a DM e gruppi +### Accesso DM e 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 abbinamento monouso; il proprietario deve approvare | -| `allowlist` | Solo i mittenti in `allowFrom` (o archivio allow di pairing) | -| `open` | Consenti tutti i DM in ingresso (richiede `allowFrom: ["*"]`) | -| `disabled` | Ignora tutti i DM in ingresso | +| Criterio DM | Comportamento | +| ------------------- | -------------------------------------------------------------- | +| `pairing` (default) | I mittenti sconosciuti ricevono un codice di pairing monouso; il proprietario deve approvare | +| `allowlist` | Solo i mittenti in `allowFrom` (o nello store paired allow) | +| `open` | Consenti tutti i DM in ingresso (richiede `allowFrom: ["*"]`) | +| `disabled` | Ignora tutti i DM in ingresso | | Criterio gruppo | Comportamento | | --------------------- | ----------------------------------------------------- | | `allowlist` (default) | Solo i gruppi che corrispondono alla allowlist configurata | -| `open` | Aggira le allowlist dei gruppi (il gating per menzione si applica comunque) | -| `disabled` | Blocca tutti i messaggi di gruppo/stanza | +| `open` | Bypassa le allowlist dei gruppi (il mention-gating 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 pairing scadono dopo 1 ora. Le richieste di pairing DM in sospeso sono limitate a **3 per canale**. -Se un blocco provider manca del tutto (`channels.` assente), il criterio di gruppo a runtime torna a `allowlist` (fail-closed) con un avviso all'avvio. +Se un blocco provider manca completamente (`channels.` assente), il criterio di gruppo a runtime ricade su `allowlist` (fail-closed) con un avviso all'avvio. ### Override del modello per canale -Usa `channels.modelByChannel` per fissare ID 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 (per esempio impostato tramite `/model`). +Usa `channels.modelByChannel` per fissare specifici ID di canale 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 { @@ -87,7 +87,7 @@ Usa `channels.modelByChannel` per fissare ID canale specifici a un modello. I va ### Valori predefiniti dei canali e heartbeat -Usa `channels.defaults` per il comportamento condiviso di criterio dei gruppi e heartbeat tra i provider: +Usa `channels.defaults` per il comportamento condiviso di group-policy e heartbeat tra i provider: ```json5 { @@ -105,15 +105,15 @@ Usa `channels.defaults` per il comportamento condiviso di criterio dei gruppi e } ``` -- `channels.defaults.groupPolicy`: criterio di 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` (default, include tutto il contesto citato/thread/storico), `allowlist` (include solo il contesto da mittenti 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 sani nell'output heartbeat. -- `channels.defaults.heartbeat.showAlerts`: include gli stati degradati/in errore nell'output heartbeat. -- `channels.defaults.heartbeat.useIndicator`: renderizza un output heartbeat compatto in stile indicatore. +- `channels.defaults.groupPolicy`: criterio di gruppo di fallback quando un `groupPolicy` a livello di provider non è impostato. +- `channels.defaults.contextVisibility`: modalità predefinita di visibilità del contesto supplementare per tutti i canali. Valori: `all` (default, include tutto il contesto di citazioni/thread/cronologia), `allowlist` (include solo il contesto dai mittenti 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. ### 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 { @@ -164,9 +164,9 @@ WhatsApp viene eseguito tramite il canale web del gateway (Baileys Web). Si avvi } ``` -- I comandi in uscita usano come default l'account `default` se presente; altrimenti il primo ID account configurato (ordinato). -- `channels.whatsapp.defaultAccount` facoltativo sostituisce quella selezione dell'account predefinito quando corrisponde a un ID account configurato. -- La directory auth Baileys legacy single-account viene migrata da `openclaw doctor` in `whatsapp/default`. +- I comandi in uscita usano per default l'account `default` se presente; altrimenti il primo ID account configurato (ordinato). +- `channels.whatsapp.defaultAccount` facoltativo override quel fallback per la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- La directory di autenticazione legacy single-account di Baileys viene migrata da `openclaw doctor` in `whatsapp/default`. - Override per account: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -190,7 +190,7 @@ WhatsApp viene eseguito tramite il canale web del gateway (Baileys Web). Si avvi "99": { requireMention: false, skills: ["search"], - systemPrompt: "Resta in tema.", + systemPrompt: "Rimani in tema.", }, }, }, @@ -202,7 +202,7 @@ WhatsApp viene eseguito tramite il canale web del gateway (Baileys Web). Si avvi historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress (default: off; attivalo esplicitamente per evitare limiti di frequenza anteprima-modifica) + streaming: "partial", // off | partial | block | progress (predefinito: off; abilita esplicitamente per evitare i limiti di frequenza delle modifiche alle anteprime) actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -225,13 +225,13 @@ WhatsApp viene eseguito tramite il canale web del gateway (Baileys Web). Si avvi } ``` -- Token bot: `channels.telegram.botToken` o `channels.telegram.tokenFile` (solo file regolare; symlink rifiutati), con `TELEGRAM_BOT_TOKEN` come fallback per l'account predefinito. -- `channels.telegram.defaultAccount` facoltativo sostituisce la selezione dell'account predefinito quando corrisponde a un ID account configurato. -- Nelle configurazioni multi-account (2+ ID account), imposta un default esplicito (`channels.telegram.defaultAccount` o `channels.telegram.accounts.default`) per evitare routing di fallback; `openclaw doctor` avvisa quando manca o non è valido. -- `configWrites: false` blocca le scritture di configurazione avviate da Telegram (migrazioni ID supergruppo, `/config set|unset`). -- Le voci `bindings[]` di livello superiore con `type: "acp"` configurano binding ACP persistenti per i topic 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 streaming di Telegram usano `sendMessage` + `editMessageText` (funziona in chat dirette e di gruppo). -- Criterio di retry: vedi [Retry policy](/it/concepts/retry). +- 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. +- `channels.telegram.defaultAccount` facoltativo override la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- Nelle configurazioni multi-account (2+ ID account), imposta un default esplicito (`channels.telegram.defaultAccount` o `channels.telegram.accounts.default`) per evitare il routing di fallback; `openclaw doctor` avvisa quando manca o non è valido. +- `configWrites: false` blocca le scritture di configurazione avviate da Telegram (migrazioni degli ID dei supergroup, `/config set|unset`). +- Le voci `bindings[]` di livello superiore con `type: "acp"` configurano binding ACP persistenti per i topic del forum (usa il formato canonico `chatId:topic:topicId` in `match.peer.id`). La semantica dei campi è condivisa in [Agenti ACP](/it/tools/acp-agents#channel-specific-settings). +- Le anteprime stream di Telegram usano `sendMessage` + `editMessageText` (funziona in chat dirette e di gruppo). +- Criterio di retry: vedi [Criterio di retry](/it/concepts/retry). ### Discord @@ -286,7 +286,7 @@ WhatsApp viene eseguito tramite il canale web del gateway (Baileys Web). Si avvi historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress (progress viene mappato a partial su Discord) + streaming: "off", // off | partial | block | progress (progress corrisponde a partial su Discord) maxLinesPerMessage: 17, ui: { components: { @@ -334,35 +334,35 @@ 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 account continuano a provenire dall'account selezionato nello snapshot runtime attivo. -- `channels.discord.defaultAccount` facoltativo sostituisce la selezione dell'account predefinito quando corrisponde a un ID account configurato. -- Usa `user:` (DM) o `channel:` (canale guild) per i target di consegna; gli ID numerici nudi vengono rifiutati. -- Gli slug delle guild sono minuscoli con gli spazi sostituiti da `-`; le chiavi canale usano il nome trasformato in slug (senza `#`). Preferisci gli ID guild. -- I messaggi scritti dal bot vengono ignorati per impostazione predefinita. `allowBots: true` li abilita; usa `allowBots: "mentions"` per accettare solo messaggi bot che menzionano il bot (i propri messaggi restano comunque filtrati). -- `channels.discord.guilds..ignoreOtherMentions` (e override di canale) elimina i messaggi che menzionano un altro utente o ruolo ma non il bot (esclusi @everyone/@here). -- `maxLinesPerMessage` (default 17) suddivide i messaggi alti anche quando sono sotto i 2000 caratteri. -- `channels.discord.threadBindings` controlla il routing legato ai thread Discord: - - `enabled`: override Discord per le funzionalità di sessione legata al thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` e consegna/routing vincolati) - - `idleHours`: override Discord per l'auto-unfocus dopo inattività in ore (`0` disabilita) - - `maxAgeHours`: override Discord per età massima rigida in ore (`0` disabilita) - - `spawnSubagentSessions`: interruttore opt-in per la creazione/binding automatici del thread da `sessions_spawn({ thread: true })` -- Le voci `bindings[]` di livello superiore con `type: "acp"` configurano binding ACP persistenti per canali e thread (usa l'ID 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 conversazioni nei canali vocali Discord e override facoltativi auto-join + TTS. -- `channels.discord.voice.daveEncryption` e `channels.discord.voice.decryptionFailureTolerance` vengono passati a `@discordjs/voice` come opzioni DAVE (`true` e `24` per default). -- OpenClaw inoltre tenta il recupero della ricezione vocale uscendo/rientrando in una sessione vocale dopo ripetuti errori di decrittazione. -- `channels.discord.streaming` è la chiave canonica della modalità stream. I valori legacy `streamMode` e booleani `streaming` vengono auto-migrati. +- 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. +- `channels.discord.defaultAccount` facoltativo override la selezione dell'account predefinito 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 default. `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 del canale) scarta 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 restano sotto i 2000 caratteri. +- `channels.discord.threadBindings` controlla il routing associato ai thread 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 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 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 [Agenti ACP](/it/tools/acp-agents#channel-specific-settings). +- `channels.discord.ui.components.accentColor` imposta il colore d'accento per i container 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 (predefiniti `true` e `24`). +- Inoltre, OpenClaw tenta il recupero della ricezione vocale uscendo e rientrando in una sessione vocale dopo ripetuti errori di decrittazione. +- `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 facoltativi del testo di stato. -- `channels.discord.dangerouslyAllowNameMatching` riabilita il matching per 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"` (default). 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 richieste exec. Se omesso, usa come fallback `commands.ownerAllowFrom`. - - `agentFilter`: allowlist facoltativa di ID agente. Ometti per inoltrare approvazioni per tutti gli agenti. - - `sessionFilter`: pattern facoltativi di chiave sessione (sottostringa o regex). - - `target`: dove inviare le richieste di approvazione. `"dm"` (default) invia ai DM degli approvatori, `"channel"` invia al canale di origine, `"both"` invia a entrambi. Quando il target include `"channel"`, i pulsanti sono utilizzabili solo dagli approvatori risolti. +- `channels.discord.dangerouslyAllowNameMatching` riabilita la corrispondenza per nome/tag mutabili (modalità di compatibilità break-glass). +- `channels.discord.execApprovals`: consegna delle approvazioni exec nativa di Discord 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 degli ID agente. Omettila per inoltrare le approvazioni per tutti gli agenti. + - `sessionFilter`: pattern facoltativi della chiave di sessione (sottostringa o regex). + - `target`: dove inviare i prompt di approvazione. `"dm"` (predefinito) invia ai DM degli approvatori, `"channel"` invia al canale di origine, `"both"` invia a entrambi. Quando il target include `"channel"`, i pulsanti sono utilizzabili 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, default), `all` (tutti i messaggi), `allowlist` (da `guilds..users` su tutti i messaggi). +**Modalità di notifica delle reazioni:** `off` (nessuna), `own` (messaggi del bot, predefinito), `all` (tutti i messaggi), `allowlist` (da `guilds..users` su tutti i messaggi). ### Google Chat @@ -393,11 +393,11 @@ WhatsApp viene eseguito tramite il canale web del gateway (Baileys Web). Si avvi } ``` -- JSON account di servizio: inline (`serviceAccount`) o basato su file (`serviceAccountFile`). -- È supportato anche SecretRef per account di servizio (`serviceAccountRef`). +- JSON dell'account di servizio: inline (`serviceAccount`) o basato su file (`serviceAccountFile`). +- È supportato anche SecretRef per l'account di servizio (`serviceAccountRef`). - Fallback env: `GOOGLE_CHAT_SERVICE_ACCOUNT` o `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. - Usa `spaces/` o `users/` per i target di consegna. -- `channels.googlechat.dangerouslyAllowNameMatching` riabilita il matching per principal email mutabili (modalità di compatibilità break-glass). +- `channels.googlechat.dangerouslyAllowNameMatching` riabilita la corrispondenza con il principal email mutabile (modalità di compatibilità break-glass). ### Slack @@ -464,35 +464,30 @@ 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` per il fallback env dell'account predefinito). -- **HTTP mode** 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 per credenziale come - `botTokenSource`, `botTokenStatus`, `appTokenStatus` e, in modalità HTTP, - `signingSecretStatus`. `configured_unavailable` significa che l'account è - configurato tramite SecretRef ma il percorso comando/runtime corrente non ha potuto - risolvere il valore del segreto. +- La **modalità Socket** richiede sia `botToken` sia `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` per il 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/per-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. - `configWrites: false` blocca le scritture di configurazione avviate da Slack. -- `channels.slack.defaultAccount` facoltativo sostituisce la selezione dell'account predefinito quando corrisponde a un ID account configurato. -- `channels.slack.streaming.mode` è la chiave canonica della modalità stream Slack. `channels.slack.streaming.nativeTransport` controlla il trasporto streaming nativo di Slack. I valori legacy `streamMode`, booleani `streaming` e `nativeStreaming` vengono auto-migrati. +- `channels.slack.defaultAccount` facoltativo override la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- `channels.slack.streaming.mode` è la chiave canonica per la modalità di streaming 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` (default), `all`, `allowlist` (da `reactionAllowlist`). +**Modalità di notifica delle reazioni:** `off`, `own` (predefinito), `all`, `allowlist` (da `reactionAllowlist`). -**Isolamento sessione thread:** `thread.historyScope` è per-thread (default) o condiviso a livello di canale. `thread.inheritParent` copia la trascrizione del canale padre nei nuovi thread. +**Isolamento della sessione thread:** `thread.historyScope` è per thread (predefinito) o condiviso nel canale. `thread.inheritParent` copia la trascrizione del canale padre nei nuovi thread. -- Lo streaming nativo Slack più lo stato thread stile assistente Slack "sta scrivendo..." richiedono un target di risposta nel thread. I DM di primo livello restano fuori thread per default, quindi usano `typingReaction` o 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"`. -- `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"`). +- Lo streaming nativo di Slack più lo stato thread in stile assistente Slack "is typing..." richiedono un target di risposta thread. I DM di livello superiore restano fuori thread per default, quindi usano `typingReaction` o la consegna normale invece dell'anteprima in stile thread. +- `typingReaction` aggiunge una reazione temporanea al messaggio Slack in ingresso mentre è in esecuzione una risposta, poi la rimuove al completamento. Usa uno shortcode emoji Slack come `"hourglass_flowing_sand"`. +- `channels.slack.execApprovals`: consegna delle approvazioni exec nativa di Slack 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 | Default | Note | -| ---------------- | ------- | ---------------------- | -| reactions | abilitato | Reagisci + elenca reazioni | -| messages | abilitato | Leggi/invia/modifica/elimina | -| pins | abilitato | Fissa/rimuovi/elenca | -| memberInfo | abilitato | Informazioni membro | -| emojiList | abilitato | Elenco emoji personalizzate | +| Gruppo di azioni | Predefinito | Note | +| ---------------- | ----------- | ----------------------- | +| reactions | abilitato | Reagire + elencare reazioni | +| messages | abilitato | Leggere/inviare/modificare/eliminare | +| pins | abilitato | Fissare/rimuovere/elencare | +| memberInfo | abilitato | Informazioni sui membri | +| emojiList | abilitato | Elenco emoji personalizzate | ### Mattermost @@ -526,23 +521,18 @@ Mattermost viene distribuito come plugin: `openclaw plugins install @openclaw/ma } ``` -Modalità chat: `oncall` (risponde su @-mention, default), `onmessage` (ogni messaggio), `onchar` (messaggi che iniziano con prefisso trigger). +Modalità chat: `oncall` (risponde a @-mention, predefinito), `onmessage` (ogni messaggio), `onchar` (messaggi che iniziano con il prefisso trigger). Quando i comandi nativi Mattermost sono abilitati: -- `commands.callbackPath` deve essere un percorso (per 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 - vengono attivati comandi, OpenClaw rifiuta i callback con - `Unauthorized: invalid command token.` -- Per host di callback privati/tailnet/interni, Mattermost può richiedere - che `ServiceSettings.AllowedUntrustedInternalConnections` includa l'host/dominio del callback. - Usa valori host/dominio, non URL completi. +- `commands.callbackPath` deve essere un percorso (ad esempio `/api/channels/mattermost/command`), non un URL completo. +- `commands.callbackUrl` deve risolvere verso l'endpoint del 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 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`: consenti o nega le scritture di configurazione avviate da Mattermost. - `channels.mattermost.requireMention`: richiedi `@mention` prima di rispondere nei canali. -- `channels.mattermost.groups..requireMention`: override per canale del gating per menzione (`"*"` per il default). -- `channels.mattermost.defaultAccount` facoltativo sostituisce la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- `channels.mattermost.groups..requireMention`: override per-canale del mention-gating (`"*"` per il default). +- `channels.mattermost.defaultAccount` facoltativo override la selezione dell'account predefinito quando corrisponde a un ID account configurato. ### Signal @@ -563,15 +553,15 @@ Quando i comandi nativi Mattermost sono abilitati: } ``` -**Modalità di notifica delle reazioni:** `off`, `own` (default), `all`, `allowlist` (da `reactionAllowlist`). +**Modalità di notifica delle reazioni:** `off`, `own` (predefinito), `all`, `allowlist` (da `reactionAllowlist`). - `channels.signal.account`: fissa l'avvio del canale a una specifica identità account Signal. -- `channels.signal.configWrites`: consenti o nega le scritture di configurazione avviate da Signal. -- `channels.signal.defaultAccount` facoltativo sostituisce 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. +- `channels.signal.defaultAccount` facoltativo override la selezione dell'account predefinito quando corrisponde a un ID account configurato. ### BlueBubbles -BlueBubbles è il percorso consigliato per iMessage (supportato da plugin, configurato in `channels.bluebubbles`). +BlueBubbles è il percorso iMessage consigliato (basato su plugin, configurato sotto `channels.bluebubbles`). ```json5 { @@ -579,21 +569,21 @@ BlueBubbles è il percorso consigliato per iMessage (supportato da plugin, confi bluebubbles: { enabled: true, dmPolicy: "pairing", - // serverUrl, password, webhookPath, controlli gruppo e azioni avanzate: + // serverUrl, password, webhookPath, controlli di gruppo e azioni avanzate: // vedi /channels/bluebubbles }, }, } ``` -- Percorsi chiave core trattati qui: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- `channels.bluebubbles.defaultAccount` facoltativo sostituisce la selezione dell'account predefinito quando corrisponde a un ID account configurato. -- Le voci `bindings[]` di livello superiore 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 di chiavi core coperti qui: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. +- `channels.bluebubbles.defaultAccount` facoltativo override la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- Le voci `bindings[]` di livello superiore 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: [Agenti ACP](/it/tools/acp-agents#channel-specific-settings). - La configurazione completa del canale BlueBubbles è documentata in [BlueBubbles](/it/channels/bluebubbles). ### iMessage -OpenClaw avvia `imsg rpc` (JSON-RPC su stdio). Non è richiesto alcun daemon o porta. +OpenClaw avvia `imsg rpc` (JSON-RPC su stdio). Non è richiesto alcun demone o porta. ```json5 { @@ -617,15 +607,15 @@ OpenClaw avvia `imsg rpc` (JSON-RPC su stdio). Non è richiesto alcun daemon o p } ``` -- `channels.imessage.defaultAccount` facoltativo sostituisce la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- `channels.imessage.defaultAccount` facoltativo override la selezione dell'account predefinito quando corrisponde a un ID account configurato. -- Richiede Full Disk Access al DB dei Messaggi. +- Richiede l'accesso completo al disco per il DB di Messages. - 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 allegati SCP. -- `attachmentRoots` e `remoteAttachmentRoots` limitano i percorsi degli allegati in ingresso (default: `/Users/*/Library/Messages/Attachments`). -- SCP usa 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 livello superiore 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). +- `cliPath` può puntare a un wrapper SSH; imposta `remoteHost` (`host` o `user@host`) per il recupero degli allegati tramite 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`: consente o nega le scritture di configurazione avviate da iMessage. +- Le voci `bindings[]` di livello superiore 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: [Agenti ACP](/it/tools/acp-agents#channel-specific-settings). @@ -638,7 +628,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix è supportato da estensione e configurato in `channels.matrix`. +Matrix è supportato da un'estensione ed è configurato sotto `channels.matrix`. ```json5 { @@ -668,25 +658,25 @@ Matrix è supportato da estensione e configurato in `channels.matrix`. } ``` -- L'autenticazione token usa `accessToken`; l'autenticazione password usa `userId` + `password`. -- `channels.matrix.proxy` instrada il traffico HTTP Matrix tramite un proxy HTTP(S) esplicito. Gli account con nome possono fare override con `channels.matrix.accounts..proxy`. +- 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 con nome possono overridearlo 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 come default `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.execApprovals`: consegna nativa Matrix delle approvazioni exec e autorizzazione degli approvatori. - - `enabled`: `true`, `false` o `"auto"` (default). In modalità auto, le approvazioni exec si attivano quando gli approvatori possono essere risolti da `approvers` o `commands.ownerAllowFrom`. - - `approvers`: ID utente Matrix (es. `@owner:example.org`) autorizzati ad approvare richieste exec. - - `agentFilter`: allowlist facoltativa di ID agente. Ometti per inoltrare approvazioni per tutti gli agenti. - - `sessionFilter`: pattern facoltativi di chiave sessione (sottostringa o regex). - - `target`: dove inviare le richieste di approvazione. `"dm"` (default), `"channel"` (stanza di origine) o `"both"`. +- `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 delle approvazioni exec nativa di Matrix 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 esempio `@owner:example.org`) autorizzati ad approvare le richieste exec. + - `agentFilter`: allowlist facoltativa degli ID agente. Omettila per inoltrare le approvazioni per tutti gli agenti. + - `sessionFilter`: pattern facoltativi della chiave di sessione (sottostringa o regex). + - `target`: dove inviare i prompt 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` (default) 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. -- La configurazione completa di Matrix, le regole di targeting e gli esempi di setup sono documentati in [Matrix](/it/channels/matrix). +- `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 lookup live della 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 -Microsoft Teams è supportato da estensione e configurato in `channels.msteams`. +Microsoft Teams è supportato da un'estensione ed è configurato sotto `channels.msteams`. ```json5 { @@ -701,12 +691,12 @@ Microsoft Teams è supportato da estensione e configurato in `channels.msteams`. } ``` -- Percorsi chiave core trattati 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). +- Percorsi di chiavi core coperti qui: `channels.msteams`, `channels.msteams.configWrites`. +- La configurazione completa di Teams (credenziali, webhook, criterio DM/gruppo, override per team/per canale) è documentata in [Microsoft Teams](/it/channels/msteams). ### IRC -IRC è supportato da estensione e configurato in `channels.irc`. +IRC è supportato da un'estensione ed è configurato sotto `channels.irc`. ```json5 { @@ -727,13 +717,13 @@ IRC è supportato da estensione e configurato in `channels.irc`. } ``` -- Percorsi chiave core trattati qui: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- `channels.irc.defaultAccount` facoltativo sostituisce la selezione dell'account predefinito 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). +- Percorsi di chiavi core coperti qui: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. +- `channels.irc.defaultAccount` facoltativo override la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- La configurazione completa del canale IRC (host/porta/TLS/canali/allowlist/mention gating) è documentata in [IRC](/it/channels/irc). ### Multi-account (tutti i canali) -Esegui più account per canale (ognuno con il proprio `accountId`): +Esegui più account per canale (ciascuno con il proprio `accountId`): ```json5 { @@ -756,26 +746,26 @@ Esegui più account per canale (ognuno con il proprio `accountId`): - `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 del canale base si applicano a tutti gli account a meno che non vengano overrideate 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 canale) mentre sei ancora in una configurazione canale top-level single-account, OpenClaw promuove prima i valori top-level single-account circoscritti all'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 named/default esistente corrispondente. -- I binding esistenti solo-canale (senza `accountId`) continuano a corrispondere all'account predefinito; i binding scoped per account restano facoltativi. -- `openclaw doctor --fix` ripara anche forme miste spostando i valori top-level single-account scoped all'account nell'account promosso scelto per quel canale. La maggior parte dei canali usa `accounts.default`; Matrix può preservare un target named/default esistente corrispondente. +- Se aggiungi un account non predefinito tramite `openclaw channels add` (o onboarding del canale) mentre sei ancora in una configurazione di canale top-level single-account, OpenClaw promuove prima i valori top-level single-account 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 con nome/default esistente corrispondente. +- I binding esistenti solo di 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 single-account con ambito account nell'account promosso scelto per quel canale. La maggior parte dei canali usa `accounts.default`; Matrix può invece preservare un target con nome/default esistente corrispondente. ### Altri canali di estensione -Molti canali di estensione sono configurati come `channels.` e documentati nelle relative pagine dedicate al canale (per esempio Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat e Twitch). -Vedi l'indice completo dei canali: [Channels](/it/channels). +Molti canali di estensione sono configurati come `channels.` e documentati nelle rispettive pagine di canale dedicate (ad esempio Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat e Twitch). +Vedi l'indice completo dei canali: [Canali](/it/channels). -### Gating per menzione nelle chat di gruppo +### Mention gating nelle chat di gruppo -I messaggi di gruppo richiedono per default una **menzione obbligatoria** (menzione nei metadati o pattern regex sicuri). Si applica a chat di gruppo WhatsApp, Telegram, Discord, Google Chat e iMessage. +Per default, i messaggi di gruppo **richiedono una mention** (mention nei metadati o pattern regex sicuri). Si applica alle chat di gruppo WhatsApp, Telegram, Discord, Google Chat e iMessage. -**Tipi di menzione:** +**Tipi di mention:** -- **Menzioni nei metadati**: @-mention native della piattaforma. Ignorate in modalità self-chat WhatsApp. -- **Pattern testuali**: pattern regex sicuri in `agents.list[].groupChat.mentionPatterns`. I pattern non validi e la ripetizione annidata non sicura vengono ignorati. -- Il gating per menzione viene applicato solo quando il rilevamento è possibile (menzioni native o almeno un pattern). +- **Mention nei metadati**: @-mention native della piattaforma. Ignorate in modalità self-chat 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. +- Il mention gating viene applicato solo quando il rilevamento è possibile (mention native o almeno un pattern). ```json5 { @@ -788,9 +778,9 @@ I messaggi di gruppo richiedono per default una **menzione obbligatoria** (menzi } ``` -`messages.groupChat.historyLimit` imposta il default globale. I canali possono fare override con `channels..historyLimit` (o per account). Imposta `0` per disabilitare. +`messages.groupChat.historyLimit` imposta il valore predefinito globale. I canali possono overridearlo con `channels..historyLimit` (o per account). Imposta `0` per disabilitare. -#### Limiti cronologia DM +#### Limiti della cronologia DM ```json5 { @@ -805,13 +795,13 @@ I messaggi di gruppo richiedono per default una **menzione obbligatoria** (menzi } ``` -Risoluzione: override per-DM → default provider → nessun limite (tutto mantenuto). +Risoluzione: override per DM → predefinito del provider → nessun limite (tutto mantenuto). Supportati: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. #### Modalità self-chat -Includi il tuo numero in `allowFrom` per abilitare la modalità self-chat (ignora le @-mention native, risponde solo ai pattern testuali): +Includi il tuo numero in `allowFrom` per abilitare la modalità self-chat (ignora le @-mention native, risponde solo ai pattern di testo): ```json5 { @@ -832,21 +822,21 @@ Includi il tuo numero in `allowFrom` per abilitare la modalità self-chat (ignor } ``` -### Commands (gestione comandi chat) +### Comandi (gestione dei comandi chat) ```json5 { commands: { - native: "auto", // registra comandi nativi quando supportati - nativeSkills: "auto", // registra comandi skill nativi quando supportati - text: true, // interpreta /commands nei messaggi chat + native: "auto", // registra i comandi nativi quando supportati + nativeSkills: "auto", // registra i comandi Skills nativi quando supportati + text: true, // analizza i /comandi nei messaggi chat bash: false, // consenti ! (alias: /bash) bashForegroundMs: 2000, config: false, // consenti /config mcp: false, // consenti /mcp plugins: false, // consenti /plugins debug: false, // consenti /debug - restart: true, // consenti /restart + strumento di riavvio gateway + restart: true, // consenti /restart + strumento di riavvio del gateway ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -861,32 +851,32 @@ Includi il tuo numero in `allowFrom` per abilitare la modalità self-chat (ignor -- Questo blocco configura le superfici dei comandi. Per il catalogo di comandi integrato + bundled attuale, vedi [Slash Commands](/it/tools/slash-commands). -- Questa pagina è un **riferimento delle chiavi di configurazione**, non il catalogo completo dei comandi. 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 loro pagine canale/plugin e in [Slash Commands](/it/tools/slash-commands). -- I comandi testuali devono essere messaggi **standalone** con `/` iniziale. -- `native: "auto"` attiva i comandi nativi per Discord/Telegram, lascia Slack disattivato. -- `nativeSkills: "auto"` attiva i comandi skill nativi per Discord/Telegram, lascia Slack disattivato. +- Questo blocco configura le superfici dei comandi. Per il catalogo attuale dei comandi built-in + bundled, vedi [Comandi Slash](/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 del canale/plugin e in [Comandi Slash](/it/tools/slash-commands). +- I comandi di testo devono essere messaggi **autonomi** con `/` iniziale. +- `native: "auto"` attiva i comandi nativi per Discord/Telegram e lascia Slack disattivato. +- `nativeSkills: "auto"` attiva i comandi Skills nativi per Discord/Telegram e lascia Slack disattivato. - Override per canale: `channels.discord.commands.native` (bool o `"auto"`). `false` cancella i comandi registrati in precedenza. -- Override della registrazione delle skill native per canale con `channels..commands.nativeSkills`. -- `channels.telegram.customCommands` aggiunge voci extra al menu bot Telegram. -- `bash: true` abilita `! ` per la shell host. Richiede `tools.elevated.enabled` e 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`; la lettura sola `/config show` resta disponibile ai normali client operator con ambito write. +- Override della registrazione delle Skills 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 `/config show` in sola lettura resta disponibile ai normali client operatore con ambito di scrittura. - `mcp: true` abilita `/mcp` per la configurazione del server MCP gestita da OpenClaw sotto `mcp.servers`. -- `plugins: true` abilita `/plugins` per individuazione, installazione e controlli di abilitazione/disabilitazione dei plugin. -- `channels..configWrites` gestisce le mutazioni di configurazione per canale (default: true). -- Per canali multi-account, `channels..accounts..configWrites` governa anche le scritture che mirano a quell'account (per esempio `/allowlist --config --account ` o `/config set channels..accounts....`). -- `restart: false` disabilita `/restart` e le azioni dello strumento di riavvio gateway. Default: `true`. +- `plugins: true` abilita `/plugins` per il rilevamento dei plugin, l'installazione e i 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 hanno come target 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 riservati al proprietario. È separata da `allowFrom`. -- `ownerDisplay: "hash"` applica hash agli ID proprietario nel system prompt. Imposta `ownerDisplaySecret` per controllare l'hash. -- `allowFrom` è per-provider. Quando impostato, è l'**unica** fonte di autorizzazione (le allowlist/pairing del canale e `useAccessGroups` vengono ignorati). +- `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/pairing 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 comandi: - - catalogo integrato + bundled: [Slash Commands](/it/tools/slash-commands) - - superfici di comando specifiche del canale: [Channels](/it/channels) +- Mappa della documentazione dei comandi: + - catalogo built-in + bundled: [Comandi Slash](/it/tools/slash-commands) + - superfici di comando specifiche del canale: [Canali](/it/channels) - comandi QQ Bot: [QQ Bot](/it/channels/qqbot) - comandi di pairing: [Pairing](/it/channels/pairing) - - comando card LINE: [LINE](/it/channels/line) - - dreaming memory: [Dreaming](/it/concepts/dreaming) + - comando card di LINE: [LINE](/it/channels/line) + - dreaming della memoria: [Dreaming](/it/concepts/dreaming) @@ -896,7 +886,7 @@ Includi il tuo numero in `allowFrom` per abilitare la modalità self-chat (ignor ### `agents.defaults.workspace` -Default: `~/.openclaw/workspace`. +Predefinito: `~/.openclaw/workspace`. ```json5 { @@ -906,7 +896,7 @@ Default: `~/.openclaw/workspace`. ### `agents.defaults.repoRoot` -Radice del repository facoltativa mostrata nella riga Runtime del system prompt. Se non impostata, OpenClaw la rileva automaticamente risalendo dalla workspace. +Radice del repository facoltativa mostrata nella riga Runtime del prompt di sistema. Se non è impostata, OpenClaw la rileva automaticamente risalendo dalla workspace. ```json5 { @@ -916,7 +906,7 @@ Radice del repository facoltativa mostrata nella riga Runtime del system prompt. ### `agents.defaults.skills` -Allowlist predefinita facoltativa di skill per agenti che non impostano +Allowlist predefinita facoltativa delle Skills per gli agenti che non impostano `agents.list[].skills`. ```json5 @@ -925,17 +915,17 @@ Allowlist predefinita facoltativa di skill per agenti che non impostano defaults: { skills: ["github", "weather"] }, list: [ { id: "writer" }, // eredita github, weather - { id: "docs", skills: ["docs-search"] }, // sostituisce i default - { id: "locked-down", skills: [] }, // nessuna skill + { id: "docs", skills: ["docs-search"] }, // sostituisce i valori predefiniti + { id: "locked-down", skills: [] }, // nessuna Skills ], }, } ``` -- Ometti `agents.defaults.skills` per skill senza restrizioni per default. -- Ometti `agents.list[].skills` per ereditare i default. -- Imposta `agents.list[].skills: []` per nessuna skill. -- Una lista non vuota `agents.list[].skills` è l'insieme finale per quell'agente; non viene fusa con i default. +- Ometti `agents.defaults.skills` per avere Skills senza restrizioni per default. +- Ometti `agents.list[].skills` per ereditare i valori predefiniti. +- Imposta `agents.list[].skills: []` per non avere Skills. +- Un elenco `agents.list[].skills` non vuoto è l'insieme finale per quell'agente; non viene unito ai valori predefiniti. ### `agents.defaults.skipBootstrap` @@ -949,9 +939,9 @@ Disabilita la creazione automatica dei file bootstrap della workspace (`AGENTS.m ### `agents.defaults.contextInjection` -Controlla quando i file bootstrap della workspace vengono iniettati nel system prompt. Default: `"always"`. +Controlla quando i file bootstrap della workspace vengono iniettati nel prompt di sistema. Predefinito: `"always"`. -- `"continuation-skip"`: i turni di continuazione sicuri (dopo una risposta assistente completata) saltano la re-iniezione del bootstrap della workspace, riducendo la dimensione del prompt. Le esecuzioni heartbeat e i retry dopo compattazione ricostruiscono comunque il contesto. +- `"continuation-skip"`: nei turni di continuazione sicuri (dopo una risposta completata dell'assistente) la reiniezione del bootstrap della workspace viene saltata, riducendo la dimensione del prompt. Le esecuzioni heartbeat e i retry dopo la compattazione ricostruiscono comunque il contesto. ```json5 { @@ -961,7 +951,7 @@ Controlla quando i file bootstrap della workspace vengono iniettati nel system p ### `agents.defaults.bootstrapMaxChars` -Numero massimo di caratteri per file bootstrap della workspace prima del troncamento. Default: `20000`. +Numero massimo di caratteri per file bootstrap della workspace prima del troncamento. Predefinito: `20000`. ```json5 { @@ -971,7 +961,7 @@ Numero massimo di caratteri per file bootstrap della workspace prima del troncam ### `agents.defaults.bootstrapTotalMaxChars` -Numero massimo totale di caratteri iniettati su tutti i file bootstrap della workspace. Default: `150000`. +Numero massimo totale di caratteri iniettati in tutti i file bootstrap della workspace. Predefinito: `150000`. ```json5 { @@ -982,9 +972,9 @@ Numero massimo totale di caratteri iniettati su tutti i file bootstrap della wor ### `agents.defaults.bootstrapPromptTruncationWarning` Controlla il testo di avviso visibile all'agente quando il contesto bootstrap viene troncato. -Default: `"once"`. +Predefinito: `"once"`. -- `"off"`: non iniettare mai il testo di avviso nel system prompt. +- `"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. @@ -996,10 +986,10 @@ Default: `"once"`. ### `agents.defaults.imageMaxDimensionPx` -Dimensione massima in pixel del lato più lungo dell'immagine nei blocchi immagine transcript/tool prima delle chiamate al provider. -Default: `1200`. +Dimensione massima in pixel del lato più lungo dell'immagine nei blocchi immagine di transcript/tool prima delle chiamate al provider. +Predefinito: `1200`. -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ù bassi di solito riducono l'uso di vision token e la dimensione del payload della richiesta nelle esecuzioni con molti screenshot. Valori più alti preservano più dettaglio visivo. ```json5 @@ -1010,7 +1000,7 @@ Valori più alti preservano più dettaglio visivo. ### `agents.defaults.userTimezone` -Fuso orario per il contesto del system prompt (non i timestamp dei messaggi). Usa come fallback il fuso orario dell'host. +Fuso orario per il contesto del prompt di sistema (non per i timestamp dei messaggi). Usa come fallback il fuso orario dell'host. ```json5 { @@ -1020,7 +1010,7 @@ Fuso orario per il contesto del system prompt (non i timestamp dei messaggi). Us ### `agents.defaults.timeFormat` -Formato ora nel system prompt. Default: `auto` (preferenza OS). +Formato ora nel prompt di sistema. Predefinito: `auto` (preferenza del sistema operativo). ```json5 { @@ -1058,7 +1048,7 @@ Formato ora nel system prompt. Default: `auto` (preferenza OS). primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // parametri provider predefiniti globali + params: { cacheRetention: "long" }, // parametri globali predefiniti del provider pdfMaxBytesMb: 10, pdfMaxPages: 20, thinkingDefault: "low", @@ -1073,64 +1063,64 @@ Formato ora nel system prompt. Default: `auto` (preferenza OS). } ``` -- `model`: accetta una stringa (`"provider/model"`) o un oggetto (`{ primary, fallbacks }`). +- `model`: accetta una stringa (`"provider/model"`) oppure un oggetto (`{ primary, fallbacks }`). - La forma stringa imposta solo il modello primario. - La forma oggetto imposta il primario più i modelli di failover ordinati. -- `imageModel`: accetta una stringa (`"provider/model"`) o un oggetto (`{ primary, fallbacks }`). +- `imageModel`: accetta una stringa (`"provider/model"`) oppure un oggetto (`{ primary, fallbacks }`). - Usato dal percorso dello strumento `image` come configurazione del suo modello vision. - Usato anche come routing di fallback quando il modello selezionato/predefinito non può accettare input immagine. -- `imageGenerationModel`: accetta una stringa (`"provider/model"`) o un oggetto (`{ primary, fallbacks }`). - - Usato dalla capacità condivisa di generazione immagini e da qualsiasi futura superficie tool/plugin che generi immagini. - - Valori tipici: `google/gemini-3.1-flash-image-preview` per generazione immagini Gemini nativa, `fal/fal-ai/flux/dev` per fal, o `openai/gpt-image-1` per OpenAI Images. - - Se selezioni direttamente un provider/modello, configura anche la corrispondente auth/API key del provider (per 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 dall'auth. Prova prima il provider predefinito corrente, poi i restanti provider di generazione immagine registrati in ordine di provider-id. -- `musicGenerationModel`: accetta una stringa (`"provider/model"`) o un oggetto (`{ primary, fallbacks }`). - - Usato dalla capacità condivisa di generazione musicale e dallo strumento integrato `music_generate`. +- `imageGenerationModel`: accetta una stringa (`"provider/model"`) oppure un oggetto (`{ primary, fallbacks }`). + - 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 immagini nativa di Gemini, `fal/fal-ai/flux/dev` per fal o `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. +- `musicGenerationModel`: accetta una stringa (`"provider/model"`) oppure un oggetto (`{ primary, fallbacks }`). + - Usato dalla capability condivisa di generazione musicale e dallo strumento built-in `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 dall'auth. 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 la corrispondente auth/API key del provider. -- `videoGenerationModel`: accetta una stringa (`"provider/model"`) o un oggetto (`{ primary, fallbacks }`). - - Usato dalla capacità condivisa di generazione video e dallo strumento integrato `video_generate`. + - 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. + - Se selezioni direttamente un provider/modello, configura anche l'autenticazione/la chiave API del provider corrispondente. +- `videoGenerationModel`: accetta una stringa (`"provider/model"`) oppure un oggetto (`{ primary, fallbacks }`). + - Usato dalla capability condivisa di generazione video e dallo strumento built-in `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 dall'auth. 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 la corrispondente auth/API key del provider. - - Il provider bundled per 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 una stringa (`"provider/model"`) o un oggetto (`{ primary, fallbacks }`). + - 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. + - 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 output, 1 immagine in input, 4 video in input, 10 secondi di durata e opzioni a livello provider `size`, `aspectRatio`, `resolution`, `audio` e `watermark`. +- `pdfModel`: accetta una stringa (`"provider/model"`) oppure un oggetto (`{ primary, fallbacks }`). - Usato dallo strumento `pdf` per il routing del modello. - - Se omesso, lo strumento PDF ripiega su `imageModel`, poi sul modello di sessione/default risolto. -- `pdfMaxBytesMb`: limite dimensione PDF predefinito per lo strumento `pdf` quando `maxBytesMb` non viene passato al momento della chiamata. + - Se omesso, lo strumento PDF ricade su `imageModel`, poi sul modello risolto della sessione/predefinito. +- `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`. -- `verboseDefault`: livello verbose predefinito per gli agenti. Valori: `"off"`, `"on"`, `"full"`. Default: `"off"`. -- `elevatedDefault`: livello predefinito di output elevated per gli agenti. Valori: `"off"`, `"on"`, `"ask"`, `"full"`. Default: `"on"`. -- `model.primary`: formato `provider/model` (es. `openai/gpt-5.4`). Se ometti il provider, OpenClaw prova prima un alias, poi una corrispondenza univoca di configured-provider per quel preciso model id, e solo allora ripiega sul provider predefinito configurato (comportamento di compatibilità deprecato, quindi preferisci `provider/model` esplicito). Se quel provider non espone più il modello predefinito configurato, OpenClaw ripiega sul primo provider/modello configurato invece di mostrare un default obsoleto di provider rimosso. -- `models`: catalogo modelli configurato e allowlist per `/model`. Ogni voce può includere `alias` (scorciatoia) e `params` (specifici del provider, per esempio `temperature`, `maxTokens`, `cacheRetention`, `context1m`). -- `params`: parametri provider predefiniti globali applicati a tutti i modelli. Impostali in `agents.defaults.params` (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), poi `agents.list[].params` (ID agente corrispondente) sovrascrive per chiave. Vedi [Prompt Caching](/it/reference/prompt-caching) per i dettagli. -- I writer di configurazione che mutano questi campi (per esempio `/models set`, `/models set-image` e comandi add/remove dei fallback) salvano la forma canonica a oggetto e preservano le liste fallback esistenti quando possibile. -- `maxConcurrent`: numero massimo di esecuzioni agente parallele tra sessioni (ogni sessione resta comunque serializzata). Default: 4. +- `verboseDefault`: livello verbose predefinito per gli agenti. Valori: `"off"`, `"on"`, `"full"`. Predefinito: `"off"`. +- `elevatedDefault`: livello predefinito di output elevated 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 ricade sul provider predefinito configurato (comportamento di compatibilità deprecato, quindi preferisci `provider/model` esplicito). Se quel provider non espone più il modello predefinito configurato, OpenClaw ricade sul primo provider/modello configurato invece di mostrare un predefinito obsoleto di un provider rimosso. +- `models`: il catalogo dei modelli configurati e la 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. Impostali in `agents.defaults.params` (ad esempio `{ cacheRetention: "long" }`). +- Precedenza di merge di `params` (config): `agents.defaults.params` (base globale) viene sovrascritto da `agents.defaults.models["provider/model"].params` (per modello), poi `agents.list[].params` (ID agente corrispondente) sovrascrive per chiave. Vedi [Caching dei prompt](/it/reference/prompt-caching) per i dettagli. +- 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 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. -**Scorciatoie alias integrate** (si applicano solo quando il modello è in `agents.defaults.models`): +**Scorciatoie alias built-in** (si applicano solo quando il modello è in `agents.defaults.models`): -| Alias | Modello | -| ------------------- | -------------------------------------- | -| `opus` | `anthropic/claude-opus-4-6` | -| `sonnet` | `anthropic/claude-sonnet-4-6` | -| `gpt` | `openai/gpt-5.4` | -| `gpt-mini` | `openai/gpt-5.4-mini` | -| `gpt-nano` | `openai/gpt-5.4-nano` | -| `gemini` | `google/gemini-3.1-pro-preview` | -| `gemini-flash` | `google/gemini-3-flash-preview` | +| Alias | Modello | +| ------------------- | ------------------------------------- | +| `opus` | `anthropic/claude-opus-4-6` | +| `sonnet` | `anthropic/claude-sonnet-4-6` | +| `gpt` | `openai/gpt-5.4` | +| `gpt-mini` | `openai/gpt-5.4-mini` | +| `gpt-nano` | `openai/gpt-5.4-nano` | +| `gemini` | `google/gemini-3.1-pro-preview` | +| `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -I tuoi alias configurati hanno sempre precedenza sui default. +Gli alias che configuri 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 default per lo streaming delle chiamate tool. Imposta `agents.defaults.models["zai/"].params.tool_stream` a `false` per disabilitarlo. -I modelli Anthropic Claude 4.6 usano come default il thinking `adaptive` quando non è impostato alcun livello di thinking esplicito. +I modelli Z.AI abilitano `tool_stream` per default per lo streaming delle chiamate agli strumenti. Imposta `agents.defaults.models["zai/"].params.tool_stream` su `false` per disabilitarlo. +I modelli Anthropic Claude 4.6 usano per default `adaptive` thinking quando non è impostato alcun livello di thinking esplicito. ### `agents.defaults.cliBackends` -Backend CLI facoltativi per esecuzioni di fallback solo testo (senza chiamate tool). Utile come backup quando i provider API falliscono. +CLI backend facoltativi per esecuzioni di fallback solo testo (senza chiamate agli strumenti). Utili come backup quando i provider API falliscono. ```json5 { @@ -1158,13 +1148,13 @@ Backend CLI facoltativi per esecuzioni di fallback solo testo (senza chiamate to } ``` -- I backend CLI sono orientati al testo; i tool sono sempre disabilitati. -- Sessioni supportate quando `sessionArg` è impostato. -- Il pass-through delle immagini è supportato quando `imageArg` accetta percorsi file. +- I CLI backend sono orientati prima di tutto al testo; gli strumenti sono sempre disabilitati. +- Le sessioni sono supportate quando `sessionArg` è impostato. +- Il pass-through delle immagini è supportato quando `imageArg` accetta percorsi di file. ### `agents.defaults.systemPromptOverride` -Sostituisci l'intero system prompt 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 precedenza; un valore vuoto o composto solo da spazi viene ignorato. Utile per esperimenti controllati sul 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 { @@ -1188,13 +1178,13 @@ Esecuzioni heartbeat periodiche. every: "30m", // 0m disabilita model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // default: true; false omette la sezione Heartbeat dal system prompt - lightContext: false, // default: false; true mantiene solo HEARTBEAT.md tra i file bootstrap della workspace - isolatedSession: false, // default: false; true esegue ogni heartbeat in una sessione nuova (senza cronologia conversazione) + 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 (nessuna cronologia conversazione) session: "main", to: "+15555550123", - directPolicy: "allow", // allow (default) | block - target: "none", // default: none | opzioni: last | whatsapp | telegram | discord | ... + directPolicy: "allow", // allow (predefinito) | block + target: "none", // predefinito: none | opzioni: last | whatsapp | telegram | discord | ... prompt: "Leggi HEARTBEAT.md se esiste...", ackMaxChars: 300, suppressToolErrorWarnings: false, @@ -1204,14 +1194,14 @@ Esecuzioni heartbeat periodiche. } ``` -- `every`: stringa durata (ms/s/m/h). Default: `30m` (auth API-key) o `1h` (auth OAuth). Imposta `0m` per disabilitare. -- `includeSystemPromptSection`: quando false, omette la sezione Heartbeat dal system prompt e salta l'iniezione di `HEARTBEAT.md` nel contesto bootstrap. Default: `true`. -- `suppressToolErrorWarnings`: quando true, sopprime i payload di avviso di errore tool durante le esecuzioni heartbeat. -- `directPolicy`: criterio di consegna diretta/DM. `allow` (default) consente la consegna a target diretto. `block` la sopprime ed emette `reason=dm-blocked`. +- `every`: stringa durata (ms/s/m/h). Predefinito: `30m` (autenticazione tramite chiave API) o `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 di errore degli strumenti durante le esecuzioni heartbeat. +- `directPolicy`: criterio di consegna diretta/DM. `allow` (predefinito) consente la consegna diretta al target. `block` sopprime la consegna diretta al target ed emette `reason=dm-blocked`. - `lightContext`: quando true, le esecuzioni heartbeat usano un contesto bootstrap leggero e mantengono solo `HEARTBEAT.md` dai 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 token per heartbeat da ~100K a ~2-5K token. -- Per-agente: imposta `agents.list[].heartbeat`. Quando qualsiasi agente definisce `heartbeat`, **solo quegli agenti** eseguono heartbeat. -- Gli heartbeat eseguono turni agente completi — intervalli più brevi consumano più token. +- `isolatedSession`: quando true, ogni heartbeat viene eseguito in una sessione nuova senza cronologia conversazionale precedente. Stesso modello di isolamento di 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` @@ -1227,13 +1217,13 @@ Esecuzioni heartbeat periodiche. identifierPolicy: "strict", // strict | off | custom 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 reiniezione - model: "openrouter/anthropic/claude-sonnet-4-6", // override facoltativo del modello solo per compaction - notifyUser: true, // invia un breve avviso quando inizia la compaction (default: false) + model: "openrouter/anthropic/claude-sonnet-4-6", // override facoltativo 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 avvicina alla compaction. Memorizza 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 salvare.", + systemPrompt: "La sessione si avvicina alla compaction. Memorizza ora le memorie 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 memorizzare.", }, }, }, @@ -1241,19 +1231,19 @@ Esecuzioni heartbeat periodiche. } ``` -- `mode`: `default` o `safeguard` (riassunto a 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 riassunto LLM integrato. In caso di errore, ripiega su quello 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. Default: `900`. -- `identifierPolicy`: `strict` (default), `off` o `custom`. `strict` antepone la guida integrata per la conservazione di identificatori opachi durante il riassunto di compaction. -- `identifierInstructions`: testo facoltativo personalizzato di preservazione identificatori usato quando `identifierPolicy=custom`. -- `postCompactionSections`: nomi facoltativi di sezioni H2/H3 di AGENTS.md da re-iniettare dopo la compaction. Default `["Session Startup", "Red Lines"]`; imposta `[]` per disabilitare la reiniezione. Quando non impostato o esplicitamente impostato a quella coppia di default, vengono accettati anche i titoli legacy `Every Session`/`Safety` come fallback retrocompatibile. -- `model`: override facoltativo `provider/model-id` solo per il riassunto di compaction. Usalo quando la sessione principale deve mantenere un modello ma i riassunti di compaction devono essere eseguiti su 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 (per esempio "Compattazione del contesto..."). È disabilitato per default per mantenere la compaction silenziosa. -- `memoryFlush`: turno silenzioso agentico prima della auto-compaction per memorizzare ricordi durevoli. Saltato quando la workspace è in sola lettura. +- `mode`: `default` o `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 built-in. In caso di errore, ricade sul built-in. 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` o `custom`. `strict` antepone una guida built-in per la conservazione di identificatori opachi durante il riepilogo della compaction. +- `identifierInstructions`: testo personalizzato facoltativo per la preservazione degli identificatori usato quando `identifierPolicy=custom`. +- `postCompactionSections`: nomi facoltativi delle sezioni H2/H3 di AGENTS.md da reiniettare dopo la compaction. Il valore predefinito è `["Session Startup", "Red Lines"]`; imposta `[]` per disabilitare la reiniezione. Quando non è impostato oppure è impostato esplicitamente a quella coppia predefinita, vengono accettate come fallback legacy anche le intestazioni precedenti `Every Session`/`Safety`. +- `model`: override facoltativo `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; quando non è impostato, la compaction usa il modello primario della sessione. +- `notifyUser`: quando `true`, invia un breve avviso all'utente all'inizio della compaction (ad esempio, "Compattazione del contesto in corso..."). Disabilitato per default per mantenere la compaction silenziosa. +- `memoryFlush`: turno agentico silenzioso prima dell'auto-compaction per memorizzare ricordi durevoli. Viene saltato quando la workspace è in sola lettura. ### `agents.defaults.contextPruning` -Pota i **vecchi risultati dei tool** dal contesto in memoria prima di inviarlo all'LLM. **Non** modifica la cronologia della sessione su disco. +Rimuove **i vecchi risultati degli strumenti** dal contesto in memoria prima di inviarlo al LLM. **Non** modifica la cronologia della sessione su disco. ```json5 { @@ -1267,7 +1257,7 @@ Pota i **vecchi risultati dei tool** dal contesto in memoria prima di inviarlo a hardClearRatio: 0.5, minPrunableToolChars: 50000, softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }, - hardClear: { enabled: true, placeholder: "[Contenuto del vecchio risultato tool eliminato]" }, + hardClear: { enabled: true, placeholder: "[Contenuto del vecchio risultato dello strumento cancellato]" }, tools: { deny: ["browser", "canvas"] }, }, }, @@ -1279,23 +1269,23 @@ Pota i **vecchi risultati dei tool** dal contesto in memoria prima di inviarlo a - `mode: "cache-ttl"` abilita i passaggi di pruning. - `ttl` controlla ogni quanto il pruning può essere eseguito di nuovo (dopo l'ultimo tocco della cache). -- Il pruning esegue prima soft-trim dei risultati tool sovradimensionati, poi hard-clear dei risultati tool più vecchi se necessario. +- Il pruning esegue prima il soft-trim dei risultati degli strumenti troppo grandi, poi se necessario cancella completamente i risultati degli strumenti più vecchi. **Soft-trim** mantiene inizio + fine e inserisce `...` nel mezzo. -**Hard-clear** sostituisce l'intero risultato del tool con il placeholder. +**Hard-clear** sostituisce l'intero risultato dello strumento con il placeholder. Note: -- I blocchi immagine non vengono mai trimmati/eliminati. +- I blocchi immagine non vengono mai ridotti o cancellati. - I rapporti sono basati sui caratteri (approssimativi), non su conteggi esatti di token. -- Se esistono meno di `keepLastAssistants` messaggi assistente, il pruning viene saltato. +- Se esistono meno di `keepLastAssistants` messaggi dell'assistente, il pruning viene saltato. -Vedi [Session Pruning](/it/concepts/session-pruning) per i dettagli di comportamento. +Vedi [Session Pruning](/it/concepts/session-pruning) per i dettagli sul comportamento. -### Block streaming +### Streaming a blocchi ```json5 { @@ -1311,11 +1301,11 @@ Vedi [Session Pruning](/it/concepts/session-pruning) per i dettagli di comportam } ``` -- I canali non Telegram richiedono `*.blockStreaming: true` esplicito per abilitare le risposte a blocchi. -- Override di canale: `channels..blockStreamingCoalesce` (e varianti per-account). Signal/Slack/Discord/Google Chat hanno come default `minChars: 1500`. -- `humanDelay`: pausa casuale tra risposte a blocchi. `natural` = 800–2500ms. Override per agente: `agents.list[].humanDelay`. +- I canali diversi da Telegram richiedono `*.blockStreaming: true` esplicito per abilitare le risposte a blocchi. +- Override del canale: `channels..blockStreamingCoalesce` (e varianti per account). Signal/Slack/Discord/Google Chat hanno come predefinito `minChars: 1500`. +- `humanDelay`: pausa casuale tra le risposte a blocchi. `natural` = 800–2500 ms. Override per agente: `agents.list[].humanDelay`. -Vedi [Streaming](/it/concepts/streaming) per dettagli su comportamento + chunking. +Vedi [Streaming](/it/concepts/streaming) per i dettagli su comportamento e suddivisione in blocchi. ### Indicatori di digitazione @@ -1330,16 +1320,16 @@ Vedi [Streaming](/it/concepts/streaming) per dettagli su comportamento + chunkin } ``` -- Default: `instant` per chat dirette/menzioni, `message` per chat di gruppo senza menzione. +- Valori predefiniti: `instant` per chat dirette/mention, `message` per chat di gruppo senza mention. - Override per sessione: `session.typingMode`, `session.typingIntervalSeconds`. -Vedi [Typing Indicators](/it/concepts/typing-indicators). +Vedi [Indicatori di digitazione](/it/concepts/typing-indicators). ### `agents.defaults.sandbox` -Sandboxing facoltativo per l'agente integrato. Vedi [Sandboxing](/it/gateway/sandboxing) per la guida completa. +Sandbox facoltativa per l'agente incorporato. Vedi [Sandboxing](/it/gateway/sandboxing) per la guida completa. ```json5 { @@ -1434,52 +1424,52 @@ Sandboxing facoltativo per l'agente integrato. Vedi [Sandboxing](/it/gateway/san } ``` - + **Backend:** -- `docker`: runtime Docker locale (default) +- `docker`: runtime Docker locale (predefinito) - `ssh`: runtime remoto generico basato su SSH - `openshell`: runtime OpenShell -Quando è selezionato `backend: "openshell"`, le impostazioni specifiche del runtime si spostano in +Quando viene selezionato `backend: "openshell"`, le impostazioni specifiche del runtime si spostano in `plugins.entries.openshell.config`. **Configurazione backend SSH:** - `target`: target SSH nel formato `user@host[:port]` -- `command`: comando client SSH (default: `ssh`) -- `workspaceRoot`: root remota assoluta usata per workspace per-scope +- `command`: comando del client SSH (predefinito: `ssh`) +- `workspaceRoot`: root remota assoluta usata per le workspace per ambito - `identityFile` / `certificateFile` / `knownHostsFile`: file locali esistenti passati a OpenSSH - `identityData` / `certificateData` / `knownHostsData`: contenuti inline o SecretRef che OpenClaw materializza in file temporanei a runtime -- `strictHostKeyChecking` / `updateHostKeys`: controlli del criterio host-key OpenSSH +- `strictHostKeyChecking` / `updateHostKeys`: controlli del criterio della chiave host OpenSSH -**Precedenza auth SSH:** +**Precedenza di autenticazione SSH:** -- `identityData` prevale su `identityFile` -- `certificateData` prevale su `certificateFile` -- `knownHostsData` prevale su `knownHostsFile` -- I valori `*Data` supportati da SecretRef vengono risolti dallo snapshot attivo del runtime secrets 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 backend SSH:** +**Comportamento del backend SSH:** -- inizializza la workspace remota una sola volta dopo create o recreate +- inizializza una volta la workspace remota dopo la creazione o ricreazione - poi mantiene canonica la workspace SSH remota -- instrada `exec`, i file tool e i percorsi media tramite SSH -- non sincronizza automaticamente sul host le modifiche remote +- instrada `exec`, gli strumenti file e i percorsi media su SSH +- non sincronizza automaticamente con l'host le modifiche remote - non supporta container browser sandbox **Accesso alla workspace:** -- `none`: workspace sandbox per-scope sotto `~/.openclaw/sandboxes` +- `none`: workspace sandbox per ambito sotto `~/.openclaw/sandboxes` - `ro`: workspace sandbox in `/workspace`, workspace agente montata in sola lettura in `/agent` -- `rw`: workspace agente montata lettura/scrittura in `/workspace` +- `rw`: workspace agente montata in lettura/scrittura in `/workspace` -**Scope:** +**Ambito:** - `session`: container + workspace per sessione -- `agent`: un container + workspace per agente (default) -- `shared`: container e workspace condivisi (nessun isolamento cross-session) +- `agent`: un container + workspace per agente (predefinito) +- `shared`: container e workspace condivisi (nessun isolamento tra sessioni) **Configurazione plugin OpenShell:** @@ -1509,30 +1499,30 @@ Quando è selezionato `backend: "openshell"`, le impostazioni specifiche del run **Modalità OpenShell:** -- `mirror`: inizializza il remoto dal locale prima di exec, sincronizza indietro dopo exec; la workspace locale resta canonica -- `remote`: inizializza il remoto una sola volta quando il sandbox viene creato, poi mantiene canonica la workspace remota +- `mirror`: inizializza il remoto dal locale prima di `exec`, sincronizza indietro dopo `exec`; la workspace locale resta canonica +- `remote`: inizializza il remoto una volta quando la sandbox viene creata, poi mantiene canonica la workspace remota -In modalità `remote`, le modifiche locali sull'host fatte fuori da OpenClaw non vengono sincronizzate automaticamente nel sandbox dopo la fase iniziale di seed. -Il trasporto avviene via SSH nel sandbox OpenShell, ma il plugin possiede il ciclo di vita del sandbox e la sincronizzazione mirror facoltativa. +In modalità `remote`, le modifiche locali sull'host fatte fuori da OpenClaw non vengono sincronizzate automaticamente nella sandbox dopo il passaggio di inizializzazione. +Il trasporto è SSH nella sandbox OpenShell, ma il plugin possiede il ciclo di vita della sandbox e l'eventuale sincronizzazione mirror. -**`setupCommand`** viene eseguito una volta dopo la creazione del container (tramite `sh -lc`). Richiede egress di rete, root scrivibile, utente root. +**`setupCommand`** viene eseguito una volta dopo la creazione del container (tramite `sh -lc`). Richiede uscita di rete, root scrivibile e utente root. -**I container hanno come default `network: "none"`** — imposta `"bridge"` (o una rete bridge personalizzata) se l'agente necessita di accesso in uscita. +**I container usano per default `network: "none"`**: imposta `"bridge"` (o una rete bridge personalizzata) se l'agente ha bisogno di accesso in uscita. `"host"` è bloccato. `"container:"` è bloccato per default a meno che tu non imposti esplicitamente -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (break-glass). +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (modalità break-glass). **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 fusi. +**`docker.binds`** monta directory host aggiuntive; i bind globali e per agente vengono uniti. -**Browser sandboxed** (`sandbox.browser.enabled`): Chromium + CDP in un container. L'URL noVNC viene iniettato nel system prompt. Non richiede `browser.enabled` in `openclaw.json`. -L'accesso osservatore noVNC usa l'autenticazione VNC per default 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 iniettato nel prompt di sistema. Non richiede `browser.enabled` in `openclaw.json`. +L'accesso osservatore noVNC usa per default l'autenticazione VNC e OpenClaw emette un URL con token a breve durata (invece di esporre la password nell'URL condiviso). -- `allowHostControl: false` (default) blocca le sessioni sandboxed dal puntare al browser host. -- `network` ha come default `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 (per esempio `172.21.0.1/32`). -- `sandbox.browser.binds` monta directory host aggiuntive solo nel container browser sandbox. Quando impostato (incluso `[]`), sostituisce `docker.binds` per il container browser. -- I default di avvio sono definiti in `scripts/sandbox-browser-entrypoint.sh` e ottimizzati per host container: +- `allowHostControl: false` (predefinito) blocca le sessioni sandboxed dal prendere come target il browser host. +- `network` ha come predefinito `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 (ad 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 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=` - `--user-data-dir=${HOME}/.chrome` @@ -1557,22 +1547,22 @@ L'accesso osservatore noVNC usa l'autenticazione VNC per default e OpenClaw emet dipende da esse. - `--renderer-process-limit=2` può essere modificato con `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; imposta `0` per usare il - limite processi predefinito di Chromium. + limite predefinito di Chromium. - più `--no-sandbox` e `--disable-setuid-sandbox` quando `noSandbox` è abilitato. - - I default sono la baseline dell'immagine container; usa un'immagine browser personalizzata con entrypoint personalizzato per cambiare i default 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 browser sandboxing e `sandbox.docker.binds` sono solo Docker. +Il browser sandboxing e `sandbox.docker.binds` sono solo per Docker. -Costruisci le immagini: +Crea le immagini: ```bash scripts/sandbox-setup.sh # immagine sandbox principale scripts/sandbox-browser-setup.sh # immagine browser facoltativa ``` -### `agents.list` (override per-agente) +### `agents.list` (override per agente) ```json5 { @@ -1585,11 +1575,11 @@ scripts/sandbox-browser-setup.sh # immagine browser facoltativa workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", model: "anthropic/claude-opus-4-6", // oppure { primary, fallbacks } - thinkingDefault: "high", // override livello thinking per-agente - reasoningDefault: "on", // override visibilità reasoning per-agente - fastModeDefault: false, // override fast mode per-agente - params: { cacheRetention: "none" }, // sovrascrive le chiavi corrispondenti di defaults.models - skills: ["docs-search"], // sostituisce agents.defaults.skills quando impostato + 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à fast + params: { cacheRetention: "none" }, // override per chiave dei params di defaults.models corrispondenti + skills: ["docs-search"], // sostituisce agents.defaults.skills quando è impostato identity: { name: "Samantha", theme: "bradipo disponibile", @@ -1621,25 +1611,25 @@ scripts/sandbox-browser-setup.sh # immagine browser facoltativa ``` - `id`: ID agente stabile (obbligatorio). -- `default`: quando ne sono impostati più di uno, vince il primo (viene registrato un avviso). Se nessuno è impostato, il primo elemento della lista è il default. -- `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 comunque a ereditare i fallback default a meno che tu non imposti `fallbacks: []`. -- `params`: parametri 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 facoltativa di skill per-agente. Se omessa, l'agente eredita `agents.defaults.skills` quando impostata; una lista esplicita sostituisce i default invece di fonderli, e `[]` significa nessuna skill. -- `thinkingDefault`: livello di thinking predefinito facoltativo per-agente (`off | minimal | low | medium | high | xhigh | adaptive`). Sovrascrive `agents.defaults.thinkingDefault` per questo agente quando non è impostato alcun override per-messaggio o per-sessione. -- `reasoningDefault`: override facoltativo per-agente della visibilità reasoning (`on | off | stream`). Si applica quando non è impostato alcun override reasoning per-messaggio o per-sessione. -- `fastModeDefault`: default facoltativo per-agente per fast mode (`true | false`). Si applica quando non è impostato alcun override fast-mode per-messaggio o per-sessione. -- `runtime`: descrittore runtime facoltativo per-agente. Usa `type: "acp"` con i default `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) quando l'agente deve usare di default sessioni harness ACP. +- `default`: quando ne sono impostati più di uno, vince il primo (viene registrato un avviso). Se non ne è impostato nessuno, il predefinito è la prima voce dell'elenco. +- `model`: la forma stringa override solo `primary`; la forma oggetto `{ primary, fallbacks }` override entrambi (`[]` disabilita i fallback globali). I job cron che overrideano solo `primary` ereditano comunque i fallback predefiniti a meno che tu non imposti `fallbacks: []`. +- `params`: parametri stream per agente uniti sopra la voce del modello selezionato in `agents.defaults.models`. Usali per override specifici dell'agente come `cacheRetention`, `temperature` o `maxTokens` senza duplicare l'intero catalogo modelli. +- `skills`: allowlist facoltativa delle Skills per agente. Se omessa, l'agente eredita `agents.defaults.skills` quando è impostato; un elenco esplicito sostituisce i valori predefiniti invece di unirli, e `[]` significa nessuna Skills. +- `thinkingDefault`: valore predefinito facoltativo per agente del livello di thinking (`off | minimal | low | medium | high | xhigh | adaptive`). Override `agents.defaults.thinkingDefault` per questo agente quando non è impostato alcun override per messaggio o sessione. +- `reasoningDefault`: valore predefinito facoltativo per agente della visibilità del reasoning (`on | off | stream`). Si applica quando non è impostato alcun override di reasoning per messaggio o sessione. +- `fastModeDefault`: valore predefinito facoltativo per agente della modalità fast (`true | false`). Si applica quando non è impostato alcun override della modalità fast per messaggio o sessione. +- `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 default sessioni harness ACP. - `identity.avatar`: percorso relativo alla workspace, URL `http(s)` o URI `data:`. -- `identity` deriva i default: `ackReaction` da `emoji`, `mentionPatterns` da `name`/`emoji`. -- `subagents.allowAgents`: allowlist di ID agente per `sessions_spawn` (`["*"]` = qualunque; default: solo lo stesso agente). -- Guardia di ereditarietà sandbox: se la sessione richiedente è sandboxed, `sessions_spawn` rifiuta target che verrebbero eseguiti senza sandbox. -- `subagents.requireAgentId`: quando true, blocca le chiamate `sessions_spawn` che omettono `agentId` (impone selezione esplicita del profilo; default: false). +- `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). +- Guardrail di 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 una selezione esplicita del profilo; predefinito: false). --- ## Routing multi-agent -Esegui più agenti isolati dentro un unico Gateway. Vedi [Multi-Agent](/it/concepts/multi-agent). +Esegui più agenti isolati all'interno di un unico Gateway. Vedi [Multi-Agent](/it/concepts/multi-agent). ```json5 { @@ -1656,11 +1646,11 @@ Esegui più agenti isolati dentro un unico Gateway. Vedi [Multi-Agent](/it/conce } ``` -### Campi di corrispondenza binding +### Campi di corrispondenza dei binding -- `type` (facoltativo): `route` per il routing normale (se manca, type ha default route), `acp` per binding persistenti di conversazione ACP. +- `type` (facoltativo): `route` per il routing normale (il tipo mancante usa come predefinito route), `acp` per binding di conversazioni ACP persistenti. - `match.channel` (obbligatorio) -- `match.accountId` (facoltativo; `*` = qualunque account; omesso = account predefinito) +- `match.accountId` (facoltativo; `*` = qualsiasi account; omesso = account predefinito) - `match.peer` (facoltativo; `{ kind: direct|group|channel, id }`) - `match.guildId` / `match.teamId` (facoltativo; specifici del canale) - `acp` (facoltativo; solo per voci `type: "acp"`): `{ mode, label, cwd, backend }` @@ -1670,17 +1660,17 @@ Esegui più agenti isolati dentro un unico Gateway. Vedi [Multi-Agent](/it/conce 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId` (esatto, nessun peer/guild/team) -5. `match.accountId: "*"` (esteso a tutto il canale) +4. `match.accountId` (esatto, senza peer/guild/team) +5. `match.accountId: "*"` (esteso al canale) 6. Agente predefinito All'interno di ogni livello, vince la prima voce `bindings` corrispondente. -Per le voci `type: "acp"`, OpenClaw risolve per identità esatta della conversazione (`match.channel` + account + `match.peer.id`) e non usa l'ordine a livelli dei binding route 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 dei livelli di binding route sopra. -### Profili di accesso per-agente +### Profili di accesso per agente - + ```json5 { @@ -1773,7 +1763,7 @@ Per le voci `type: "acp"`, OpenClaw risolve per identità esatta della conversaz -Vedi [Multi-Agent Sandbox & Tools](/it/tools/multi-agent-sandbox-tools) per i dettagli di precedenza. +Vedi [Sandbox e strumenti multi-agent](/it/tools/multi-agent-sandbox-tools) per i dettagli sulla precedenza. --- @@ -1799,7 +1789,7 @@ 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 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", @@ -1807,12 +1797,12 @@ Vedi [Multi-Agent Sandbox & Tools](/it/tools/multi-agent-sandbox-tools) per i de rotateBytes: "10mb", resetArchiveRetention: "30d", // durata o false maxDiskBytes: "500mb", // budget rigido facoltativo - highWaterBytes: "400mb", // target di cleanup facoltativo + highWaterBytes: "400mb", // target di pulizia facoltativo }, threadBindings: { enabled: true, - idleHours: 24, // default auto-unfocus dopo inattività in ore (`0` disabilita) - maxAgeHours: 0, // default età massima rigida 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") agentToAgent: { maxPingPongTurns: 5 }, @@ -1824,37 +1814,37 @@ Vedi [Multi-Agent Sandbox & Tools](/it/tools/multi-agent-sandbox-tools) per i de } ``` - + -- **`scope`**: strategia base di raggruppamento della sessione per i contesti di chat di gruppo. - - `per-sender` (default): ogni mittente ottiene una sessione isolata dentro un contesto canale. - - `global`: tutti i partecipanti in un contesto canale condividono una singola sessione (usalo solo quando è voluto un contesto condiviso). +- **`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 di un contesto di 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 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 ID canonici a peer con prefisso provider per la condivisione di sessione cross-channel. -- **`reset`**: criterio di reset primario. `daily` resetta all'`atHour` locale; `idle` resetta dopo `idleMinutes`. Quando entrambi sono configurati, prevale quello che scade prima. +- **`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 all'ora locale `atHour`; `idle` esegue il reset 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`**: massimo `totalTokens` della sessione padre consentito quando si crea una sessione thread forked (default `100000`). - - Se il `totalTokens` del padre è sopra questo valore, OpenClaw avvia una nuova sessione thread invece di ereditare la cronologia transcript del 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 reply-back tra agenti durante scambi agent-to-agent (intero, intervallo: `0`–`5`). `0` disabilita la catena ping-pong. -- **`sendPolicy`**: corrisponde per `channel`, `chatType` (`direct|group|channel`, con alias legacy `dm`), `keyPrefix` o `rawKeyPrefix`. Vince il primo deny. -- **`maintenance`**: controlli di cleanup + retention del session-store. - - `mode`: `warn` emette solo avvisi; `enforce` applica il cleanup. - - `pruneAfter`: soglia temporale per voci obsolete (default `30d`). - - `maxEntries`: numero massimo di voci in `sessions.json` (default `500`). - - `rotateBytes`: ruota `sessions.json` quando supera questa dimensione (default `10mb`). - - `resetArchiveRetention`: retention per gli archivi transcript `*.reset.`. Ha come default `pruneAfter`; imposta `false` per disabilitare. - - `maxDiskBytes`: budget disco facoltativo per la directory sessioni. In modalità `warn` registra avvisi; in modalità `enforce` rimuove prima gli artefatti/sessioni più vecchi. - - `highWaterBytes`: target facoltativo dopo il cleanup del budget. Ha come default l'`80%` di `maxDiskBytes`. -- **`threadBindings`**: default globali per funzionalità di sessione legate ai thread. - - `enabled`: interruttore predefinito master (i provider possono fare override; Discord usa `channels.discord.threadBindings.enabled`) - - `idleHours`: default auto-unfocus per inattività in ore (`0` disabilita; i provider possono fare override) - - `maxAgeHours`: default età massima rigida in ore (`0` disabilita; i provider possono fare override) +- **`parentForkMaxTokens`**: massimo `totalTokens` della sessione padre consentito quando si crea una sessione thread forked (predefinito `100000`). + - Se il `totalTokens` del padre è superiore a questo valore, OpenClaw avvia una nuova sessione thread invece di ereditare la cronologia del transcript del padre. + - Imposta `0` per disabilitare questa protezione e consentire sempre il fork dal padre. +- **`mainKey`**: campo legacy. Il runtime usa sempre `"main"` per il bucket principale della chat diretta. +- **`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`**: corrispondenza per `channel`, `chatType` (`direct|group|channel`, con alias legacy `dm`), `keyPrefix` o `rawKeyPrefix`. Vince il primo deny. +- **`maintenance`**: controlli di pulizia + conservazione dello store delle sessioni. + - `mode`: `warn` emette solo avvisi; `enforce` applica la pulizia. + - `pruneAfter`: limite di età 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 transcript `*.reset.`. Il predefinito è `pruneAfter`; imposta `false` per disabilitare. + - `maxDiskBytes`: budget disco facoltativo per la directory delle sessioni. In modalità `warn` registra avvisi; in modalità `enforce` rimuove prima gli artefatti/le sessioni più vecchi. + - `highWaterBytes`: target facoltativo dopo la pulizia del budget. Il predefinito è `80%` di `maxDiskBytes`. +- **`threadBindings`**: valori predefiniti globali per le funzionalità di sessione associate ai thread. + - `enabled`: interruttore predefinito principale (i provider possono fare override; Discord usa `channels.discord.threadBindings.enabled`) + - `idleHours`: auto-unfocus 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) @@ -1896,32 +1886,32 @@ Override per canale/account: `channels..responsePrefix`, `channels..ackReaction`, `channels..accounts..ackReaction`. -- Ordine di risoluzione: account → canale → `messages.ackReaction` → fallback identity. -- Scope: `group-mentions` (default), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: rimuove l'ack dopo la risposta su Slack, Discord e Telegram. +- Ordine di risoluzione: account → canale → `messages.ackReaction` → fallback dell'identità. +- Ambito: `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 ack sono attive. - Su Telegram, impostalo esplicitamente a `true` per abilitare le reazioni di stato del ciclo di vita. + Su Slack e Discord, se non impostato mantiene abilitate le reazioni di stato quando le reazioni di conferma sono attive. + Su Telegram, impostalo esplicitamente su `true` per abilitare le reazioni di stato del ciclo di vita. ### Debounce in ingresso -Raggruppa rapidi messaggi solo testuali dello stesso mittente in un unico turno agente. Media/allegati vengono scaricati immediatamente. I comandi di controllo bypassano il debounce. +Raggruppa i rapidi messaggi solo testo dallo stesso mittente in un unico turno dell'agente. Media/allegati forzano lo svuotamento immediato. I comandi di controllo bypassano il debouncing. ### TTS (sintesi vocale) @@ -1964,12 +1954,12 @@ Raggruppa rapidi messaggi solo testuali dello stesso mittente in un unico turno } ``` -- `auto` controlla la modalità auto-TTS predefinita: `off`, `always`, `inbound` o `tagged`. `/tts on|off` può fare override delle preferenze locali, e `/tts status` mostra lo stato effettivo. -- `summaryModel` sovrascrive `agents.defaults.model.primary` per il riepilogo automatico. -- `modelOverrides` è abilitato per default; `modelOverrides.allowProvider` ha come default `false` (opt-in). -- Le API key usano come fallback `ELEVENLABS_API_KEY`/`XI_API_KEY` e `OPENAI_API_KEY`. -- `openai.baseUrl` sovrascrive l'endpoint OpenAI TTS. 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 server TTS compatibile OpenAI e allenta la convalida model/voice. +- `auto` controlla la modalità predefinita di auto-TTS: `off`, `always`, `inbound` o `tagged`. `/tts on|off` può fare override delle preferenze locali e `/tts status` mostra lo stato effettivo. +- `summaryModel` override `agents.defaults.model.primary` per il riepilogo automatico. +- `modelOverrides` è abilitato per default; `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` override l'endpoint OpenAI TTS. 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. --- @@ -2000,50 +1990,50 @@ 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 chiavi Talk flat legacy (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) sono compatibilità-only e vengono auto-migrate in `talk.providers.`. -- Gli ID voice usano come fallback `ELEVENLABS_VOICE_ID` o `SAG_VOICE_ID`. +- Le chiavi Talk legacy flat (`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 API key Talk. -- `providers.*.voiceAliases` permette alle direttive Talk di usare nomi intuitivi. +- Il fallback `ELEVENLABS_API_KEY` si applica solo quando non è configurata alcuna chiave API Talk. +- `providers.*.voiceAliases` consente alle direttive Talk di usare nomi descrittivi. - `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`). --- ## Strumenti -### Profili strumenti +### Profili degli strumenti `tools.profile` imposta una allowlist di base prima di `tools.allow`/`tools.deny`: -L'onboarding locale imposta nelle nuove configurazioni locali `tools.profile: "coding"` quando assente (i profili espliciti esistenti vengono preservati). +L'onboarding locale imposta per default le nuove configurazioni locali su `tools.profile: "coding"` quando non è impostato (i profili espliciti esistenti vengono preservati). | Profilo | Include | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | solo `session_status` | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------ | +| `minimal` | solo `session_status` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | -| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | Nessuna restrizione (uguale a non impostato) | +| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | +| `full` | Nessuna restrizione (uguale a non impostato) | -### Gruppi strumenti +### 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 built-in (esclude i plugin provider) | ### `tools.allow` / `tools.deny` -Criterio globale di allow/deny per gli strumenti (deny vince). Case-insensitive, supporta wildcard `*`. Applicato anche quando il sandbox Docker è disattivato. +Criterio globale di allow/deny degli strumenti (vince il deny). Case-insensitive, supporta wildcard `*`. Applicato anche quando la sandbox Docker è disattivata. ```json5 { @@ -2069,7 +2059,7 @@ Restringe ulteriormente gli strumenti per provider o modelli specifici. Ordine: ### `tools.elevated` -Controlla l'accesso exec elevated fuori dal sandbox: +Controlla l'accesso exec elevated fuori dalla sandbox: ```json5 { @@ -2085,9 +2075,9 @@ Controlla l'accesso exec elevated fuori dal sandbox: } ``` -- L'override per-agente (`agents.list[].tools.elevated`) può solo restringere 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` elevated bypassa il sandboxing e usa il percorso di escape configurato (`gateway` per default, oppure `node` quando il target exec è `node`). +- `exec` elevated bypassa la sandbox e usa il percorso di escape configurato (`gateway` per default oppure `node` quando il target exec è `node`). ### `tools.exec` @@ -2111,8 +2101,8 @@ Controlla l'accesso exec elevated fuori dal sandbox: ### `tools.loopDetection` -I controlli di sicurezza sui loop di strumenti sono **disabilitati per default**. 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`. +I controlli di sicurezza del loop degli strumenti sono **disabilitati per default**. Imposta `enabled: true` per attivare il rilevamento. +Le impostazioni possono essere definite globalmente in `tools.loopDetection` e overrideate per agente in `agents.list[].tools.loopDetection`. ```json5 { @@ -2133,13 +2123,13 @@ Le impostazioni possono essere definite globalmente in `tools.loopDetection` e s } ``` -- `historySize`: cronologia massima delle chiamate tool conservata per l'analisi dei loop. -- `warningThreshold`: soglia del pattern ripetitivo senza progresso per gli avvisi. -- `criticalThreshold`: soglia ripetitiva più alta per bloccare loop critici. -- `globalCircuitBreakerThreshold`: soglia di arresto rigido per qualsiasi esecuzione senza progresso. -- `detectors.genericRepeat`: avvisa su chiamate ripetute stesso-tool/stessi-argomenti. -- `detectors.knownPollNoProgress`: avvisa/blocca sui noti tool di polling (`process.poll`, `command_status`, ecc.). -- `detectors.pingPong`: avvisa/blocca sui pattern alternati a coppie senza progresso. +- `historySize`: massima cronologia delle chiamate agli strumenti conservata per l'analisi dei loop. +- `warningThreshold`: soglia di pattern ripetuto 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 su chiamate ripetute allo stesso strumento/con gli stessi argomenti. +- `detectors.knownPollNoProgress`: avvisa/blocca sugli strumenti di polling noti (`process.poll`, `command_status`, ecc.). +- `detectors.pingPong`: avvisa/blocca sui pattern alternati a coppie senza avanzamento. - Se `warningThreshold >= criticalThreshold` o `criticalThreshold >= globalCircuitBreakerThreshold`, la convalida fallisce. ### `tools.web` @@ -2157,7 +2147,7 @@ Le impostazioni possono essere definite globalmente in `tools.loopDetection` e s }, fetch: { enabled: true, - provider: "firecrawl", // facoltativo; ometti per auto-detect + provider: "firecrawl", // facoltativo; omettilo per il rilevamento automatico maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2182,7 +2172,7 @@ Configura la comprensione dei media in ingresso (immagine/audio/video): media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: invia direttamente nel canale i task async music/video completati + directSend: false, // opt-in: invia direttamente al canale i contenuti music/video asincroni completati }, audio: { enabled: true, @@ -2206,32 +2196,32 @@ Configura la comprensione dei media in ingresso (immagine/audio/video): } ``` - + **Voce provider** (`type: "provider"` o omesso): - `provider`: ID provider API (`openai`, `anthropic`, `google`/`gemini`, `groq`, ecc.) -- `model`: override model id -- `profile` / `preferredProfile`: selezione profilo `auth-profiles.json` +- `model`: override dell'ID modello +- `profile` / `preferredProfile`: selezione del profilo `auth-profiles.json` **Voce CLI** (`type: "cli"`): -- `command`: eseguibile da eseguire -- `args`: argomenti template (supporta `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, ecc.) +- `command`: eseguibile da avviare +- `args`: argomenti con template (supporta `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, ecc.) **Campi comuni:** -- `capabilities`: lista facoltativa (`image`, `audio`, `video`). Default: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. -- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: override per-voce. -- I fallimenti passano alla voce successiva. +- `capabilities`: elenco facoltativo (`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, si passa alla voce successiva. -L'auth provider segue l'ordine standard: `auth-profiles.json` → variabili env → `models.providers.*.apiKey`. +L'autenticazione del provider segue l'ordine standard: `auth-profiles.json` → variabili env → `models.providers.*.apiKey`. -**Campi di completamento async:** +**Campi di completamento asincrono:** -- `asyncCompletion.directSend`: quando `true`, i task completati async `music_generate` - e `video_generate` provano prima la consegna diretta al canale. Default: `false` - (percorso legacy requester-session wake/model-delivery). +- `asyncCompletion.directSend`: quando `true`, le attività completate di `music_generate` + e `video_generate` provano prima la consegna diretta al canale. Predefinito: `false` + (percorso legacy di wake/consegna modello della sessione richiedente). @@ -2250,9 +2240,9 @@ L'auth provider segue l'ordine standard: `auth-profiles.json` → variabili env ### `tools.sessions` -Controlla quali sessioni possono essere bersaglio degli strumenti di sessione (`sessions_list`, `sessions_history`, `sessions_send`). +Controlla quali sessioni possono essere prese come target dagli strumenti di sessione (`sessions_list`, `sessions_history`, `sessions_send`). -Default: `tree` (sessione corrente + sessioni generate da essa, come i subagent). +Predefinito: `tree` (sessione corrente + sessioni generate da essa, come i subagenti). ```json5 { @@ -2268,14 +2258,14 @@ Default: `tree` (sessione corrente + sessioni generate da essa, come i subagent) 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). +- `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 con lo stesso ID agente). - `all`: qualsiasi sessione. Il targeting cross-agent richiede comunque `tools.agentToAgent`. -- Clamp sandbox: quando la sessione corrente è sandboxed e `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, la visibilità viene forzata a `tree` anche se `tools.sessions.visibility="all"`. +- 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` -Controlla il supporto agli allegati inline per `sessions_spawn`. +Controlla il supporto degli allegati inline per `sessions_spawn`. ```json5 { @@ -2286,7 +2276,7 @@ Controlla il supporto agli allegati inline per `sessions_spawn`. 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" }, }, }, @@ -2297,20 +2287,20 @@ Note: - Gli allegati sono supportati solo per `runtime: "subagent"`. Il runtime ACP li rifiuta. - I file vengono materializzati nella workspace figlia in `.openclaw/attachments//` con un `.manifest.json`. -- Il contenuto degli allegati viene automaticamente redatto dalla persistenza transcript. -- Gli input base64 vengono convalidati con controlli rigorosi su alfabeto/padding e una guardia di dimensione pre-decodifica. -- I permessi file sono `0700` per le directory e `0600` per i file. -- Il cleanup segue il criterio `cleanup`: `delete` rimuove sempre gli allegati; `keep` li conserva solo quando `retainOnSessionKeep: true`. +- Il contenuto degli allegati viene automaticamente redatto dalla persistenza del transcript. +- Gli input Base64 vengono convalidati con controlli rigorosi di alfabeto/padding e una protezione preventiva 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 per strumenti integrati. Default disattivato salvo quando si applica una regola di auto-enable specifica del runtime. +Flag sperimentali degli strumenti built-in. Disattivati per default a meno che non si applichi una regola di auto-abilitazione specifica del runtime. ```json5 { tools: { experimental: { - planTool: true, // abilita l'update_plan sperimentale + planTool: true, // abilita update_plan sperimentale }, }, } @@ -2318,9 +2308,9 @@ Flag sperimentali per strumenti integrati. Default disattivato salvo quando si a Note: -- `planTool`: abilita lo strumento strutturato `update_plan` per il tracciamento di lavori multi-step non banali. -- Default: `false` per i provider non OpenAI. Le esecuzioni OpenAI e OpenAI Codex lo auto-abilitano quando non impostato; imposta `false` per disabilitare questo auto-enable. -- Quando abilitato, il system prompt aggiunge anche linee guida d'uso così il modello lo usa solo per lavoro sostanziale e mantiene al massimo uno step `in_progress`. +- `planTool`: abilita lo strumento strutturato `update_plan` per il tracciamento del lavoro multi-step non banale. +- Predefinito: `false` per i provider non OpenAI. Le esecuzioni OpenAI e OpenAI Codex lo auto-abilitano quando non è impostato; imposta `false` per disabilitare questa auto-abilitazione. +- Quando è abilitato, il prompt di sistema aggiunge anche indicazioni d'uso in modo che il modello lo usi solo per lavori sostanziali e mantenga al massimo un solo passaggio `in_progress`. ### `agents.defaults.subagents` @@ -2340,21 +2330,21 @@ Note: } ``` -- `model`: modello predefinito per i sub-agenti generati. Se omesso, i sub-agenti ereditano il modello del chiamante. -- `allowAgents`: allowlist predefinita di ID agente target per `sessions_spawn` quando l'agente richiedente non imposta il proprio `subagents.allowAgents` (`["*"]` = qualunque; default: solo lo stesso agente). -- `runTimeoutSeconds`: timeout predefinito (secondi) per `sessions_spawn` quando la chiamata tool omette `runTimeoutSeconds`. `0` significa nessun timeout. -- Criterio tool per-subagent: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. +- `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 subagente: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- -## Provider personalizzati e base URL +## Provider personalizzati e URL base -OpenClaw usa il catalogo modelli integrato. Aggiungi provider personalizzati tramite `models.providers` in config o `~/.openclaw/agents//agent/models.json`. +OpenClaw usa il catalogo modelli built-in. Aggiungi provider personalizzati tramite `models.providers` nella configurazione o `~/.openclaw/agents//agent/models.json`. ```json5 { models: { - mode: "merge", // merge (default) | replace + mode: "merge", // merge (predefinito) | replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", @@ -2379,46 +2369,47 @@ OpenClaw usa il catalogo modelli integrato. Aggiungi provider personalizzati tra ``` - Usa `authHeader: true` + `headers` per esigenze di autenticazione personalizzate. -- Sovrascrivi la root config agente con `OPENCLAW_AGENT_DIR` (oppure `PI_CODING_AGENT_DIR`, alias legacy della variabile ambiente). -- Precedenza di unione per ID provider corrispondenti: - - I valori `baseUrl` non vuoti in `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 corrente config/auth-profile. - - I valori `apiKey` del provider gestiti da SecretRef vengono aggiornati dai marker sorgente (`ENV_VAR_NAME` per env ref, `secretref-managed` per ref file/exec) invece di persistere i segreti risolti. - - I valori header del provider gestiti da SecretRef vengono aggiornati dai marker sorgente (`secretref-env:ENV_VAR_NAME` per env ref, `secretref-managed` per ref file/exec). - - `apiKey`/`baseUrl` dell'agente vuoti o mancanti usano come fallback `models.providers` in config. - - I valori `contextWindow`/`maxTokens` del modello corrispondente usano il valore più alto tra config esplicita e valori impliciti del catalogo. - - Il valore `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 config riscriva completamente `models.json`. - - La persistenza dei marker è source-authoritative: i marker vengono scritti dallo snapshot attivo della configurazione sorgente (pre-risoluzione), non dai valori dei segreti risolti a runtime. +- Override della root della configurazione dell'agente con `OPENCLAW_AGENT_DIR` (o `PI_CODING_AGENT_DIR`, alias legacy della variabile d'ambiente). +- Precedenza di merge per ID provider corrispondenti: + - I valori `baseUrl` non vuoti di `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 corrente di configurazione/auth-profile. + - I valori `apiKey` del provider gestiti da SecretRef vengono aggiornati dai marker della sorgente (`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 della sorgente (`secretref-env:ENV_VAR_NAME` per i riferimenti env, `secretref-managed` per i riferimenti file/exec). + - `apiKey`/`baseUrl` dell'agente vuoti o mancanti ricadono su `models.providers` nella configurazione. + - I valori `contextWindow`/`maxTokens` dei modelli corrispondenti usano il valore più alto tra la configurazione esplicita e i valori impliciti del catalogo. + - I valori `contextTokens` dei modelli corrispondenti preservano un limite runtime esplicito quando presente; usalo per limitare il contesto effettivo senza modificare i metadati nativi del modello. + - Usa `models.mode: "replace"` quando vuoi che la configurazione riscriva completamente `models.json`. + - La persistenza dei marker è autorevole rispetto alla sorgente: i marker vengono scritti dallo snapshot di configurazione sorgente attivo (pre-risoluzione), non dai valori segreti risolti a runtime. -### Dettagli dei campi provider +### Dettagli dei campi del provider - `models.mode`: comportamento del catalogo provider (`merge` o `replace`). -- `models.providers`: mappa provider personalizzati indicizzati per ID provider. -- `models.providers.*.api`: adattatore di richiesta (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai`, ecc). -- `models.providers.*.apiKey`: credenziale provider (preferisci SecretRef/sostituzione env). -- `models.providers.*.auth`: strategia auth (`api-key`, `token`, `oauth`, `aws-sdk`). -- `models.providers.*.injectNumCtxForOpenAICompat`: per Ollama + `openai-completions`, inietta `options.num_ctx` nelle richieste (default: `true`). +- `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.*.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`, inietta `options.num_ctx` nelle richieste (predefinito: `true`). - `models.providers.*.authHeader`: forza il trasporto della credenziale nell'header `Authorization` quando richiesto. -- `models.providers.*.baseUrl`: URL base API upstream. -- `models.providers.*.headers`: header statici extra per proxy/tenant routing. -- `models.providers.*.request`: override di trasporto per richieste HTTP del model-provider. - - `request.headers`: header extra (fusi con i default provider). I valori accettano SecretRef. - - `request.auth`: override della strategia auth. Modalità: `"provider-default"` (usa l'auth integrata del provider), `"authorization-bearer"` (con `token`), `"header"` (con `headerName`, `value`, `prefix` facoltativo). +- `models.providers.*.baseUrl`: URL base dell'API upstream. +- `models.providers.*.headers`: header statici aggiuntivi per routing proxy/tenant. +- `models.providers.*.request`: override di trasporto per le richieste HTTP del provider di modelli. + - `request.headers`: header aggiuntivi (uniti ai valori predefiniti del provider). I valori accettano SecretRef. + - `request.auth`: override della strategia di autenticazione. Modalità: `"provider-default"` (usa l'autenticazione built-in del provider), `"authorization-bearer"` (con `token`), `"header"` (con `headerName`, `value`, `prefix` facoltativo). - `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` 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 risolve in intervalli privati, CGNAT o simili, tramite la protezione SSRF del fetch HTTP del provider (opt-in dell'operatore per endpoint OpenAI-compatibili self-hosted attendibili). WebSocket usa lo stesso `request` per header/TLS ma non quel gate SSRF del 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 runtime facoltativo del contesto. Usalo quando vuoi un budget di contesto effettivo più piccolo della `contextWindow` nativa del modello. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: hint di compatibilità facoltativo. Per `api: "openai-completions"` con `baseUrl` non vuoto e non nativo (host diverso da `api.openai.com`), OpenClaw lo forza a `false` a runtime. `baseUrl` vuoto/omesso mantiene il comportamento predefinito OpenAI. -- `models.providers.*.models.*.compat.requiresStringContent`: hint di compatibilità facoltativo per endpoint chat compatibili OpenAI che accettano solo stringhe. Quando `true`, OpenClaw appiattisce gli array `messages[].content` di puro testo in semplici stringhe prima di inviare la richiesta. -- `plugins.entries.amazon-bedrock.config.discovery`: radice impostazioni auto-discovery Bedrock. +- `models.providers.*.models.*.contextTokens`: limite di contesto runtime facoltativo. Usalo quando vuoi un budget di contesto effettivo più piccolo del `contextWindow` nativo del modello. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: suggerimento di compatibilità facoltativo. Per `api: "openai-completions"` con `baseUrl` non vuoto e non nativo (host diverso da `api.openai.com`), OpenClaw lo forza a `false` a runtime. `baseUrl` vuoto/omesso mantiene il comportamento OpenAI predefinito. +- `models.providers.*.models.*.compat.requiresStringContent`: suggerimento di compatibilità facoltativo 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 provider-id per discovery mirata. +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: filtro facoltativo per ID provider per una 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 modelli scoperti. -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: token massimi di output di fallback per modelli scoperti. +- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: finestra di contesto di fallback per i modelli rilevati. +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: massimo di token in output di fallback per i modelli rilevati. ### Esempi di provider @@ -2456,7 +2447,7 @@ OpenClaw usa il catalogo modelli integrato. Aggiungi provider personalizzati tra } ``` -Usa `cerebras/zai-glm-4.7` per Cerebras; `zai/glm-4.7` per Z.AI direct. +Usa `cerebras/zai-glm-4.7` per Cerebras; `zai/glm-4.7` per Z.AI diretto. @@ -2493,8 +2484,8 @@ Imposta `OPENCODE_API_KEY` (o `OPENCODE_ZEN_API_KEY`). Usa riferimenti `opencode Imposta `ZAI_API_KEY`. `z.ai/*` e `z-ai/*` sono alias accettati. Scorciatoia: `openclaw onboard --auth-choice zai-api-key`. - Endpoint generale: `https://api.z.ai/api/paas/v4` -- Endpoint coding (default): `https://api.z.ai/api/coding/paas/v4` -- Per l'endpoint generale, definisci un provider personalizzato con override del base URL. +- Endpoint coding (predefinito): `https://api.z.ai/api/coding/paas/v4` +- Per l'endpoint generale, definisci un provider personalizzato con l'override del base URL. @@ -2533,11 +2524,11 @@ Imposta `ZAI_API_KEY`. `z.ai/*` e `z-ai/*` sono alias accettati. Scorciatoia: `o } ``` -Per l'endpoint Cina: `baseUrl: "https://api.moonshot.cn/v1"` o `openclaw onboard --auth-choice moonshot-api-key-cn`. +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 streaming sul trasporto condiviso +Gli endpoint Moonshot nativi dichiarano la compatibilità con l'uso dello streaming sul trasporto condiviso `openai-completions`, e OpenClaw si basa sulle capacità dell'endpoint -piuttosto che sul solo provider id integrato. +più che solo sull'ID provider built-in. @@ -2555,11 +2546,11 @@ piuttosto che sul solo provider id integrato. } ``` -Compatibile Anthropic, provider integrato. Scorciatoia: `openclaw onboard --auth-choice kimi-code-api-key`. +Compatibile con Anthropic, provider built-in. Scorciatoia: `openclaw onboard --auth-choice kimi-code-api-key`. - + ```json5 { @@ -2598,7 +2589,7 @@ Il base URL deve omettere `/v1` (il client Anthropic lo aggiunge). Scorciatoia: - + ```json5 { @@ -2635,11 +2626,11 @@ Il base URL deve omettere `/v1` (il client Anthropic lo aggiunge). Scorciatoia: ``` Imposta `MINIMAX_API_KEY`. Scorciatoie: -`openclaw onboard --auth-choice minimax-global-api` o +`openclaw onboard --auth-choice minimax-global-api` oppure `openclaw onboard --auth-choice minimax-cn-api`. -Il catalogo modelli ha come default solo M2.7. -Sul percorso streaming compatibile Anthropic, OpenClaw disabilita il thinking MiniMax -per default a meno che tu non imposti esplicitamente `thinking`. `/fast on` o +Il catalogo modelli usa per default solo M2.7. +Nel percorso di streaming compatibile con Anthropic, OpenClaw disabilita per default 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`. @@ -2647,7 +2638,7 @@ per default a meno che tu non imposti esplicitamente `thinking`. `/fast on` o -Vedi [Local Models](/it/gateway/local-models). In breve: esegui un grande modello locale tramite LM Studio Responses API su hardware serio; mantieni i modelli hosted uniti come fallback. +Vedi [Modelli locali](/it/gateway/local-models). In breve: esegui un grande modello locale tramite LM Studio Responses API su hardware adeguato; mantieni uniti i modelli hosted per il fallback. @@ -2678,14 +2669,14 @@ Vedi [Local Models](/it/gateway/local-models). In breve: esegui un grande modell } ``` -- `allowBundled`: allowlist facoltativa solo per le bundled skills (le managed/workspace skills non sono influenzate). -- `load.extraDirs`: root skill condivise aggiuntive (precedenza più bassa). +- `allowBundled`: allowlist facoltativa solo per le Skills bundled (le Skills managed/workspace non sono interessate). +- `load.extraDirs`: root aggiuntive 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` + disponibile prima di ricadere su 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 skill anche se bundled/installata. -- `entries..apiKey`: campo di comodità per la API key a livello skill per skill che dichiarano una variabile env primaria (stringa in chiaro o oggetto SecretRef). +- `entries..enabled: false` disabilita una Skills anche se bundled/installata. +- `entries..apiKey`: opzione di comodità per le Skills che dichiarano una variabile env primaria (stringa in chiaro o oggetto SecretRef). --- @@ -2713,43 +2704,43 @@ 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 i bundle Claude senza manifest nel layout predefinito. +- Caricati da `~/.openclaw/extensions`, `/.openclaw/extensions` e `plugins.load.paths`. +- La discovery accetta plugin OpenClaw nativi più bundle Codex compatibili e bundle Claude, inclusi i bundle Claude con layout predefinito senza manifest. - **Le modifiche di configurazione richiedono un riavvio del gateway.** -- `allow`: allowlist facoltativa (si caricano solo i plugin elencati). `deny` vince. -- `plugins.entries..apiKey`: campo di comodità per la API key a livello plugin (quando supportato dal plugin). -- `plugins.entries..env`: mappa di variabili env scoped al 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 dei plugin nativi e alle directory hook fornite da bundle supportati. -- `plugins.entries..subagent.allowModelOverride`: fidati esplicitamente di questo plugin per richiedere override per-run di `provider` e `model` per esecuzioni in background di subagent. -- `plugins.entries..subagent.allowedModels`: allowlist facoltativa di target canonici `provider/model` per override trusted di subagent. Usa `"*"` solo quando vuoi intenzionalmente consentire qualsiasi modello. -- `plugins.entries..config`: oggetto di configurazione definito dal plugin (convalidato dallo schema nativo del plugin OpenClaw quando disponibile). -- `plugins.entries.firecrawl.config.webFetch`: impostazioni provider web-fetch Firecrawl. - - `apiKey`: API key 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 API Firecrawl (default: `https://api.firecrawl.dev`). - - `onlyMainContent`: estrae solo il contenuto principale dalle pagine (default: `true`). - - `maxAgeMs`: età massima della cache in millisecondi (default: `172800000` / 2 giorni). - - `timeoutSeconds`: timeout della richiesta scrape in secondi (default: `60`). -- `plugins.entries.xai.config.xSearch`: impostazioni xAI X Search (ricerca web Grok). +- `allow`: allowlist facoltativa (si caricano solo i plugin elencati). Vince `deny`. +- `plugins.entries..apiKey`: campo di comodità per la chiave API a livello plugin (quando supportato dal plugin). +- `plugins.entries..env`: mappa delle variabili env con ambito plugin. +- `plugins.entries..hooks.allowPromptInjection`: quando `false`, il core blocca `before_prompt_build` e ignora i campi che mutano il prompt dal legacy `before_agent_start`, preservando comunque i legacy `modelOverride` e `providerOverride`. Si applica agli hook dei plugin nativi e alle directory hook fornite dai bundle supportati. +- `plugins.entries..subagent.allowModelOverride`: si fida esplicitamente di questo plugin per richiedere override per-esecuzione di `provider` e `model` per le esecuzioni dei subagenti in background. +- `plugins.entries..subagent.allowedModels`: allowlist facoltativa di target canonici `provider/model` per override di subagenti attendibili. Usa `"*"` solo quando vuoi intenzionalmente 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 web-fetch. + - `apiKey`: chiave API Firecrawl (accetta SecretRef). Ricade su `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 di xAI X Search (ricerca web Grok). - `enabled`: abilita il provider X Search. - - `model`: modello Grok da usare per la ricerca (es. `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: impostazioni dreaming della memoria (sperimentale). Vedi [Dreaming](/it/concepts/dreaming) per fasi e soglie. - - `enabled`: interruttore master dreaming (default `false`). + - `model`: modello Grok da usare per la ricerca (ad esempio `"grok-4-1-fast"`). +- `plugins.entries.memory-core.config.dreaming`: impostazioni di memory dreaming (sperimentale). Vedi [Dreaming](/it/concepts/dreaming) per fasi e soglie. + - `enabled`: interruttore principale del dreaming (predefinito `false`). - `frequency`: cadenza cron per ogni sweep completo di dreaming (`"0 3 * * *"` per default). - - il criterio di fase e le soglie sono dettagli di implementazione (non chiavi di configurazione rivolte all'utente). -- La configurazione completa della memoria è in [Memory configuration reference](/it/reference/memory-config): + - Il criterio di fase e le soglie sono dettagli implementativi (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 default Pi incorporati da `settings.json`; OpenClaw li applica come impostazioni agente sanificate, non come patch grezze alla configurazione OpenClaw. -- `plugins.slots.memory`: scegli l'ID del plugin memoria attivo, o `"none"` per disabilitare i plugin memoria. -- `plugins.slots.contextEngine`: scegli l'ID del plugin motore di contesto attivo; ha come default `"legacy"` a meno che non installi e selezioni un altro engine. +- I plugin bundle Claude abilitati possono anche contribuire con valori predefiniti Pi incorporati da `settings.json`; OpenClaw li applica come impostazioni agente sanificate, non come patch di configurazione raw di 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 predefinito è `"legacy"` a meno che tu non installi e selezioni un altro motore. - `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. -Vedi [Plugins](/it/tools/plugin). +Vedi [Plugin](/it/tools/plugin). --- @@ -2762,7 +2753,7 @@ Vedi [Plugins](/it/tools/plugin). evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - dangerouslyAllowPrivateNetwork: true, // modalità predefinita trusted-network + dangerouslyAllowPrivateNetwork: true, // modalità trusted-network predefinita // allowPrivateNetwork: true, // alias legacy // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], @@ -2790,22 +2781,918 @@ Vedi [Plugins](/it/tools/plugin). ``` - `evaluateEnabled: false` disabilita `act:evaluate` e `wait --fn`. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` ha come default `true` quando non impostato (modello trusted-network). -- Imposta `ssrfPolicy.dangerouslyAllowPrivateNetwork: false` per una navigazione browser rigorosa solo pubblica. -- In modalità strict, gli endpoint profilo CDP remoti (`profiles.*.cdpUrl`) sono soggetti allo stesso blocco delle reti private durante i controlli di raggiungibilità/discovery. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` ha come predefinito `true` quando non è impostato (modello trusted-network). +- Imposta `ssrfPolicy.dangerouslyAllowPrivateNetwork: false` per una navigazione browser rigorosamente solo pubblica. +- 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.allowPrivateNetwork` resta supportato come alias legacy. -- In modalità strict, usa `ssrfPolicy.hostnameAllowlist` e `ssrfPolicy.allowedHostnames` per eccezioni esplicite. -- I profili remoti sono solo attach-only (start/stop/reset disabilitati). +- In modalità rigorosa, usa `ssrfPolicy.hostnameAllowlist` e `ssrfPolicy.allowedHostnames` per eccezioni esplicite. +- I profili remoti sono solo attach-only (avvio/arresto/reset disabilitati). - `profiles.*.cdpUrl` accetta `http://`, `https://`, `ws://` e `wss://`. Usa HTTP(S) quando vuoi che OpenClaw scopra `/json/version`; usa WS(S) - quando il provider ti fornisce un URL WebSocket DevTools diretto. + quando il provider ti fornisce un URL WebSocket diretto di DevTools. - 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` mantengono i limiti correnti del percorso Chrome MCP: - azioni guidate da snapshot/ref invece del targeting CSS selector, hook di upload a file singolo, - nessun override del timeout dialogo, nessun `wait --load networkidle`, e nessun - `responsebody`, export PDF, intercettazione download o azioni batch. +- I profili `existing-session` possono impostare `userDataDir` per prendere come target uno specifico + profilo di browser basato su Chromium come Brave o Edge. +- I profili `existing-session` mantengono gli attuali limiti di routing di Chrome MCP: + azioni basate su snapshot/riferimenti invece del targeting con selettori CSS, hook di upload + per un solo file, nessun override del timeout delle finestre di dialogo, nessun `wait --load networkidle` e nessun + `responsebody`, esportazione PDF, intercettazione download o azioni batch. - I profili locali gestiti `openclaw` assegnano automaticamente `cdpPort` e `cdpUrl`; imposta - `cdpUrl` esplicitamente solo per CDP remoto. -- Ordine di auto-detect: browser predefinito se basato su Chromium → Chrome → Brave → Edge → Chromium → Chrome \ No newline at end of file + `cdpUrl` esplicitamente solo per CDP remoti. +- 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 (ad esempio + `--disable-gpu`, dimensionamento finestra o flag di debug). + +--- + +## UI + +```json5 +{ + ui: { + seamColor: "#FF4500", + assistant: { + name: "OpenClaw", + avatar: "CB", // emoji, testo breve, URL immagine o URI data + }, + }, +} +``` + +- `seamColor`: colore d'accento per il chrome della UI dell'app nativa (tinta del fumetto in modalità Talk, ecc.). +- `assistant`: override dell'identità della Control UI. Ricade sull'identità dell'agente attivo. + +--- + +## Gateway + +```json5 +{ + gateway: { + mode: "local", // local | remote + port: 18789, + bind: "loopback", + auth: { + mode: "token", // none | token | password | trusted-proxy + token: "your-token", + // password: "your-password", // oppure OPENCLAW_GATEWAY_PASSWORD + // trustedProxy: { userHeader: "x-forwarded-user" }, // per mode=trusted-proxy; vedi /gateway/trusted-proxy-auth + allowTailscale: true, + rateLimit: { + maxAttempts: 10, + windowMs: 60000, + lockoutMs: 300000, + exemptLoopback: true, + }, + }, + tailscale: { + mode: "off", // off | serve | funnel + resetOnExit: false, + }, + controlUi: { + enabled: true, + basePath: "/openclaw", + // root: "dist/control-ui", + // allowedOrigins: ["https://control.example.com"], // richiesto per Control UI non loopback + // dangerouslyAllowHostHeaderOriginFallback: false, // modalità pericolosa di fallback origine basata sull'header Host + // allowInsecureAuth: false, + // dangerouslyDisableDeviceAuth: false, + }, + remote: { + url: "ws://gateway.tailnet:18789", + transport: "ssh", // ssh | direct + token: "your-token", + // password: "your-password", + }, + trustedProxies: ["10.0.0.1"], + // Facoltativo. Predefinito false. + allowRealIpFallback: false, + tools: { + // deny HTTP aggiuntivi per /tools/invoke + deny: ["browser"], + // Rimuove strumenti dalla deny list HTTP predefinita + allow: ["gateway"], + }, + push: { + apns: { + relay: { + baseUrl: "https://relay.example.com", + timeoutMs: 10000, + }, + }, + }, + }, +} +``` + + + +- `mode`: `local` (esegue il gateway) oppure `remote` (si connette a un gateway remoto). Il gateway rifiuta di avviarsi se non è `local`. +- `port`: singola porta multiplexed 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 legacy di bind**: usa i valori di 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 `loopback` predefinito 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 è irraggiungibile. 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 default. I bind non loopback richiedono l'autenticazione del gateway. In pratica 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 default. +- Se sono configurati sia `gateway.auth.token` sia `gateway.auth.password` (inclusi SecretRef), imposta esplicitamente `gateway.auth.mode` su `token` oppure `password`. L'avvio e i flussi di installazione/riparazione del servizio falliscono quando entrambi sono configurati e `mode` non è impostato. +- `gateway.auth.mode: "none"`: modalità esplicita senza autenticazione. Usala solo per configurazioni loopback locali attendibili; 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 [Autenticazione Trusted Proxy](/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 della Control UI/WebSocket (verificati tramite `tailscale whois`). Gli endpoint HTTP API **non** usano questa autenticazione tramite header Tailscale; seguono invece la normale modalità di autenticazione HTTP del gateway. Questo flusso senza token presuppone che l'host gateway sia attendibile. Il predefinito è `true` quando `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: limiter facoltativo per auth fallita. Si applica per IP client e per ambito di autenticazione (shared-secret e device-token vengono tracciati in modo indipendente). I tentativi bloccati restituiscono `429` + `Retry-After`. + - Nel percorso asincrono Tailscale Serve Control UI, i tentativi falliti per lo stesso `{scope, clientIp}` vengono serializzati prima della scrittura del fallimento. I tentativi concorrenti errati dello stesso client possono quindi far scattare il limiter sulla seconda richiesta invece di passare entrambi come semplici mismatch. + - `gateway.auth.rateLimit.exemptLoopback` ha come predefinito `true`; impostalo su `false` quando vuoi intenzionalmente limitare anche il traffico localhost (per configurazioni di test o deployment proxy rigorosi). +- I tentativi di autenticazione WS originati dal browser sono sempre limitati con l'esenzione loopback disabilitata (difesa in profondità contro brute force localhost basata su browser). +- Su loopback, quei lockout con origine browser sono isolati per valore `Origin` + normalizzato, quindi fallimenti ripetuti da un'origine localhost non bloccano automaticamente + un'altra origine. +- `tailscale.mode`: `serve` (solo tailnet, bind loopback) oppure `funnel` (pubblico, richiede auth). +- `controlUi.allowedOrigins`: allowlist esplicita delle origini browser per le connessioni Gateway WebSocket. Richiesta quando sono previsti client browser da origini non loopback. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: modalità pericolosa che abilita il fallback dell'origine basato su header Host per deployment che si affidano intenzionalmente al criterio di origine dell'header Host. +- `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 di rete privata attendibili; il predefinito resta solo loopback per il traffico in chiaro. +- `gateway.remote.token` / `.password` sono campi di credenziali del client remoto. Non configurano da soli l'autenticazione del gateway. +- `gateway.push.apns.relay.baseUrl`: URL base HTTPS per il relay APNs esterno usato dalle build iOS ufficiali/TestFlight dopo che pubblicano registrazioni relay-backed nel gateway. Questo URL deve corrispondere all'URL del relay compilato nella build iOS. +- `gateway.push.apns.relay.timeoutMs`: timeout in millisecondi per l'invio gateway-to-relay. Il predefinito è `10000`. +- Le registrazioni relay-backed vengono delegate a una specifica identità gateway. L'app iOS associata recupera `gateway.identity.get`, include quell'identità nella registrazione relay e inoltra al gateway un grant di invio con ambito 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 del relay sopra. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: via di fuga 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 dai riavvii del monitor di salute mantenendo attivo 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 ma non risolto, la risoluzione fallisce in modo fail-closed (nessun fallback remoto che mascheri il problema). +- `trustedProxies`: IP dei reverse proxy che terminano TLS o iniettano header del client inoltrato. Elenca solo proxy che controlli. Le voci loopback sono comunque valide per configurazioni di rilevamento proxy locale/stesso host (ad esempio Tailscale Serve o un reverse proxy locale), ma **non** rendono le richieste loopback idonee per `gateway.auth.mode: "trusted-proxy"`. +- `allowRealIpFallback`: quando `true`, il gateway accetta `X-Real-IP` se `X-Forwarded-For` è assente. Il predefinito è `false` per un 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. + + + +### Endpoint OpenAI-compatibili + +- Chat Completions: disabilitato per default. Abilitalo con `gateway.http.endpoints.chatCompletions.enabled: true`. +- Responses API: `gateway.http.endpoints.responses.enabled`. +- Hardening dell'input URL per 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: + - `gateway.http.securityHeaders.strictTransportSecurity` (impostalo solo per origini HTTPS che controlli; vedi [Autenticazione Trusted Proxy](/it/gateway/trusted-proxy-auth#tls-termination-and-hsts)) + +### Isolamento multi-instance + +Esegui più gateway su un unico host con porte e directory di stato uniche: + +```bash +OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ +OPENCLAW_STATE_DIR=~/.openclaw-a \ +openclaw gateway --port 19001 +``` + +Flag di comodità: `--dev` (usa `~/.openclaw-dev` + porta `19001`), `--profile ` (usa `~/.openclaw-`). + +Vedi [Gateway multipli](/it/gateway/multiple-gateways). + +### `gateway.tls` + +```json5 +{ + gateway: { + tls: { + enabled: false, + autoGenerate: false, + certPath: "/etc/openclaw/tls/server.crt", + keyPath: "/etc/openclaw/tls/server.key", + caPath: "/etc/openclaw/tls/ca-bundle.crt", + }, + }, +} +``` + +- `enabled`: abilita la terminazione TLS sul listener del gateway (HTTPS/WSS) (predefinito: `false`). +- `autoGenerate`: genera automaticamente una coppia locale di certificato/chiave self-signed quando i file espliciti non sono configurati; solo per uso locale/dev. +- `certPath`: percorso filesystem del file di certificato TLS. +- `keyPath`: percorso filesystem del file della chiave privata TLS; mantienilo con permessi limitati. +- `caPath`: percorso facoltativo del bundle CA per la verifica client o catene di trust personalizzate. + +### `gateway.reload` + +```json5 +{ + gateway: { + reload: { + mode: "hybrid", // off | restart | hot | hybrid + debounceMs: 500, + deferralTimeoutMs: 300000, + }, + }, +} +``` + +- `mode`: controlla come le modifiche di configurazione vengono applicate a runtime. + - `"off"`: ignora le modifiche live; i cambiamenti richiedono un riavvio esplicito. + - `"restart"`: riavvia sempre il processo del gateway in caso di modifica della configurazione. + - `"hot"`: applica le modifiche in-process senza riavvio. + - `"hybrid"` (predefinito): prova prima il reload a caldo; ricade sul riavvio se necessario. +- `debounceMs`: finestra di debounce in ms prima che le modifiche di configurazione vengano applicate (intero non negativo). +- `deferralTimeoutMs`: tempo massimo in ms di attesa delle operazioni in corso prima di forzare un riavvio (predefinito: `300000` = 5 minuti). + +--- + +## Hook + +```json5 +{ + hooks: { + enabled: true, + token: "shared-secret", + path: "/hooks", + maxBodyBytes: 262144, + defaultSessionKey: "hook:ingress", + allowRequestSessionKey: false, + allowedSessionKeyPrefixes: ["hook:"], + allowedAgentIds: ["hooks", "main"], + presets: ["gmail"], + transformsDir: "~/.openclaw/hooks/transforms", + mappings: [ + { + match: { path: "gmail" }, + action: "agent", + agentId: "hooks", + wakeMode: "now", + name: "Gmail", + sessionKey: "hook:gmail:{{messages[0].id}}", + messageTemplate: "Da: {{messages[0].from}}\nOggetto: {{messages[0].subject}}\n{{messages[0].snippet}}", + deliver: true, + channel: "last", + model: "openai/gpt-5.4-mini", + }, + ], + }, +} +``` + +Auth: `Authorization: Bearer ` oppure `x-openclaw-token: `. +I token 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`; riutilizzare il token del Gateway viene rifiutato. +- `hooks.path` non può essere `/`; usa un sottopercorso dedicato come `/hooks`. +- Se `hooks.allowRequestSessionKey=true`, limita `hooks.allowedSessionKeyPrefixes` (ad esempio `["hook:"]`). + +**Endpoint:** + +- `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` +- `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` + - `sessionKey` dal payload della richiesta viene accettato solo quando `hooks.allowRequestSessionKey=true` (predefinito: `false`). +- `POST /hooks/` → risolto tramite `hooks.mappings` + + + +- `match.path` corrisponde al sottopercorso dopo `/hooks` (ad esempio `/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 dentro `hooks.transformsDir` (i percorsi assoluti e il traversal vengono rifiutati). +- `agentId` instrada verso un agente specifico; gli ID sconosciuti ricadono sul predefinito. +- `allowedAgentIds`: limita il routing esplicito (`*` o omesso = consenti tutto, `[]` = nega tutto). +- `defaultSessionKey`: chiave di sessione fissa facoltativa 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 i valori espliciti di `sessionKey` (richiesta + mapping), ad esempio `["hook:"]`. +- `deliver: true` invia la risposta finale a un canale; `channel` ha come predefinito `last`. +- `model` override l'LLM per questa esecuzione hook (deve essere consentito se è impostato il catalogo modelli). + + + +### Integrazione Gmail + +```json5 +{ + hooks: { + gmail: { + account: "openclaw@gmail.com", + topic: "projects//topics/gog-gmail-watch", + subscription: "gog-gmail-watch-push", + pushToken: "shared-push-token", + hookUrl: "http://127.0.0.1:18789/hooks/gmail", + includeBody: true, + maxBytes: 20000, + renewEveryMinutes: 720, + serve: { bind: "127.0.0.1", port: 8788, path: "/" }, + tailscale: { mode: "funnel", path: "/gmail-pubsub" }, + model: "openrouter/meta-llama/llama-3.3-70b-instruct:free", + thinking: "off", + }, + }, +} +``` + +- 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 + +```json5 +{ + canvasHost: { + root: "~/.openclaw/workspace/canvas", + liveReload: true, + // enabled: false, // oppure OPENCLAW_SKIP_CANVAS_HOST=1 + }, +} +``` + +- 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 del Gateway (token/password/trusted-proxy), come le altre superfici HTTP del Gateway. +- I Node WebView in genere non inviano header di autenticazione; dopo che un node è paired e connesso, il Gateway pubblicizza URL di capability con ambito node per l'accesso canvas/A2UI. +- Gli URL di 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 in `/__openclaw__/a2ui/`. +- Le modifiche richiedono un riavvio del gateway. +- Disabilita il live reload per directory grandi o in caso di errori `EMFILE`. + +--- + +## Discovery + +### mDNS (Bonjour) + +```json5 +{ + discovery: { + mdns: { + mode: "minimal", // minimal | full | off + }, + }, +} +``` + +- `minimal` (predefinito): omette `cliPath` + `sshPort` dai record TXT. +- `full`: include `cliPath` + `sshPort`. +- L'hostname ha come predefinito `openclaw`. Override con `OPENCLAW_MDNS_HOSTNAME`. + +### Wide-area (DNS-SD) + +```json5 +{ + discovery: { + wideArea: { enabled: true }, + }, +} +``` + +Scrive una zona DNS-SD unicast sotto `~/.openclaw/dns/`. Per la discovery cross-network, abbinala a un server DNS (consigliato CoreDNS) + split DNS Tailscale. + +Configurazione: `openclaw dns setup --apply`. + +--- + +## Ambiente + +### `env` (variabili env inline) + +```json5 +{ + env: { + OPENROUTER_API_KEY: "sk-or-...", + vars: { + GROQ_API_KEY: "gsk-...", + }, + shellEnv: { + enabled: true, + timeoutMs: 15000, + }, + }, +} +``` + +- 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 override le variabili esistenti). +- `shellEnv`: importa le chiavi mancanti attese dal profilo della tua shell di login. +- Vedi [Ambiente](/it/help/environment) per la precedenza completa. + +### Sostituzione di variabili env + +Riferisci variabili env in qualsiasi stringa di configurazione con `${VAR_NAME}`: + +```json5 +{ + gateway: { + auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" }, + }, +} +``` + +- Corrispondono solo 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`. + +--- + +## Segreti + +I SecretRef sono additivi: i valori in chiaro continuano a funzionare. + +### `SecretRef` + +Usa una sola forma oggetto: + +```json5 +{ source: "env" | "file" | "exec", provider: "default", id: "..." } +``` + +Convalida: + +- pattern di `provider`: `^[a-z][a-z0-9_-]{0,63}$` +- pattern di id per `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` +- `source: "file"` id: puntatore JSON assoluto (ad esempio `"/providers/openai/apiKey"`) +- pattern di id per `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` +- Gli id `source: "exec"` non devono contenere segmenti di percorso slash-delimited `.` o `..` (ad esempio `a/../b` viene rifiutato) + +### Superficie delle credenziali supportata + +- Matrice canonica: [Superficie credenziali SecretRef](/it/reference/secretref-credential-surface) +- `secrets apply` prende come target i percorsi delle credenziali supportati in `openclaw.json`. +- I riferimenti `auth-profiles.json` sono inclusi nella risoluzione runtime e nella copertura di audit. + +### Configurazione dei provider di segreti + +```json5 +{ + secrets: { + providers: { + default: { source: "env" }, // provider env esplicito facoltativo + filemain: { + source: "file", + path: "~/.openclaw/secrets.json", + mode: "json", + timeoutMs: 5000, + }, + vault: { + source: "exec", + command: "/usr/local/bin/openclaw-vault-resolver", + passEnv: ["PATH", "VAULT_ADDR"], + }, + }, + defaults: { + env: "default", + file: "filemain", + exec: "vault", + }, + }, +} +``` + +Note: + +- Il provider `file` supporta `mode: "json"` e `mode: "singleValue"` (`id` deve essere `"value"` in modalità singleValue). +- Il provider `exec` richiede un `command` assoluto e usa payload di protocollo su stdin/stdout. +- Per default, i percorsi comando symlink vengono rifiutati. Imposta `allowSymlinkCommand: true` per consentire percorsi symlink con validazione del percorso target risolto. +- Se `trustedDirs` è configurato, il controllo delle directory attendibili si applica al percorso target risolto. +- L'ambiente del processo figlio `exec` è minimo per default; passa esplicitamente le variabili richieste 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. +- Il filtraggio della superficie attiva si applica durante l'attivazione: i riferimenti non risolti su superfici abilitate fanno fallire startup/reload, mentre le superfici inattive vengono saltate con diagnostica. + +--- + +## Archiviazione auth + +```json5 +{ + auth: { + profiles: { + "anthropic:default": { provider: "anthropic", mode: "api_key" }, + "anthropic:work": { provider: "anthropic", mode: "api_key" }, + "openai-codex:personal": { provider: "openai-codex", mode: "oauth" }, + }, + order: { + anthropic: ["anthropic:default", "anthropic:work"], + "openai-codex": ["openai-codex:personal"], + }, + }, +} +``` + +- I profili per agente sono 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 di auth-profile supportate da SecretRef. +- Le credenziali runtime statiche provengono da snapshot risolti in memoria; le voci statiche legacy in `auth.json` vengono ripulite quando rilevate. +- Import legacy OAuth da `~/.openclaw/credentials/oauth.json`. +- Vedi [OAuth](/it/concepts/oauth). +- Comportamento runtime dei segreti e strumenti `audit/configure/apply`: [Gestione dei segreti](/it/gateway/secrets). + +### `auth.cooldowns` + +```json5 +{ + auth: { + cooldowns: { + billingBackoffHours: 5, + billingBackoffHoursByProvider: { anthropic: 3, openai: 8 }, + billingMaxHours: 24, + authPermanentBackoffMinutes: 10, + authPermanentMaxMinutes: 60, + failureWindowHours: 24, + overloadedProfileRotations: 1, + overloadedBackoffMs: 0, + rateLimitedProfileRotations: 1, + }, + }, +} +``` + +- `billingBackoffHours`: backoff base in ore quando un profilo fallisce per veri + errori di fatturazione/credito insufficiente (predefinito: `5`). Un testo esplicito di fatturazione può + comunque arrivare 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 retryable HTTP `402` relativi a usage-window o + limiti di spesa di organizzazione/workspace restano invece nel percorso `rate_limit`. +- `billingBackoffHoursByProvider`: override facoltativi per provider per le ore di billing backoff. +- `billingMaxHours`: limite in ore per la crescita esponenziale del billing backoff (predefinito: `24`). +- `authPermanentBackoffMinutes`: backoff base in minuti per fallimenti `auth_permanent` ad alta confidenza (predefinito: `10`). +- `authPermanentMaxMinutes`: limite 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 auth-profile del provider per errori di sovraccarico prima di passare al fallback del modello (predefinito: `1`). Le forme provider-busy come `ModelNotReadyException` finiscono qui. +- `overloadedBackoffMs`: ritardo fisso prima di riprovare una rotazione di provider/profilo sovraccarico (predefinito: `0`). +- `rateLimitedProfileRotations`: massimo numero di rotazioni dello stesso auth-profile del provider per errori di rate-limit prima di passare al fallback del modello (predefinito: `1`). Quel bucket `rate_limit` include testo tipico del provider come `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` e `resource exhausted`. + +--- + +## Logging + +```json5 +{ + logging: { + level: "info", + file: "/tmp/openclaw/openclaw.log", + consoleLevel: "info", + consoleStyle: "pretty", // pretty | compact | json + redactSensitive: "tools", // off | tools + redactPatterns: ["\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1"], + }, +} +``` + +- 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 la rotazione esterna dei log per i deployment di produzione. + +--- + +## Diagnostica + +```json5 +{ + diagnostics: { + enabled: true, + flags: ["telegram.*"], + stuckSessionWarnMs: 30000, + + otel: { + enabled: false, + endpoint: "https://otel-collector.example.com:4318", + protocol: "http/protobuf", // http/protobuf | grpc + headers: { "x-tenant-id": "my-org" }, + serviceName: "openclaw-gateway", + traces: true, + metrics: true, + logs: false, + sampleRate: 1.0, + flushIntervalMs: 5000, + }, + + cacheTrace: { + enabled: false, + filePath: "~/.openclaw/logs/cache-trace.jsonl", + includeMessages: true, + includePrompt: true, + includeSystem: true, + }, + }, +} +``` + +- `enabled`: interruttore principale per l'output di instrumentazione (predefinito: `true`). +- `flags`: array di stringhe flag che abilitano output di log mirati (supporta wildcard come `"telegram.*"` o `"*"`). +- `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) oppure `"grpc"`. +- `otel.headers`: header di metadati HTTP/gRPC aggiuntivi inviati con le richieste di esportazione OTel. +- `otel.serviceName`: nome del servizio per gli attributi della risorsa. +- `otel.traces` / `otel.metrics` / `otel.logs`: abilitano l'esportazione di trace, metriche o log. +- `otel.sampleRate`: frequenza di campionamento delle trace `0`–`1`. +- `otel.flushIntervalMs`: intervallo periodico di flush della telemetria in ms. +- `cacheTrace.enabled`: registra snapshot di cache trace per le esecuzioni incorporate (predefinito: `false`). +- `cacheTrace.filePath`: percorso di output per il JSONL di cache trace (predefinito: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: controllano cosa viene incluso nell'output di cache trace (tutti predefiniti: `true`). + +--- + +## Update + +```json5 +{ + update: { + channel: "stable", // stable | beta | dev + checkOnStart: true, + + auto: { + enabled: false, + stableDelayHours: 6, + stableJitterHours: 12, + betaCheckIntervalHours: 1, + }, + }, +} +``` + +- `channel`: canale di rilascio per installazioni npm/git — `"stable"`, `"beta"` o `"dev"`. +- `checkOnStart`: controlla gli aggiornamenti npm all'avvio del gateway (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`; massimo: `168`). +- `auto.stableJitterHours`: finestra aggiuntiva di distribuzione graduale sul canale stable in ore (predefinito: `12`; massimo: `168`). +- `auto.betaCheckIntervalHours`: frequenza in ore dei controlli sul canale beta (predefinito: `1`; massimo: `24`). + +--- + +## ACP + +```json5 +{ + acp: { + enabled: false, + dispatch: { enabled: true }, + backend: "acpx", + defaultAgent: "main", + allowedAgents: ["main", "ops"], + maxConcurrentSessions: 10, + + stream: { + coalesceIdleMs: 50, + maxChunkChars: 1000, + repeatSuppression: true, + deliveryMode: "live", // live | final_only + hiddenBoundarySeparator: "paragraph", // none | space | newline | paragraph + maxOutputChars: 50000, + maxSessionUpdateChars: 500, + }, + + runtime: { + ttlMinutes: 30, + }, + }, +} +``` + +- `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 bloccando l'esecuzione. +- `backend`: ID backend runtime ACP predefinito (deve corrispondere a un plugin runtime ACP registrato). +- `defaultAgent`: ID agente target ACP di fallback quando gli spawn non specificano un target esplicito. +- `allowedAgents`: allowlist degli 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 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 le righe di stato/strumento ripetute per turno (predefinito: `true`). +- `stream.deliveryMode`: `"live"` esegue 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`: massimo numero di caratteri di output dell'assistente proiettati per turno ACP. +- `stream.maxSessionUpdateChars`: massimo numero di caratteri per le righe proiettate di stato/aggiornamento ACP. +- `stream.tagVisibility`: record dei nomi dei tag verso 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 facoltativo da eseguire durante il bootstrap di un ambiente runtime ACP. + +--- + +## CLI + +```json5 +{ + cli: { + banner: { + taglineMode: "off", // random | default | off + }, + }, +} +``` + +- `cli.banner.taglineMode` controlla lo stile del tagline del banner: + - `"random"` (predefinito): tagline a rotazione, divertenti/stagionali. + - `"default"`: tagline neutro fisso (`Tutte le tue chat, un solo OpenClaw.`). + - `"off"`: nessun testo tagline (restano comunque mostrati titolo/versione del banner). +- Per nascondere l'intero banner (non solo i tagline), imposta la variabile env `OPENCLAW_HIDE_BANNER=1`. + +--- + +## Wizard + +Metadati scritti dai flussi guidati della CLI (`onboard`, `configure`, `doctor`): + +```json5 +{ + wizard: { + lastRunAt: "2026-01-01T00:00:00.000Z", + lastRunVersion: "2026.1.4", + lastRunCommit: "abc1234", + lastRunCommand: "configure", + lastRunMode: "local", + }, +} +``` + +--- + +## Identity + +Vedi i campi identity di `agents.list` in [Valori predefiniti degli agenti](#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). + + + +```json +{ + "bridge": { + "enabled": true, + "port": 18790, + "bind": "tailnet", + "tls": { + "enabled": true, + "autoGenerate": true + } + } +} +``` + + + +--- + +## Cron + +```json5 +{ + cron: { + enabled: true, + maxConcurrentRuns: 2, + webhook: "https://example.invalid/legacy", // fallback deprecato per i job memorizzati con notify:true + webhookToken: "replace-with-dedicated-token", // bearer token facoltativo per l'auth webhook in uscita + sessionRetention: "24h", // stringa durata o false + runLog: { + maxBytes: "2mb", // predefinito 2_000_000 byte + keepLines: 2000, // predefinito 2000 + }, + }, +} +``` + +- `sessionRetention`: per quanto tempo mantenere le sessioni complete delle esecuzioni cron isolate prima della pulizia da `sessions.json`. Controlla anche la pulizia dei transcript cron archiviati ed eliminati. 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`: bearer token usato per la consegna POST del webhook cron (`delivery.mode = "webhook"`); se omesso non viene inviato alcun header auth. +- `webhook`: URL webhook fallback legacy deprecato (http/https) usato solo per i job memorizzati che hanno ancora `notify: true`. + +### `cron.retry` + +```json5 +{ + cron: { + retry: { + maxAttempts: 3, + backoffMs: [30000, 60000, 300000], + retryOn: ["rate_limit", "overloaded", "network", "timeout", "server_error"], + }, + }, +} +``` + +- `maxAttempts`: massimo numero 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"`. Omettilo per riprovare tutti i tipi transitori. + +Si applica solo ai job cron one-shot. I job ricorrenti usano una gestione separata dei fallimenti. + +### `cron.failureAlert` + +```json5 +{ + cron: { + failureAlert: { + enabled: false, + after: 3, + cooldownMs: 3600000, + mode: "announce", + accountId: "main", + }, + }, +} +``` + +- `enabled`: abilita gli avvisi di errore per i job cron (predefinito: `false`). +- `after`: numero di fallimenti consecutivi prima che venga emesso 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`: account o ID canale facoltativo per limitare l'ambito della consegna dell'avviso. + +### `cron.failureDestination` + +```json5 +{ + cron: { + failureDestination: { + mode: "announce", + channel: "last", + to: "channel:C1234567890", + accountId: "main", + }, + }, +} +``` + +- Destinazione predefinita per le notifiche di errore cron in tutti i job. +- `mode`: `"announce"` oppure `"webhook"`; usa come predefinito `"announce"` quando esistono dati target sufficienti. +- `channel`: override del canale per la consegna announce. `"last"` riutilizza l'ultimo canale di consegna noto. +- `to`: target announce esplicito o URL webhook. Obbligatorio per la modalità webhook. +- `accountId`: override facoltativo dell'account per la consegna. +- `delivery.failureDestination` per job override questo valore predefinito globale. +- Quando non è impostata né una destinazione di errore globale né una per job, i job che già consegnano tramite `announce` ricadono su quel target announce primario in caso di errore. +- `delivery.failureDestination` è supportato solo per i job `sessionTarget="isolated"` a meno che `delivery.mode` primario del job non sia `"webhook"`. + +Vedi [Job Cron](/it/automation/cron-jobs). Le esecuzioni cron isolate sono tracciate come [attività in background](/it/automation/tasks). + +--- + +## Variabili template del modello media + +Placeholder template espansi in `tools.media.models[].args`: + +| Variabile | Descrizione | +| ------------------ | ------------------------------------------------- | +| `{{Body}}` | Corpo completo del messaggio in ingresso | +| `{{RawBody}}` | Corpo raw (senza wrapper di cronologia/mittente) | +| `{{BodyStripped}}` | Corpo con le mention 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: + +```json5 +// ~/.openclaw/openclaw.json +{ + gateway: { port: 18789 }, + agents: { $include: "./agents.json5" }, + broadcast: { + $include: ["./clients/mueller.json5", "./clients/schmidt.json5"], + }, +} +``` + +**Comportamento di merge:** + +- File singolo: sostituisce l'oggetto contenitore. +- Array di file: deep-merge in ordine (i successivi overrideano i precedenti). +- Chiavi sibling: unite dopo le include (overrideano i valori inclusi). +- Include annidate: 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 comunque si risolvono all'interno di quel confine. +- Errori: messaggi chiari per file mancanti, errori di parsing e include circolari. + +--- + +_Correlati: [Configurazione](/it/gateway/configuration) · [Esempi di configurazione](/it/gateway/configuration-examples) · [Doctor](/it/gateway/doctor)_ diff --git a/docs/it/gateway/protocol.md b/docs/it/gateway/protocol.md index 26b4ad546..f80263058 100644 --- a/docs/it/gateway/protocol.md +++ b/docs/it/gateway/protocol.md @@ -1,32 +1,32 @@ --- read_when: - - Implementazione o aggiornamento di client WS del gateway - - Debug di mismatch del protocollo o errori di connessione - - Rigenerazione di schema/modelli del protocollo -summary: 'Protocollo WebSocket del gateway: handshake, frame, versioning' -title: Protocollo del gateway + - Implementazione o aggiornamento dei client WS del gateway + - Debug del protocollo non corrispondente o degli errori di connessione + - Rigenerazione dello schema/dei modelli del protocollo +summary: 'Protocollo WebSocket del Gateway: handshake, frame, versioning' +title: Protocollo del Gateway x-i18n: - generated_at: "2026-04-08T02:15:55Z" + generated_at: "2026-04-10T08:14:12Z" model: gpt-5.4 provider: openai - source_hash: 8635e3ac1dd311dbd3a770b088868aa1495a8d53b3ebc1eae0dfda3b2bf4694a + source_hash: 83c820c46d4803d571c770468fd6782619eaa1dca253e156e8087dec735c127f source_path: gateway/protocol.md workflow: 15 --- # Protocollo del gateway (WebSocket) -Il protocollo WS del gateway è il **singolo control plane + trasporto dei nodi** per -OpenClaw. Tutti i client (CLI, interfaccia web, app macOS, nodi iOS/Android, nodi -headless) si connettono tramite WebSocket e dichiarano il proprio **ruolo** + **ambito** al -momento dell'handshake. +Il protocollo WS del Gateway è il **singolo control plane + trasporto dei nodi** per +OpenClaw. Tutti i client (CLI, interfaccia web, app macOS, nodi iOS/Android, +nodi headless) si connettono tramite WebSocket e dichiarano il proprio **ruolo** + **ambito** +al momento dell'handshake. ## Trasporto - WebSocket, frame di testo con payload JSON. - Il primo frame **deve** essere una richiesta `connect`. -## Handshake (connect) +## Handshake (`connect`) Gateway → Client (challenge pre-connessione): @@ -96,7 +96,7 @@ Quando viene emesso un token del dispositivo, `hello-ok` include anche: } ``` -Durante il passaggio di bootstrap attendibile, `hello-ok.auth` può includere anche voci di ruolo aggiuntive limitate in `deviceTokens`: +Durante il passaggio affidabile del bootstrap, `hello-ok.auth` può anche includere voci di ruolo aggiuntive limitate in `deviceTokens`: ```json { @@ -115,14 +115,12 @@ Durante il passaggio di bootstrap attendibile, `hello-ok.auth` può includere an } ``` -Per il flusso di bootstrap integrato node/operator, il token primario del nodo resta -`scopes: []` e qualsiasi token operator passato resta limitato all'allowlist dell'operatore di bootstrap -(`operator.approvals`, `operator.read`, -`operator.talk.secrets`, `operator.write`). I controlli dell'ambito di bootstrap restano -con prefisso del ruolo: le voci operator soddisfano solo richieste operator, e i ruoli non-operator -continuano a richiedere ambiti sotto il proprio prefisso di ruolo. +Per il flusso di bootstrap integrato nodo/operatore, il token principale del nodo rimane +`scopes: []` e qualsiasi token operatore passato rimane limitato alla allowlist dell'operatore di bootstrap (`operator.approvals`, `operator.read`, +`operator.talk.secrets`, `operator.write`). I controlli degli ambiti di bootstrap restano con prefisso del ruolo: le voci operatore soddisfano solo richieste operatore, e i ruoli non operatore +richiedono comunque ambiti con il prefisso del proprio ruolo. -### Esempio node +### Esempio di nodo ```json { @@ -159,9 +157,9 @@ continuano a richiedere ambiti sotto il proprio prefisso di ruolo. ## Framing -- **Request**: `{type:"req", id, method, params}` -- **Response**: `{type:"res", id, ok, payload|error}` -- **Event**: `{type:"event", event, payload, seq?, stateVersion?}` +- **Richiesta**: `{type:"req", id, method, params}` +- **Risposta**: `{type:"res", id, ok, payload|error}` +- **Evento**: `{type:"event", event, payload, seq?, stateVersion?}` I metodi con effetti collaterali richiedono **chiavi di idempotenza** (vedi schema). @@ -170,9 +168,9 @@ I metodi con effetti collaterali richiedono **chiavi di idempotenza** (vedi sche ### Ruoli - `operator` = client del control plane (CLI/UI/automazione). -- `node` = host di capacità (camera/screen/canvas/system.run). +- `node` = host delle capacità (camera/screen/canvas/system.run). -### Ambiti (operator) +### Ambiti (`operator`) Ambiti comuni: @@ -186,129 +184,128 @@ Ambiti comuni: `talk.config` con `includeSecrets: true` richiede `operator.talk.secrets` (o `operator.admin`). -I metodi RPC del gateway registrati dai plugin possono richiedere il proprio ambito operator, ma -i prefissi admin core riservati (`config.*`, `exec.approvals.*`, `wizard.*`, +I metodi RPC del gateway registrati dai plugin possono richiedere il proprio ambito operatore, ma +i prefissi amministrativi core riservati (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) vengono sempre risolti in `operator.admin`. -L'ambito del metodo è solo il primo gate. Alcuni slash command raggiunti tramite -`chat.send` applicano controlli a livello di comando più restrittivi in aggiunta. Per esempio, le scritture persistenti +L'ambito del metodo è solo il primo controllo. Alcuni slash command raggiunti tramite +`chat.send` applicano controlli più rigorosi a livello di comando. Ad esempio, le scritture persistenti `/config set` e `/config unset` richiedono `operator.admin`. -`node.pair.approve` ha anche un controllo aggiuntivo dell'ambito al momento dell'approvazione oltre al -metodo base: +`node.pair.approve` ha anche un controllo aggiuntivo dell'ambito al momento dell'approvazione oltre all'ambito base del metodo: -- richieste senza comando: `operator.pairing` -- richieste con comandi del nodo non-exec: `operator.pairing` + `operator.write` +- richieste senza comandi: `operator.pairing` +- richieste con comandi del nodo non `exec`: `operator.pairing` + `operator.write` - richieste che includono `system.run`, `system.run.prepare` o `system.which`: `operator.pairing` + `operator.admin` -### Caps/commands/permissions (node) +### `caps`/`commands`/`permissions` (`node`) -I nodi dichiarano le proprie capability claim al momento della connessione: +I nodi dichiarano le capacità richieste al momento della connessione: - `caps`: categorie di capacità di alto livello. -- `commands`: allowlist dei comandi per invoke. -- `permissions`: toggle granulari (ad esempio `screen.record`, `camera.capture`). +- `commands`: allowlist dei comandi per `invoke`. +- `permissions`: interruttori granulari (ad esempio `screen.record`, `camera.capture`). -Il gateway tratta questi elementi come **claim** e applica allowlist lato server. +Il Gateway tratta questi elementi come **dichiarazioni** e applica allowlist lato server. -## Presence +## Presenza - `system-presence` restituisce voci indicizzate per identità del dispositivo. -- Le voci di presence includono `deviceId`, `roles` e `scopes` così le UI possono mostrare una singola riga per dispositivo +- Le voci di presenza includono `deviceId`, `roles` e `scopes` così che le UI possano mostrare una singola riga per dispositivo anche quando si connette sia come **operator** sia come **node**. ## Famiglie comuni di metodi RPC Questa pagina non è un dump completo generato, ma la superficie WS pubblica è più ampia degli esempi di handshake/auth sopra. Queste sono le principali famiglie di metodi che il -gateway espone oggi. +Gateway espone oggi. -`hello-ok.features.methods` è un elenco conservativo di discovery costruito da -`src/gateway/server-methods-list.ts` più le esportazioni dei metodi plugin/channel caricati. -Trattalo come discovery delle funzionalità, non come un dump generato di ogni helper invocabile +`hello-ok.features.methods` è un elenco di discovery conservativo costruito da +`src/gateway/server-methods-list.ts` più le esportazioni dei metodi di plugin/canali caricati. +Trattalo come feature discovery, non come un dump generato di ogni helper invocabile implementato in `src/gateway/server-methods/*.ts`. ### Sistema e identità -- `health` restituisce lo snapshot di health del gateway memorizzato in cache o appena sondato. +- `health` restituisce lo snapshot di salute del gateway memorizzato in cache o appena verificato. - `status` restituisce il riepilogo del gateway in stile `/status`; i campi sensibili sono - inclusi solo per client operator con ambito admin. + inclusi solo per i client operatore con ambito admin. - `gateway.identity.get` restituisce l'identità del dispositivo gateway usata dai flussi di relay e pairing. -- `system-presence` restituisce lo snapshot corrente della presence per i dispositivi +- `system-presence` restituisce lo snapshot corrente della presenza dei dispositivi operator/node connessi. - `system-event` aggiunge un evento di sistema e può aggiornare/trasmettere il contesto - di presence. + di presenza. - `last-heartbeat` restituisce l'ultimo evento heartbeat persistito. -- `set-heartbeats` attiva/disattiva l'elaborazione heartbeat sul gateway. +- `set-heartbeats` attiva o disattiva l'elaborazione degli heartbeat sul gateway. ### Modelli e utilizzo -- `models.list` restituisce il catalogo dei modelli consentiti a runtime. -- `usage.status` restituisce finestre di utilizzo del provider/riepiloghi della quota residua. -- `usage.cost` restituisce riepiloghi aggregati del costo di utilizzo per un intervallo di date. -- `doctor.memory.status` restituisce lo stato di preparazione di vector-memory / embedding per il - workspace dell'agente predefinito attivo. +- `models.list` restituisce il catalogo dei modelli consentiti dal runtime. +- `usage.status` restituisce le finestre di utilizzo dei provider e i riepiloghi della quota rimanente. +- `usage.cost` restituisce riepiloghi aggregati dei costi di utilizzo per un intervallo di date. +- `doctor.memory.status` restituisce lo stato di prontezza della memoria vettoriale / degli embedding per il + workspace predefinito attivo dell'agente. - `sessions.usage` restituisce riepiloghi di utilizzo per sessione. - `sessions.usage.timeseries` restituisce serie temporali di utilizzo per una sessione. -- `sessions.usage.logs` restituisce voci del log di utilizzo per una sessione. +- `sessions.usage.logs` restituisce le voci del log di utilizzo per una sessione. ### Canali e helper di login -- `channels.status` restituisce riepiloghi di stato dei canali/plugin integrati + inclusi. -- `channels.logout` disconnette uno specifico canale/account nei casi in cui il canale - supporti il logout. -- `web.login.start` avvia un flusso di login QR/web per il provider del canale web corrente con supporto QR. +- `channels.status` restituisce riepiloghi di stato dei canali/plugin integrati e bundled. +- `channels.logout` esegue il logout di un canale/account specifico dove il canale + supporta il logout. +- `web.login.start` avvia un flusso di login QR/web per il provider del canale web attuale con supporto QR. - `web.login.wait` attende il completamento di quel flusso di login QR/web e avvia il canale in caso di successo. - `push.test` invia una push APNs di test a un nodo iOS registrato. -- `voicewake.get` restituisce i trigger della parola di attivazione memorizzati. -- `voicewake.set` aggiorna i trigger della parola di attivazione e trasmette la modifica. +- `voicewake.get` restituisce i trigger wake-word memorizzati. +- `voicewake.set` aggiorna i trigger wake-word e trasmette la modifica. ### Messaggistica e log -- `send` è l'RPC diretto di consegna in uscita per invii indirizzati a canale/account/thread - al di fuori del runner chat. -- `logs.tail` restituisce il tail configurato del log file del gateway con controlli di cursore/limite e +- `send` è l'RPC diretto di consegna in uscita per invii mirati a canale/account/thread + al di fuori del runner di chat. +- `logs.tail` restituisce il tail del log file del gateway configurato con controlli di cursore/limite e byte massimi. ### Talk e TTS -- `talk.config` restituisce il payload di configurazione Talk effettivo; `includeSecrets` +- `talk.config` restituisce il payload effettivo della configurazione Talk; `includeSecrets` richiede `operator.talk.secrets` (o `operator.admin`). -- `talk.mode` imposta/trasmette lo stato corrente della modalità Talk per i client WebChat/Control UI. +- `talk.mode` imposta/trasmette lo stato corrente della modalità Talk per i client + WebChat/Control UI. - `talk.speak` sintetizza il parlato tramite il provider speech Talk attivo. -- `tts.status` restituisce stato TTS abilitato, provider attivo, provider di fallback - e stato della configurazione del provider. +- `tts.status` restituisce lo stato di abilitazione del TTS, il provider attivo, i provider di fallback + e lo stato della configurazione del provider. - `tts.providers` restituisce l'inventario visibile dei provider TTS. -- `tts.enable` e `tts.disable` attivano/disattivano lo stato delle preferenze TTS. +- `tts.enable` e `tts.disable` attivano o disattivano lo stato delle preferenze TTS. - `tts.setProvider` aggiorna il provider TTS preferito. -- `tts.convert` esegue una conversione text-to-speech one-shot. +- `tts.convert` esegue una conversione text-to-speech una tantum. -### Secrets, config, update e wizard +### Secrets, configurazione, aggiornamento e wizard -- `secrets.reload` risolve nuovamente i SecretRef attivi e sostituisce lo stato runtime dei secret +- `secrets.reload` risolve di nuovo i SecretRef attivi e sostituisce lo stato segreto del runtime solo in caso di successo completo. -- `secrets.resolve` risolve le assegnazioni di secret destinate ai comandi per uno specifico - insieme comando/target. +- `secrets.resolve` risolve le assegnazioni di secret mirate ai comandi per uno specifico insieme di comando/target. - `config.get` restituisce lo snapshot e l'hash della configurazione corrente. - `config.set` scrive un payload di configurazione validato. - `config.patch` unisce un aggiornamento parziale della configurazione. -- `config.apply` valida + sostituisce l'intero payload di configurazione. +- `config.apply` valida + sostituisce il payload completo della configurazione. - `config.schema` restituisce il payload dello schema di configurazione live usato da Control UI e - strumenti CLI: schema, `uiHints`, versione e metadati di generazione, inclusi - i metadati di schema di plugin + canale quando il runtime può caricarli. Lo schema - include i metadati dei campi `title` / `description` derivati dalle stesse etichette - e dal testo di aiuto usati dalla UI, incluse diramazioni di composizione annidate di oggetto, wildcard, - elemento di array e `anyOf` / `oneOf` / `allOf` quando esiste documentazione - di campo corrispondente. + dagli strumenti CLI: schema, `uiHints`, versione e metadati di generazione, inclusi + i metadati di schema di plugin + canali quando il runtime può caricarli. Lo schema + include metadati dei campi `title` / `description` derivati dalle stesse etichette + e dallo stesso testo di aiuto usati dalla UI, incluse le diramazioni annidate di object, wildcard, array-item + e composizione `anyOf` / `oneOf` / `allOf` quando esiste documentazione dei campi + corrispondente. - `config.schema.lookup` restituisce un payload di lookup con ambito di percorso per un percorso di configurazione: - percorso normalizzato, nodo di schema superficiale, hint corrispondente + `hintPath`, e + percorso normalizzato, un nodo di schema superficiale, hint corrispondente + `hintPath`, e riepiloghi dei figli immediati per drill-down UI/CLI. - - I nodi di schema di lookup mantengono la documentazione rivolta all'utente e i comuni campi di validazione: + - I nodi di schema di lookup mantengono la documentazione rivolta all'utente e i campi di validazione comuni: `title`, `description`, `type`, `enum`, `const`, `format`, `pattern`, - limiti numerici/stringa/array/oggetto, e flag booleani come + limiti numerici/stringa/array/object e flag booleani come `additionalProperties`, `deprecated`, `readOnly`, `writeOnly`. - I riepiloghi dei figli espongono `key`, `path` normalizzato, `type`, `required`, `hasChildren`, più `hint` / `hintPath` corrispondenti. @@ -317,250 +314,263 @@ implementato in `src/gateway/server-methods/*.ts`. - `wizard.start`, `wizard.next`, `wizard.status` e `wizard.cancel` espongono il wizard di onboarding tramite WS RPC. -### Principali famiglie esistenti +### Famiglie principali esistenti -#### Helper di agente e workspace +#### Helper per agente e workspace -- `agents.list` restituisce le voci di agente configurate. +- `agents.list` restituisce le voci degli agenti configurati. - `agents.create`, `agents.update` e `agents.delete` gestiscono i record degli agenti e il wiring del workspace. - `agents.files.list`, `agents.files.get` e `agents.files.set` gestiscono i - file bootstrap del workspace esposti per un agente. + file del workspace di bootstrap esposti per un agente. - `agent.identity.get` restituisce l'identità effettiva dell'assistente per un agente o - sessione. -- `agent.wait` attende che un'esecuzione finisca e restituisce lo snapshot terminale quando + una sessione. +- `agent.wait` attende la fine di un'esecuzione e restituisce lo snapshot terminale quando disponibile. #### Controllo della sessione - `sessions.list` restituisce l'indice corrente delle sessioni. -- `sessions.subscribe` e `sessions.unsubscribe` attivano/disattivano le sottoscrizioni agli eventi di modifica della sessione +- `sessions.subscribe` e `sessions.unsubscribe` attivano o disattivano le sottoscrizioni agli eventi di modifica delle sessioni per il client WS corrente. -- `sessions.messages.subscribe` e `sessions.messages.unsubscribe` attivano/disattivano - le sottoscrizioni agli eventi di transcript/messaggi per una sessione. -- `sessions.preview` restituisce anteprime limitate del transcript per specifiche chiavi di sessione. -- `sessions.resolve` risolve o canonizza un target di sessione. +- `sessions.messages.subscribe` e `sessions.messages.unsubscribe` attivano o disattivano + le sottoscrizioni agli eventi di trascrizione/messaggio per una sessione. +- `sessions.preview` restituisce anteprime limitate della trascrizione per specifiche + chiavi di sessione. +- `sessions.resolve` risolve o canonicalizza una destinazione di sessione. - `sessions.create` crea una nuova voce di sessione. - `sessions.send` invia un messaggio in una sessione esistente. -- `sessions.steer` è la variante di interrompi-e-sterza per una sessione attiva. +- `sessions.steer` è la variante interrupt-and-steer per una sessione attiva. - `sessions.abort` interrompe il lavoro attivo per una sessione. -- `sessions.patch` aggiorna metadati/override della sessione. -- `sessions.reset`, `sessions.delete` e `sessions.compact` eseguono manutenzione della sessione. -- `sessions.get` restituisce l'intera riga di sessione memorizzata. -- l'esecuzione della chat usa ancora `chat.history`, `chat.send`, `chat.abort` e +- `sessions.patch` aggiorna i metadati/le override della sessione. +- `sessions.reset`, `sessions.delete` e `sessions.compact` eseguono la manutenzione + della sessione. +- `sessions.get` restituisce la riga completa della sessione memorizzata. +- l'esecuzione della chat continua a usare `chat.history`, `chat.send`, `chat.abort` e `chat.inject`. -- `chat.history` è normalizzato per la visualizzazione per i client UI: i tag di direttiva inline vengono - rimossi dal testo visibile, i payload XML di chiamata strumento in testo semplice (inclusi +- `chat.history` è normalizzato per la visualizzazione per i client UI: i tag delle direttive inline vengono + rimossi dal testo visibile, i payload XML plain-text delle tool call (inclusi `...`, `...`, - `...`, `...`, e - blocchi di chiamata strumento troncati) e i token di controllo del modello ASCII/full-width trapelati - vengono rimossi, le righe dell'assistente composte solo da token silenziosi come esatto `NO_REPLY` / - `no_reply` vengono omesse, e le righe troppo grandi possono essere sostituite con placeholder. + `...`, `...` e + blocchi di tool call troncati) e i token di controllo del modello ASCII/full-width trapelati + vengono rimossi, le righe dell'assistente composte solo da token silenziosi come `NO_REPLY` / + `no_reply` esatti vengono omesse, e le righe troppo grandi possono essere sostituite con segnaposto. -#### Pairing del dispositivo e token del dispositivo +#### Pairing dei dispositivi e token dispositivo - `device.pair.list` restituisce i dispositivi associati in attesa e approvati. - `device.pair.approve`, `device.pair.reject` e `device.pair.remove` gestiscono - i record di pairing del dispositivo. -- `device.token.rotate` ruota un token di dispositivo associato entro i limiti di ruolo - e ambito approvati. + i record di pairing dei dispositivi. +- `device.token.rotate` ruota un token di dispositivo associato entro i limiti del ruolo + e degli ambiti approvati. - `device.token.revoke` revoca un token di dispositivo associato. #### Pairing dei nodi, invoke e lavoro in sospeso - `node.pair.request`, `node.pair.list`, `node.pair.approve`, - `node.pair.reject` e `node.pair.verify` coprono il pairing dei nodi e la verifica - del bootstrap. -- `node.list` e `node.describe` restituiscono lo stato dei nodi noti/connessi. + `node.pair.reject` e `node.pair.verify` coprono il pairing dei nodi e la + verifica del bootstrap. +- `node.list` e `node.describe` restituiscono lo stato dei nodi conosciuti/connessi. - `node.rename` aggiorna un'etichetta di nodo associato. - `node.invoke` inoltra un comando a un nodo connesso. - `node.invoke.result` restituisce il risultato di una richiesta invoke. -- `node.event` trasporta eventi originati dal nodo di nuovo nel gateway. +- `node.event` trasporta nel gateway gli eventi originati dal nodo. - `node.canvas.capability.refresh` aggiorna i token di capacità canvas con ambito. -- `node.pending.pull` e `node.pending.ack` sono le API della coda dei nodi connessi. -- `node.pending.enqueue` e `node.pending.drain` gestiscono il lavoro persistente in sospeso +- `node.pending.pull` e `node.pending.ack` sono le API di coda dei nodi connessi. +- `node.pending.enqueue` e `node.pending.drain` gestiscono il lavoro in sospeso durevole per nodi offline/disconnessi. #### Famiglie di approvazione - `exec.approval.request`, `exec.approval.get`, `exec.approval.list` e - `exec.approval.resolve` coprono le richieste di approvazione exec one-shot più - lookup/replay delle approvazioni in sospeso. -- `exec.approval.waitDecision` attende una singola approvazione exec in sospeso e restituisce - la decisione finale (o `null` in caso di timeout). -- `exec.approvals.get` e `exec.approvals.set` gestiscono gli snapshot della policy di approvazione exec del gateway. -- `exec.approvals.node.get` e `exec.approvals.node.set` gestiscono la policy di approvazione exec locale del nodo - tramite comandi di relay del nodo. + `exec.approval.resolve` coprono le richieste di approvazione exec one-shot più la + ricerca/riproduzione delle approvazioni in sospeso. +- `exec.approval.waitDecision` attende una decisione di approvazione exec in sospeso e restituisce + la decisione finale (oppure `null` in caso di timeout). +- `exec.approvals.get` e `exec.approvals.set` gestiscono gli snapshot della policy di approvazione exec + del gateway. +- `exec.approvals.node.get` e `exec.approvals.node.set` gestiscono la policy locale del nodo per exec + tramite comandi relay del nodo. - `plugin.approval.request`, `plugin.approval.list`, `plugin.approval.waitDecision` e `plugin.approval.resolve` coprono i flussi di approvazione definiti dai plugin. -#### Altre principali famiglie +#### Altre famiglie principali - automazione: - - `wake` pianifica un'iniezione di testo wake immediata o al successivo heartbeat + - `wake` pianifica un'iniezione di testo wake immediata o al prossimo heartbeat - `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`, `cron.run`, `cron.runs` -- skills/tools: `skills.*`, `tools.catalog`, `tools.effective` +- skills/tool: `commands.list`, `skills.*`, `tools.catalog`, `tools.effective` ### Famiglie comuni di eventi -- `chat`: aggiornamenti della chat UI come `chat.inject` e altri eventi chat - solo transcript. -- `session.message` e `session.tool`: aggiornamenti del transcript/event-stream per una - sessione sottoscritta. +- `chat`: aggiornamenti della chat UI come `chat.inject` e altri eventi di chat + solo di trascrizione. +- `session.message` e `session.tool`: aggiornamenti dello stream di trascrizione/eventi per una sessione sottoscritta. - `sessions.changed`: l'indice della sessione o i metadati sono cambiati. -- `presence`: aggiornamenti dello snapshot della presence di sistema. +- `presence`: aggiornamenti dello snapshot della presenza di sistema. - `tick`: evento periodico di keepalive / liveness. -- `health`: aggiornamento dello snapshot di health del gateway. -- `heartbeat`: aggiornamento del flusso di eventi heartbeat. +- `health`: aggiornamento dello snapshot di salute del gateway. +- `heartbeat`: aggiornamento dello stream di eventi heartbeat. - `cron`: evento di modifica di esecuzione/job cron. -- `shutdown`: notifica di arresto del gateway. -- `node.pair.requested` / `node.pair.resolved`: ciclo di vita del pairing dei nodi. +- `shutdown`: notifica di spegnimento del gateway. +- `node.pair.requested` / `node.pair.resolved`: ciclo di vita del pairing del nodo. - `node.invoke.request`: broadcast di richiesta invoke del nodo. - `device.pair.requested` / `device.pair.resolved`: ciclo di vita del dispositivo associato. -- `voicewake.changed`: la configurazione dei trigger della parola di attivazione è cambiata. +- `voicewake.changed`: la configurazione dei trigger della wake-word è cambiata. - `exec.approval.requested` / `exec.approval.resolved`: ciclo di vita dell'approvazione exec. - `plugin.approval.requested` / `plugin.approval.resolved`: ciclo di vita dell'approvazione del plugin. -### Metodi helper node +### Metodi helper del nodo - I nodi possono chiamare `skills.bins` per recuperare l'elenco corrente degli eseguibili delle skill per i controlli di auto-allow. -### Metodi helper operator +### Metodi helper dell'operatore -- Gli operator possono chiamare `tools.catalog` (`operator.read`) per recuperare il catalogo runtime degli strumenti per un - agente. La risposta include strumenti raggruppati e metadati di provenienza: +- Gli operatori possono chiamare `commands.list` (`operator.read`) per recuperare l'inventario dei comandi runtime per un agente. + - `agentId` è facoltativo; omettilo per leggere il workspace dell'agente predefinito. + - `scope` controlla quale superficie viene presa di mira dal `name` primario: + - `text` restituisce il token del comando testuale primario senza la barra iniziale `/` + - `native` e il percorso predefinito `both` restituiscono nomi nativi aware del provider + quando disponibili + - `textAliases` contiene alias slash esatti come `/model` e `/m`. + - `nativeName` contiene il nome del comando nativo aware del provider quando esiste. + - `provider` è facoltativo e influisce solo sulla denominazione nativa più sulla disponibilità dei + comandi nativi del plugin. + - `includeArgs=false` omette dai risultati i metadati serializzati degli argomenti. +- Gli operatori possono chiamare `tools.catalog` (`operator.read`) per recuperare il catalogo dei tool runtime per un + agente. La risposta include tool raggruppati e metadati di provenienza: - `source`: `core` o `plugin` - `pluginId`: proprietario del plugin quando `source="plugin"` - - `optional`: se uno strumento plugin è facoltativo -- Gli operator possono chiamare `tools.effective` (`operator.read`) per recuperare l'inventario degli strumenti effettivo a runtime + - `optional`: se un tool del plugin è facoltativo +- Gli operatori possono chiamare `tools.effective` (`operator.read`) per recuperare l'inventario dei tool effettivo del runtime per una sessione. - `sessionKey` è obbligatorio. - - Il gateway deriva il contesto runtime attendibile dalla sessione lato server invece di accettare - auth o contesto di consegna forniti dal chiamante. - - La risposta ha ambito di sessione e riflette ciò che la conversazione attiva può usare in questo momento, - inclusi strumenti core, plugin e canale. -- Gli operator possono chiamare `skills.status` (`operator.read`) per recuperare l'inventario visibile + - Il gateway deriva il contesto runtime affidabile dalla sessione lato server invece di accettare + contesto auth o di consegna fornito dal chiamante. + - La risposta è limitata alla sessione e riflette ciò che la conversazione attiva può usare in questo momento, + inclusi tool core, plugin e canali. +- Gli operatori possono chiamare `skills.status` (`operator.read`) per recuperare l'inventario visibile delle skill per un agente. - `agentId` è facoltativo; omettilo per leggere il workspace dell'agente predefinito. - La risposta include idoneità, requisiti mancanti, controlli di configurazione e opzioni di installazione sanificate senza esporre valori segreti grezzi. -- Gli operator possono chiamare `skills.search` e `skills.detail` (`operator.read`) per i metadati di discovery di - ClawHub. -- Gli operator possono chiamare `skills.install` (`operator.admin`) in due modalità: +- Gli operatori possono chiamare `skills.search` e `skills.detail` (`operator.read`) per i + metadati di discovery di ClawHub. +- Gli operatori possono chiamare `skills.install` (`operator.admin`) in due modalità: - Modalità ClawHub: `{ source: "clawhub", slug, version?, force? }` installa una cartella skill nella directory `skills/` del workspace dell'agente predefinito. - - Modalità installer gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` - esegue un'azione dichiarata `metadata.openclaw.install` sull'host gateway. -- Gli operator possono chiamare `skills.update` (`operator.admin`) in due modalità: + - Modalità installer del gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` + esegue un'azione dichiarata `metadata.openclaw.install` sull'host del gateway. +- Gli operatori possono chiamare `skills.update` (`operator.admin`) in due modalità: - La modalità ClawHub aggiorna uno slug tracciato o tutte le installazioni ClawHub tracciate nel workspace dell'agente predefinito. - - La modalità Config modifica i valori `skills.entries.` come `enabled`, - `apiKey` ed `env`. + - La modalità Config applica patch ai valori `skills.entries.` come `enabled`, + `apiKey` e `env`. ## Approvazioni exec -- Quando una richiesta exec richiede approvazione, il gateway trasmette `exec.approval.requested`. -- I client operator risolvono chiamando `exec.approval.resolve` (richiede ambito `operator.approvals`). -- Per `host=node`, `exec.approval.request` deve includere `systemRunPlan` (`argv`/`cwd`/`rawCommand`/metadati di sessione canonici). Le richieste senza `systemRunPlan` vengono rifiutate. -- Dopo l'approvazione, le chiamate `node.invoke system.run` inoltrate riutilizzano quel +- Quando una richiesta exec necessita di approvazione, il gateway trasmette `exec.approval.requested`. +- I client operatore risolvono chiamando `exec.approval.resolve` (richiede l'ambito `operator.approvals`). +- Per `host=node`, `exec.approval.request` deve includere `systemRunPlan` (`argv`/`cwd`/`rawCommand`/metadati della sessione canonici). Le richieste senza `systemRunPlan` vengono rifiutate. +- Dopo l'approvazione, le chiamate inoltrate `node.invoke system.run` riutilizzano quel `systemRunPlan` canonico come contesto autorevole di comando/cwd/sessione. - Se un chiamante modifica `command`, `rawCommand`, `cwd`, `agentId` o - `sessionKey` tra prepare e l'inoltro finale approvato di `system.run`, il + `sessionKey` tra `prepare` e l'inoltro finale approvato di `system.run`, il gateway rifiuta l'esecuzione invece di fidarsi del payload modificato. ## Fallback di consegna dell'agente - Le richieste `agent` possono includere `deliver=true` per richiedere la consegna in uscita. -- `bestEffortDeliver=false` mantiene il comportamento rigoroso: i target di consegna irrisolti o solo interni restituiscono `INVALID_REQUEST`. -- `bestEffortDeliver=true` consente il fallback all'esecuzione solo-sessione quando non è possibile risolvere alcun percorso di consegna esterno (ad esempio sessioni internal/webchat o configurazioni multi-canale ambigue). +- `bestEffortDeliver=false` mantiene il comportamento rigoroso: le destinazioni di consegna irrisolte o solo interne restituiscono `INVALID_REQUEST`. +- `bestEffortDeliver=true` consente il fallback all'esecuzione solo in sessione quando non è possibile risolvere alcun percorso di consegna esterno (ad esempio sessioni interne/webchat o configurazioni multi-canale ambigue). ## Versioning - `PROTOCOL_VERSION` si trova in `src/gateway/protocol/schema.ts`. -- I client inviano `minProtocol` + `maxProtocol`; il server rifiuta i mismatch. -- Schemi + modelli sono generati da definizioni TypeBox: +- I client inviano `minProtocol` + `maxProtocol`; il server rifiuta le incompatibilità. +- Schemi + modelli vengono generati a partire dalle definizioni TypeBox: - `pnpm protocol:gen` - `pnpm protocol:gen:swift` - `pnpm protocol:check` ## Auth -- L'autenticazione gateway con secret condiviso usa `connect.params.auth.token` o +- L'auth del gateway con segreto condiviso usa `connect.params.auth.token` oppure `connect.params.auth.password`, a seconda della modalità auth configurata. -- Le modalità con identità portante come Tailscale Serve - (`gateway.auth.allowTailscale: true`) o `gateway.auth.mode: "trusted-proxy"` non-loopback - soddisfano il controllo auth di connect dagli header della richiesta invece che da `connect.params.auth.*`. -- L'ingresso privato `gateway.auth.mode: "none"` salta completamente l'auth connect con secret condiviso; non esporre quella modalità su ingressi pubblici/non attendibili. -- Dopo il pairing, il gateway emette un **token del dispositivo** con ambito del ruolo + degli ambiti della connessione. Viene restituito in `hello-ok.auth.deviceToken` e dovrebbe essere +- Le modalità che trasportano identità, come Tailscale Serve + (`gateway.auth.allowTailscale: true`) o `gateway.auth.mode: "trusted-proxy"` + su endpoint non-loopback, soddisfano il controllo auth di connessione dagli header + della richiesta invece che da `connect.params.auth.*`. +- `gateway.auth.mode: "none"` su ingressi privati salta completamente l'auth di connessione con segreto condiviso; non esporre questa modalità su ingressi pubblici/non affidabili. +- Dopo il pairing, il Gateway emette un **token dispositivo** limitato al ruolo + agli ambiti della connessione. Viene restituito in `hello-ok.auth.deviceToken` e deve essere persistito dal client per le connessioni future. -- I client dovrebbero persistere il `hello-ok.auth.deviceToken` primario dopo ogni +- I client devono persistere il `hello-ok.auth.deviceToken` primario dopo ogni connessione riuscita. -- La riconnessione con quel token del dispositivo **memorizzato** dovrebbe anche riutilizzare l'insieme di ambiti approvati memorizzato - per quel token. Questo preserva l'accesso in lettura/probe/stato - già concesso ed evita di ridurre silenziosamente le riconnessioni a un - ambito implicito più ristretto solo admin. -- La normale precedenza auth di connect è prima token/password condivisi espliciti, poi +- La riconnessione con quel token dispositivo **memorizzato** deve anche riutilizzare l'insieme di ambiti approvati memorizzato per quel token. Questo preserva l'accesso + già concesso in lettura/probe/status ed evita che le riconnessioni si riducano silenziosamente a un + ambito implicito solo admin più ristretto. +- La precedenza auth normale della connessione è: token/password condiviso esplicito per primo, poi `deviceToken` esplicito, poi token per dispositivo memorizzato, poi token di bootstrap. -- Le voci aggiuntive `hello-ok.auth.deviceTokens` sono token di passaggio bootstrap. - Persistile solo quando la connessione ha usato auth bootstrap su un trasporto attendibile - come `wss://` o pairing loopback/locale. -- Se un client fornisce un **`deviceToken` esplicito** o `scopes` espliciti, quell'insieme di ambiti richiesto dal chiamante resta autorevole; gli ambiti in cache vengono riutilizzati solo - quando il client sta riutilizzando il token per dispositivo memorizzato. -- I token del dispositivo possono essere ruotati/revocati tramite `device.token.rotate` e - `device.token.revoke` (richiede ambito `operator.pairing`). -- L'emissione/rotazione dei token resta limitata all'insieme di ruoli approvati registrato nella - voce di pairing di quel dispositivo; ruotare un token non può espandere il dispositivo in un +- Le voci aggiuntive `hello-ok.auth.deviceTokens` sono token di handoff del bootstrap. + Persistile solo quando la connessione ha usato auth di bootstrap su un trasporto affidabile + come `wss://` o loopback/pairing locale. +- Se un client fornisce un `deviceToken` **esplicito** o `scopes` espliciti, quell'insieme di ambiti richiesto dal chiamante rimane autorevole; gli ambiti in cache vengono riutilizzati solo quando il client sta riutilizzando il token per dispositivo memorizzato. +- I token dispositivo possono essere ruotati/revocati tramite `device.token.rotate` e + `device.token.revoke` (richiede l'ambito `operator.pairing`). +- L'emissione/la rotazione dei token rimane limitata all'insieme di ruoli approvato registrato nella + voce di pairing di quel dispositivo; la rotazione di un token non può espandere il dispositivo a un ruolo che l'approvazione del pairing non ha mai concesso. -- Per le sessioni token di dispositivo associato, la gestione del dispositivo ha ambito proprio salvo che il - chiamante abbia anche `operator.admin`: i chiamanti non-admin possono rimuovere/revocare/ruotare - solo la **propria** voce dispositivo. -- `device.token.rotate` controlla anche l'insieme di ambiti operator richiesto rispetto agli - ambiti della sessione corrente del chiamante. I chiamanti non-admin non possono ruotare un token in un insieme di ambiti operator più ampio di quello che già possiedono. -- I fallimenti auth includono `error.details.code` più suggerimenti di recupero: +- Per le sessioni di token di dispositivi associati, la gestione del dispositivo è limitata al proprio ambito a meno che il + chiamante non abbia anche `operator.admin`: i chiamanti non admin possono rimuovere/revocare/ruotare + solo la **propria** voce di dispositivo. +- `device.token.rotate` controlla anche l'insieme di ambiti operatore richiesto rispetto agli + ambiti della sessione corrente del chiamante. I chiamanti non admin non possono ruotare un token verso + un insieme di ambiti operatore più ampio di quello che già possiedono. +- I fallimenti auth includono `error.details.code` più suggerimenti per il recupero: - `error.details.canRetryWithDeviceToken` (boolean) - `error.details.recommendedNextStep` (`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`) - Comportamento del client per `AUTH_TOKEN_MISMATCH`: - - I client attendibili possono tentare un unico retry limitato con un token per dispositivo in cache. + - I client affidabili possono tentare un singolo retry limitato con un token per dispositivo in cache. - Se quel retry fallisce, i client devono interrompere i loop di riconnessione automatica e mostrare indicazioni per l'azione dell'operatore. ## Identità del dispositivo + pairing -- I nodi devono includere un'identità del dispositivo stabile (`device.id`) derivata da un +- I nodi devono includere un'identità del dispositivo stabile (`device.id`) derivata da una fingerprint della coppia di chiavi. - I gateway emettono token per dispositivo + ruolo. -- Le approvazioni di pairing sono richieste per nuovi ID dispositivo a meno che non sia abilitata - l'auto-approvazione locale. -- L'auto-approvazione del pairing è centrata sulle connessioni dirette local loopback. -- OpenClaw ha anche un percorso ristretto di self-connect backend/container-local per - flussi helper attendibili con secret condiviso. +- Le approvazioni di pairing sono richieste per i nuovi ID dispositivo a meno che l'approvazione automatica locale + non sia abilitata. +- L'approvazione automatica del pairing è incentrata sulle connessioni dirette local loopback. +- OpenClaw ha anche un percorso self-connect backend/container-local limitato per + flussi helper affidabili con segreto condiviso. - Le connessioni tailnet o LAN sullo stesso host sono comunque trattate come remote per il pairing e richiedono approvazione. - Tutti i client WS devono includere l'identità `device` durante `connect` (operator + node). Control UI può ometterla solo in queste modalità: - - `gateway.controlUi.allowInsecureAuth=true` per compatibilità localhost-only con HTTP insicuro. + - `gateway.controlUi.allowInsecureAuth=true` per compatibilità HTTP non sicura solo localhost. - auth operator Control UI riuscita con `gateway.auth.mode: "trusted-proxy"`. - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (break-glass, grave downgrade della sicurezza). - Tutte le connessioni devono firmare il nonce `connect.challenge` fornito dal server. -### Diagnostica di migrazione auth del dispositivo +### Diagnostica della migrazione dell'auth del dispositivo Per i client legacy che usano ancora il comportamento di firma pre-challenge, `connect` ora restituisce codici di dettaglio `DEVICE_AUTH_*` sotto `error.details.code` con un `error.details.reason` stabile. -Fallimenti di migrazione comuni: +Errori di migrazione comuni: -| Messaggio | details.code | details.reason | Significato | -| ---------------------------- | -------------------------------- | ------------------------ | --------------------------------------------------- | -| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Il client ha omesso `device.nonce` (o lo ha inviato vuoto). | -| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Il client ha firmato con un nonce vecchio/errato. | -| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | Il payload della firma non corrisponde al payload v2. | -| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | Il timestamp firmato è fuori dallo skew consentito. | -| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` non corrisponde al fingerprint della chiave pubblica. | -| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Il formato/canonicalizzazione della chiave pubblica non è riuscito. | +| Messaggio | details.code | details.reason | Significato | +| --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- | +| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Il client ha omesso `device.nonce` (o lo ha inviato vuoto). | +| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Il client ha firmato con un nonce obsoleto/errato. | +| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | Il payload della firma non corrisponde al payload v2. | +| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | Il timestamp firmato è fuori dallo skew consentito. | +| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` non corrisponde alla fingerprint della chiave pubblica. | +| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Il formato/canonicalizzazione della chiave pubblica non è riuscito. | Obiettivo della migrazione: @@ -569,16 +579,17 @@ Obiettivo della migrazione: - Inviare lo stesso nonce in `connect.params.device.nonce`. - Il payload di firma preferito è `v3`, che vincola `platform` e `deviceFamily` oltre ai campi device/client/role/scopes/token/nonce. -- Le firme legacy `v2` restano accettate per compatibilità, ma il pinning dei metadati del dispositivo associato continua a controllare la policy dei comandi alla riconnessione. +- Le firme legacy `v2` restano accettate per compatibilità, ma il pinning dei metadati + del dispositivo associato continua a controllare la policy dei comandi alla riconnessione. ## TLS + pinning - TLS è supportato per le connessioni WS. -- I client possono opzionalmente fissare il fingerprint del certificato del gateway (vedi config `gateway.tls` - più `gateway.remote.tlsFingerprint` o CLI `--tls-fingerprint`). +- I client possono facoltativamente fare pinning della fingerprint del certificato del gateway (vedi configurazione `gateway.tls` + più `gateway.remote.tlsFingerprint` o il flag CLI `--tls-fingerprint`). ## Ambito -Questo protocollo espone la **API completa del gateway** (status, channels, models, chat, +Questo protocollo espone l'**API completa del gateway** (status, channels, models, chat, agent, sessions, nodes, approvals, ecc.). La superficie esatta è definita dagli schemi TypeBox in `src/gateway/protocol/schema.ts`. diff --git a/docs/it/help/testing.md b/docs/it/help/testing.md index 264a93c17..f99759f9b 100644 --- a/docs/it/help/testing.md +++ b/docs/it/help/testing.md @@ -1,28 +1,28 @@ --- read_when: - - Esecuzione dei test in locale o in CI - - Aggiunta di regressioni per bug di modelli/provider - - Debug del comportamento di gateway + agente -summary: 'Kit di test: suite unit/e2e/live, runner Docker e ciò che copre ciascun test' -title: Testing + - Eseguire i test in locale o in CI + - Aggiungere test di regressione per bug di modelli/provider + - Debug del comportamento del gateway e dell'agente +summary: 'Kit di test: suite unit/e2e/live, runner Docker e cosa copre ciascun test' +title: Testირება x-i18n: - generated_at: "2026-04-09T01:30:37Z" + generated_at: "2026-04-10T08:13:32Z" model: gpt-5.4 provider: openai - source_hash: 01117f41d8b171a4f1da11ed78486ee700e70ae70af54eb6060c57baf64ab21b + source_hash: 21b78e59a5189f4e8e6e1b490d350f4735c0395da31d21fc5d10b825313026b4 source_path: help/testing.md workflow: 15 --- -# Testing +# Test -OpenClaw dispone di tre suite Vitest (unit/integration, e2e, live) e di un piccolo insieme di runner Docker. +OpenClaw ha tre suite Vitest (unit/integration, e2e, live) e un piccolo insieme di runner Docker. Questo documento è una guida a “come testiamo”: -- Che cosa copre ciascuna suite (e che cosa deliberatamente _non_ copre) +- Cosa copre ogni 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 @@ -31,257 +31,279 @@ Nella maggior parte dei casi: - 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` -- Ciclo 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` +- Ciclo diretto di watch 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` +- Quando stai iterando su un singolo errore, preferisci prima esecuzioni mirate. - 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` -Quando modifichi i test o vuoi maggiore affidabilità: +Quando tocchi i test o vuoi maggiore sicurezza: - Gate di copertura: `pnpm test:coverage` - Suite E2E: `pnpm test:e2e` -Quando esegui il debug di provider/modelli reali (richiede credenziali reali): +Quando esegui il debug di provider/modelli reali, richiede credenziali reali: - Suite live (modelli + probe di tool/immagini del gateway): `pnpm test:live` -- Punta a un singolo file live in modalità silenziosa: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Esegui in modo silenzioso un singolo file live: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Suggerimento: quando ti serve solo un caso che fallisce, è preferibile restringere i test live tramite le variabili env di allowlist descritte di seguito. +Suggerimento: quando ti serve solo un caso in errore, preferisci restringere i test live tramite le variabili d'ambiente di allowlist descritte sotto. -## Suite di test (cosa viene eseguito e dove) +## Runner specifici per QA -Considera le suite come livelli di “realismo crescente” (e di maggiore instabilità/costo): +Questi comandi affiancano le suite di test principali quando ti serve il realismo di qa-lab: -### Unit / integration (predefinita) +- `pnpm openclaw qa suite` + - Esegue direttamente sull'host gli scenari QA supportati dal repo. +- `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 che sono pratici per il guest: + chiavi provider basate su env, il percorso della configurazione del provider live QA e `CODEX_HOME` + quando presente. + - Le directory di output devono restare sotto la root del repo in modo che il guest possa scrivere di nuovo tramite + il workspace montato. + - Scrive il normale report + riepilogo QA, oltre ai log di Multipass, sotto + `.artifacts/qa-e2e/...`. +- `pnpm qa:lab:up` + - Avvia il sito QA supportato da Docker per lavoro QA in stile operatore. + +## Suite di test, cosa viene eseguito e dove + +Considera le suite come livelli di “realismo crescente”, e di crescente fragilità/costo: + +### Unit / integration, predefinita - Comando: `pnpm test` -- Configurazione: dieci esecuzioni shard sequenziali (`vitest.full-*.config.ts`) sui progetti Vitest con ambito già esistenti -- File: inventari core/unit in `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` e i test node `ui` in allowlist coperti da `vitest.unit.config.ts` +- Configurazione: dieci esecuzioni sequenziali di shard (`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 unitari puri - - Test di integrazione in-process (auth del gateway, routing, tooling, parsing, config) + - Test di integrazione in-process, autenticazione del gateway, routing, tooling, parsing, configurazione - Regressioni deterministiche per bug noti - Aspettative: - Viene eseguita in CI - Non richiede chiavi reali - Dovrebbe essere veloce e stabile - Nota sui progetti: - - `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 grande processo nativo del progetto root. Questo riduce il picco di RSS sulle macchine cariche ed evita che il lavoro di auto-reply/extension affami suite non correlate. - - `pnpm test --watch` usa ancora il grafo di progetto nativo root `vitest.config.ts`, perché un ciclo 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 con ambito, quindi `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita di pagare il costo di avvio completo del progetto root. - - `pnpm test:changed` espande i percorsi git modificati nelle stesse corsie con ambito quando la differenza tocca solo file sorgente/test instradabili; le modifiche a config/setup ripiegano comunque sulla riesecuzione più ampia del progetto root. - - Alcuni test `plugin-sdk` e `commands` vengono inoltre instradati attraverso corsie leggere dedicate che saltano `test/setup-openclaw-runtime.ts`; i file stateful/con runtime pesante restano nelle corsie esistenti. - - Alcuni file sorgente helper di `plugin-sdk` e `commands` mappano anche le esecuzioni in modalità changed ai 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 del harness reply più pesante lontano dai test economici su stato/chunk/token. + - `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 root-project nativo. Questo riduce il picco di RSS su macchine sotto carico ed evita che il lavoro di auto-reply/extension affami suite non correlate. + - `pnpm test --watch` usa ancora il grafo di progetti del root nativo `vitest.config.ts`, perché un ciclo di watch multi-shard non è pratico. + - `pnpm test`, `pnpm test:watch` e `pnpm test:perf:imports` instradano prima file/directory espliciti attraverso lane scoped, quindi `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita di pagare il costo di avvio completo del root project. + - `pnpm test:changed` espande i percorsi git modificati nelle stesse lane scoped quando il diff tocca solo file sorgente/test instradabili; le modifiche a config/setup tornano comunque alla riesecuzione più ampia del root project. + - Alcuni test `plugin-sdk` e `commands` selezionati passano anche attraverso lane leggere dedicate che saltano `test/setup-openclaw-runtime.ts`; i file stateful o pesanti in fase di runtime restano sulle lane esistenti. + - Alcuni file sorgente helper `plugin-sdk` e `commands` selezionati mappano anche le esecuzioni in modalità changed ai 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 tiene il lavoro più pesante dell'harness reply lontano dai test economici di status/chunk/token. - Nota sul runner embedded: - - Quando modifichi gli input di discovery dei message-tool o il contesto runtime di compaction, + - Quando modifichi input di discovery dei message-tool o il contesto runtime di compaction, mantieni entrambi i livelli di copertura. - - Aggiungi regressioni helper mirate per i confini puri di routing/normalizzazione. - - Mantieni inoltre in salute le suite di integrazione del runner embedded: + - Aggiungi regressioni helper mirate per i boundary puri di routing/normalizzazione. + - Mantieni anche in salute le suite di integrazione del runner embedded: `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 con ambito e il comportamento di compaction continuino a fluire + - Queste suite verificano che gli id scoped e il comportamento di compaction continuino a fluire attraverso i percorsi reali `run.ts` / `compact.ts`; i soli test helper non sono un sostituto sufficiente di questi percorsi di integrazione. - Nota sul pool: - - La configurazione base di Vitest ora usa `threads` per impostazione predefinita. - - La configurazione Vitest condivisa fissa inoltre `isolate: false` e usa il runner non isolato nei progetti root, nelle config e2e e live. - - La corsia UI root mantiene la propria configurazione `jsdom` e l'optimizer, ma ora viene eseguita 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` ai processi Node figli di Vitest per impostazione predefinita, per ridurre il churn di compilazione V8 durante le grandi esecuzioni locali. Imposta `OPENCLAW_VITEST_ENABLE_MAGLEV=1` se devi confrontare il comportamento con il V8 standard. + - La configurazione base di Vitest ora usa `threads` come predefinito. + - La configurazione condivisa di Vitest fissa anche `isolate: false` e usa il runner non isolato nei root project, e2e e live config. + - La lane UI root mantiene il proprio setup `jsdom` e 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 condivisa di Vitest. + - Il launcher condiviso `scripts/run-vitest.mjs` ora aggiunge anche `--no-maglev` per i processi child Node di Vitest per impostazione predefinita, per ridurre il churn di compilazione V8 durante grandi esecuzioni locali. Imposta `OPENCLAW_VITEST_ENABLE_MAGLEV=1` se devi confrontarti con il comportamento V8 standard. - Nota sull'iterazione locale veloce: - - `pnpm test:changed` instrada attraverso corsie con ambito quando i percorsi modificati si mappano chiaramente a una suite più piccola. - - `pnpm test:max` e `pnpm test:changed:max` mantengono lo stesso comportamento di instradamento, solo con un limite più alto di worker. - - L'auto-scaling locale dei worker ora è intenzionalmente più conservativo e riduce ulteriormente il carico quando il load average dell'host è già alto, così più esecuzioni Vitest concorrenti fanno meno danni per impostazione predefinita. - - La configurazione base di Vitest contrassegna i file di progetto/configurazione come `forceRerunTriggers` in modo che le riesecuzioni in modalità changed rimangano 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=/percorso/assoluto` se vuoi una posizione di cache esplicita per il profiling diretto. + - `pnpm test:changed` passa attraverso lane scoped quando i percorsi modificati corrispondono chiaramente a una suite più piccola. + - `pnpm test:max` e `pnpm test:changed:max` mantengono lo stesso comportamento di routing, solo con un limite di worker più alto. + - L'auto-scaling locale dei worker ora è intenzionalmente conservativo e riduce anche l'attività quando il load average dell'host è già alto, così più esecuzioni Vitest concorrenti causano meno danni per impostazione predefinita. + - La configurazione base di Vitest contrassegna i file di progetto/config 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 un'unica posizione di cache esplicita per il profiling diretto. - Nota sul debug delle prestazioni: - - `pnpm test:perf:imports` abilita il report della durata degli import di Vitest insieme all'output del dettaglio degli import. + - `pnpm test:perf:imports` abilita il reporting della durata degli import di Vitest insieme all'output di scomposizione 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 del progetto root per quella differenza commitata e stampa wall time più RSS massimo su macOS. -- `pnpm test:perf:changed:bench -- --worktree` misura il worktree sporco corrente instradando l'elenco dei file modificati attraverso `scripts/test-projects.mjs` e la configurazione Vitest root. - - `pnpm test:perf:profile:main` scrive un profilo CPU del thread principale per i costi di avvio e trasformazione di Vitest/Vite. - - `pnpm test:perf:profile:runner` scrive profili CPU+heap del runner per la suite unit con parallelismo dei file disabilitato. +- `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ù RSS massimo su macOS. +- `pnpm test:perf:changed:bench -- --worktree` esegue il benchmark del dirty tree corrente instradando l'elenco dei file modificati attraverso `scripts/test-projects.mjs` e la configurazione root di Vitest. + - `pnpm test:perf:profile:main` scrive un profilo CPU del thread principale per l'overhead di avvio e trasformazione di Vitest/Vite. + - `pnpm test:perf:profile:runner` scrive profili CPU+heap del runner per la suite unit con il parallelismo dei file disabilitato. -### E2E (gateway smoke) +### E2E, gateway smoke - Comando: `pnpm test:e2e` - Configurazione: `vitest.e2e.config.ts` - File: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` -- Runtime predefinito: - - Usa Vitest `threads` con `isolate: false`, in linea con il resto del repository. - - Usa worker adattivi (CI: fino a 2, locale: 1 per impostazione predefinita). - - Viene eseguito in modalità silenziosa per impostazione predefinita per ridurre l'overhead di I/O della console. +- Valori predefiniti di runtime: + - 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. + - Viene eseguita 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 dettagliato della console. + - `OPENCLAW_E2E_WORKERS=` per forzare il numero di worker, limitato a 16. + - `OPENCLAW_E2E_VERBOSE=1` per riattivare output dettagliato sulla console. - Ambito: - - Comportamento end-to-end del gateway multiistanza + - Comportamento end-to-end del gateway multi-istanza - Superfici WebSocket/HTTP, pairing dei nodi e networking più pesante - Aspettative: - - Viene eseguito in CI (quando abilitato nella pipeline) + - Viene eseguita in CI, quando abilitata nella pipeline - Non richiede chiavi reali - - Ha più parti mobili dei test unitari (può essere più lento) + - Ha più parti in movimento rispetto ai test unitari, quindi può essere più lenta ### 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 - - Crea un sandbox da un Dockerfile locale temporaneo - - Esegue il backend OpenShell di OpenClaw su `sandbox ssh-config` + exec SSH reali - - Verifica il comportamento del filesystem remoto-canonico tramite il bridge fs del sandbox + - Avvia sull'host un gateway OpenShell isolato tramite Docker + - Crea una sandbox a partire da un Dockerfile locale temporaneo + - Esegue 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 - Aspettative: - - Solo opt-in; non fa parte dell'esecuzione predefinita `pnpm test:e2e` + - Solo opt-in; non fa parte dell'esecuzione predefinita di `pnpm test:e2e` - Richiede una CLI `openshell` locale e un demone Docker funzionante - - Usa `HOME` / `XDG_CONFIG_HOME` isolati, poi distrugge il gateway di test e il 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 si esegue manualmente la suite e2e più ampia - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/percorso/a/openshell` per puntare a un binario CLI non predefinito o a uno script wrapper + - `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 una CLI binaria o a uno script wrapper non predefinito -### Live (provider reali + modelli reali) +### Live, provider reali + modelli reali - Comando: `pnpm test:live` - Configurazione: `vitest.live.config.ts` - File: `src/**/*.live.test.ts` -- Predefinito: **abilitato** da `pnpm test:live` (imposta `OPENCLAW_LIVE_TEST=1`) +- Predefinito: **abilitata** da `pnpm test:live`, imposta `OPENCLAW_LIVE_TEST=1` - Ambito: - “Questo provider/modello funziona davvero _oggi_ con credenziali reali?” - - Individua cambiamenti di formato del provider, particolarità nel tool calling, problemi di auth e comportamento dei rate limit + - Individua cambiamenti nel formato del provider, particolarità del tool-calling, problemi di autenticazione e comportamento dei rate limit - Aspettative: - - Per progettazione non è stabile in CI (reti reali, policy reali dei provider, quote, outage) + - Per progettazione non è stabile in CI, reti reali, policy reali dei provider, quote, interruzioni - Costa denaro / usa rate limit - È preferibile eseguire sottoinsiemi ristretti invece di “tutto” - Le esecuzioni live caricano `~/.profile` per recuperare eventuali chiavi API mancanti. -- Per impostazione predefinita, le esecuzioni live isolano comunque `HOME` e copiano il materiale di config/auth in una home di test temporanea in modo che le fixture unit non possano modificare il tuo vero `~/.openclaw`. -- Imposta `OPENCLAW_LIVE_USE_REAL_HOME=1` solo quando vuoi intenzionalmente 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 extra su `~/.profile` e silenzia i log di bootstrap del gateway/il chatter Bonjour. Imposta `OPENCLAW_LIVE_TEST_QUIET=0` se vuoi ripristinare i log completi di avvio. -- Rotazione delle chiavi API (specifica per provider): imposta `*_API_KEYS` in formato virgola/punto e virgola o `*_API_KEY_1`, `*_API_KEY_2` (ad esempio `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) oppure usa l'override per-live `OPENCLAW_LIVE_*_KEY`; i test ritentano in caso di risposte da rate limit. +- Per impostazione predefinita, le esecuzioni live isolano comunque `HOME` e copiano il materiale di config/auth in una home temporanea di test, così i fixture unit non possono modificare il tuo `~/.openclaw` reale. +- Imposta `OPENCLAW_LIVE_USE_REAL_HOME=1` solo quando vuoi intenzionalmente che i test live usino la tua home directory reale. +- `pnpm test:live` ora usa una modalità più silenziosa per impostazione predefinita: mantiene l'output di avanzamento `[live] ...`, ma sopprime l'avviso extra su `~/.profile` e silenzia i log di bootstrap del gateway e il rumore di 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 virgola/punto e virgola oppure `*_API_KEY_1`, `*_API_KEY_2`, per esempio `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`, oppure usa l'override per-live `OPENCLAW_LIVE_*_KEY`; i test ritentano sulle 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 provider/gateway vengono trasmesse immediatamente durante le esecuzioni live. - - Regola gli heartbeat dei modelli diretti con `OPENCLAW_LIVE_HEARTBEAT_MS`. + - `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 del modello diretto con `OPENCLAW_LIVE_HEARTBEAT_MS`. - Regola gli heartbeat di gateway/probe con `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. -## Quale suite dovrei eseguire? +## Quale suite devo eseguire? Usa questa tabella decisionale: -- Modifica di logica/test: esegui `pnpm test` (e `pnpm test:coverage` se hai modificato molto) -- Modifiche a networking del gateway / protocollo WS / pairing: aggiungi `pnpm test:e2e` +- Modifica di logica/test: esegui `pnpm test`, e `pnpm test:coverage` se hai cambiato molto +- Tocco di 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 -## Live: sweep delle capability del nodo Android +## Live: sweep delle capacità del nodo Android - Test: `src/gateway/android-node.capabilities.live.test.ts` - Script: `pnpm android:test:integration` -- Obiettivo: invocare **ogni comando attualmente pubblicizzato** da un nodo Android connesso e verificare il comportamento contrattuale del comando. +- Obiettivo: invocare **ogni comando attualmente pubblicizzato** da un nodo Android connesso e verificare il comportamento del contratto dei comandi. - Ambito: - - Setup precondizionato/manuale (la suite non installa/esegue/effettua il pairing dell'app). + - Setup manuale/con precondizioni, la suite non installa, esegue o abbina l'app. - Validazione `node.invoke` del gateway comando per comando per il nodo Android selezionato. - Pre-setup richiesto: - - App Android già connessa e associata al gateway. - - App mantenuta in foreground. - - Permessi/consenso di acquisizione concessi per le capability che ci si aspetta superino il test. -- Override facoltativi del target: - - `OPENCLAW_ANDROID_NODE_ID` o `OPENCLAW_ANDROID_NODE_NAME`. + - App Android già connessa e abbinata al gateway. + - App mantenuta in primo piano. + - Permessi/consenso alla cattura concessi per le capacità che ti aspetti passino. +- Override opzionali 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 della configurazione Android: [Android App](/it/platforms/android) -## Live: smoke dei modelli (chiavi profilo) +## Live: smoke dei modelli, chiavi del profilo -I test live sono divisi in due livelli così possiamo isolare i guasti: +I test live sono suddivisi in due livelli in modo da poter 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+agente funziona per quel modello (sessioni, cronologia, tool, policy del sandbox, ecc.). +- “Direct model” ci dice se il provider/modello può rispondere o meno con la chiave fornita. +- “Gateway smoke” ci dice se l'intera pipeline gateway+agente funziona per quel modello, sessioni, cronologia, tool, policy della sandbox e così via. -### 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 quando necessario) + - Eseguire un piccolo completamento per modello, e regressioni mirate quando 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` concentrato sul gateway smoke + - `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 sul gateway smoke - Come selezionare i modelli: - - `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 dell'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 limite curato ad alto segnale; imposta `OPENCLAW_LIVE_MAX_MODELS=0` per uno sweep modern esaustivo o un numero positivo per un limite più piccolo. + - `OPENCLAW_LIVE_MODELS=modern` per eseguire la 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 la allowlist moderna + - 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 limite curato ad alto segnale; imposta `OPENCLAW_LIVE_MAX_MODELS=0` per uno sweep moderno 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 provengono le chiavi: - - Per impostazione predefinita: archivio profili e fallback env - - Imposta `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre **solo** l'archivio profili + - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`, allowlist separata da virgole +- Da dove arrivano le chiavi: + - Per impostazione predefinita: store del profilo e fallback env + - Imposta `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre **solo** lo store del profilo - Perché esiste: - - Separa “l'API del provider è rotta / la chiave non è valida” da “la pipeline dell'agente gateway è rotta” - - Contiene regressioni piccole e isolate (esempio: replay del reasoning OpenAI Responses/Codex Responses + flussi tool-call) + - Separa “la API del provider è rotta / la chiave non è valida” da “la pipeline dell'agente del gateway è rotta” + - Contiene regressioni piccole e isolate, esempio: replay del ragionamento OpenAI Responses/Codex Responses + flussi di tool-call -### Livello 2: smoke di gateway + agente dev (quello che fa davvero "@openclaw") +### Livello 2: smoke di gateway + agente dev, ciò 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) + - Creare/modificare una sessione `agent:dev:*`, override del modello per esecuzione - Iterare sui modelli con chiavi e verificare: - - risposta “significativa” (senza tool) - - funzionamento di una vera invocazione di tool (probe di read) - - probe facoltative di tool aggiuntive (probe exec+read) - - i percorsi di regressione OpenAI (solo tool-call → follow-up) continuano 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 leggerlo con `read` e di restituire il nonce. - - probe `exec+read`: il test chiede all'agente di scrivere un nonce in un file temporaneo tramite `exec`, quindi di rileggerlo. - - probe immagine: il test allega un PNG generato (gatto + codice randomizzato) e si aspetta che il modello restituisca `cat `. + - risposta “significativa”, senza tool + - funziona una vera invocazione di tool, probe di read + - probe di tool extra opzionali, probe exec+read + - i percorsi di regressione OpenAI, solo tool-call → follow-up, continuano 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 `read` quel file e riecheggiare il nonce. + - probe `exec+read`: il test chiede all'agente di scrivere tramite `exec` un nonce in un file temporaneo, poi di leggerlo di nuovo con `read`. + - probe immagine: 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) + - `pnpm test:live` oppure `OPENCLAW_LIVE_TEST=1` se invochi Vitest direttamente - Come selezionare i modelli: - - 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 dell'allowlist modern - - Oppure imposta `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (o elenco separato 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 o un numero positivo per un limite più piccolo. -- Come selezionare i provider (evitare “tutto OpenRouter”): - - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist separata da virgole) + - 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 la 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 limite curato ad alto segnale; imposta `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` per uno sweep moderno esaustivo oppure un numero positivo per un limite più piccolo. +- Come selezionare i provider, evita “OpenRouter tutto”: + - `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 dei tool) + - probe `read` + probe `exec+read`, stress dei tool - la probe immagine viene eseguita quando il modello pubblicizza il supporto per input immagine - - Flusso (alto livello): + - Flusso, ad 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: "" }]` - Il 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 - - Verifica: la risposta contiene `cat` + il codice (tolleranza OCR: piccoli errori consentiti) + - Verifica: la risposta contiene `cat` + il codice, tolleranza OCR: piccoli errori sono consentiti -Suggerimento: per vedere cosa puoi testare sulla tua macchina (e gli id esatti `provider/model`), esegui: +Suggerimento: per vedere cosa puoi testare sulla tua macchina, e gli id esatti `provider/model`, esegui: ```bash openclaw models list openclaw models list --json ``` -## Live: smoke del backend CLI (Claude, Codex, Gemini o altre CLI locali) +## 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 config predefinita. -- Gli smoke predefiniti specifici del backend si trovano nella definizione `cli-backend.ts` dell'extension proprietaria. -- Abilita: - - `pnpm test:live` (oppure `OPENCLAW_LIVE_TEST=1` se invochi Vitest direttamente) +- Obiettivo: convalidare la pipeline Gateway + agente usando un backend CLI locale, senza toccare la configurazione predefinita. +- I valori predefiniti dello 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` - Predefiniti: - Provider/modello predefinito: `claude-cli/claude-sonnet-4-6` - - Comando/argomenti/comportamento immagine provengono dai metadati del plugin proprietario del backend CLI. -- Override (facoltativi): + - Il comportamento di comando/argomenti/immagine proviene dai metadati del plugin del backend CLI proprietario. +- Override, opzionali: - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/percorso/completo/a/codex"` + - `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"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` per inviare un vero allegato immagine (i percorsi vengono iniettati nel prompt). - - `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 è impostato `IMAGE_ARG`. - - `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 da Claude Sonnet a Opus (imposta `1` per forzarla quando il modello selezionato supporta un target di switch). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` per inviare un vero allegato immagine, i percorsi vengono iniettati nel prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` per passare i percorsi dei file immagine come argomenti della CLI invece di iniettarli 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 convalidare il flusso di ripresa. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` per disabilitare la probe predefinita di continuità nella stessa sessione da Claude Sonnet a Opus, impostalo a `1` per forzarla quando il modello selezionato supporta un target di switch. Esempio: @@ -308,26 +330,26 @@ 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 dello smoke CLI dall'extension proprietaria, quindi installa il pacchetto Linux CLI 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`). -- 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 modifica inoltre la sessione da Sonnet a Opus e verifica che la sessione ripresa ricordi ancora una nota precedente. +- Esegue lo smoke del backend CLI live dentro l'immagine Docker del repo come utente non root `node`. +- Risolve i metadati dello smoke 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`. +- Lo smoke del backend CLI live ora esercita lo stesso flusso end-to-end per Claude, Codex e Gemini: turno di testo, turno di classificazione immagine, quindi chiamata dello strumento 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. -## 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 ACP di conversation-bind con un agente ACP live: +- Obiettivo: convalidare il vero flusso ACP conversation-bind con un agente ACP live: - inviare `/acp spawn --bind here` - - associare sul posto una conversazione sintetica di message-channel - - inviare un normale follow-up su quella stessa conversazione + - associare sul posto una conversazione sintetica del canale messaggi + - inviare un normale follow-up sulla stessa conversazione - verificare che il follow-up finisca nella trascrizione della sessione ACP associata -- Abilita: +- Abilitazione: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - Predefiniti: - Agenti ACP in Docker: `claude,codex,gemini` - Agente ACP per `pnpm test:live ...` diretto: `claude` - - Canale sintetico: contesto conversazione in stile Slack DM + - Canale sintetico: contesto di conversazione in stile DM Slack - Backend ACP: `acpx` - Override: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` @@ -336,8 +358,8 @@ Note: - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Note: - - Questa corsia usa la superficie gateway `chat.send` con campi di originating-route sintetici riservati agli admin così i test possono allegare il contesto del message-channel senza fingere una consegna esterna. - - Quando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` non è impostato, il test usa il registro agenti integrato del plugin embedded `acpx` per l'agente harness ACP selezionato. + - Questa lane usa la superficie `chat.send` del gateway con campi di originating-route sintetici riservati agli admin, così i test possono allegare il contesto del canale messaggi senza fingere una consegna esterna. + - Quando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` non è impostato, il test usa il registro agent integrato del plugin `acpx` embedded per l'agente harness ACP selezionato. Esempio: @@ -364,136 +386,136 @@ 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 lo smoke ACP bind su tutti gli agenti CLI live supportati in sequenza: `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. -- Carica `~/.profile`, prepara nel container il materiale di auth CLI corrispondente, installa `acpx` in un prefisso npm scrivibile, quindi 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 dal profilo caricato. +- 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` oppure `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` per restringere la matrice. +- Carica `~/.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` oppure `@google/gemini-cli`, se manca. +- Dentro Docker, il runner imposta `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` in modo che acpx mantenga disponibili alla CLI harness figlia le variabili env del provider dal profilo caricato. ### Ricette live consigliate -Le allowlist ristrette ed esplicite sono le più rapide e meno soggette a instabilità: +Allowlist ristrette ed esplicite sono più veloci e meno fragili: -- 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, gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Tool calling su diversi provider: +- Tool calling su vari 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 su Google (chiave API Gemini + Antigravity): - - Gemini (chiave API): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` +- Focus su Google, chiave API Gemini + Antigravity: + - Gemini, chiave API: `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` + - Antigravity, OAuth: `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` Note: -- `google/...` usa l'API Gemini (chiave API). -- `google-antigravity/...` usa il bridge OAuth Antigravity (endpoint agente in stile Cloud Code Assist). -- `google-gemini-cli/...` usa la CLI Gemini locale sulla tua macchina (auth separata + particolarità di tooling). -- Gemini API vs Gemini CLI: - - API: OpenClaw chiama via HTTP l'API Gemini ospitata da Google (chiave API / auth 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/disallineamento di versione). +- `google/...` usa la API Gemini, chiave API. +- `google-antigravity/...` usa il bridge OAuth Antigravity, endpoint agente in stile Cloud Code Assist. +- `google-gemini-cli/...` usa la CLI Gemini locale sulla tua macchina, con autenticazione separata e particolarità proprie degli strumenti. +- Gemini API rispetto a Gemini CLI: + - API: OpenClaw chiama la API Gemini ospitata da Google tramite HTTP, autenticazione con chiave API / profilo; questo è ciò che la maggior parte degli utenti intende con “Gemini”. + - CLI: OpenClaw invoca una binaria locale `gemini`; ha una propria autenticazione e può comportarsi in modo diverso, streaming/supporto strumenti/disallineamento di versione. -## Live: matrice dei modelli (cosa copriamo) +## Live: matrice dei modelli, cosa copriamo -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. +Non esiste un “elenco di 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 + immagini) +### Set smoke moderno, tool calling + immagini -Questa è l'esecuzione dei “modelli comuni” che ci aspettiamo di mantenere funzionante: +Questa è l'esecuzione dei “modelli comuni” che ci aspettiamo continui a funzionare: -- OpenAI (non-Codex): `openai/gpt-5.4` (facoltativo: `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 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` +- 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, 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 il gateway smoke con tool + immagine: +Esegui il gateway smoke con tool + immagini: `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` -### Base: tool calling (Read + Exec facoltativo) +### Baseline: tool calling, Read + Exec opzionale -Scegline almeno uno per famiglia di provider: +Scegline almeno uno per ogni famiglia di provider: -- OpenAI: `openai/gpt-5.4` (oppure `openai/gpt-5.4-mini`) -- Anthropic: `anthropic/claude-opus-4-6` (oppure `anthropic/claude-sonnet-4-6`) -- Google: `google/gemini-3-flash-preview` (oppure `google/gemini-3.1-pro-preview`) -- Z.AI (GLM): `zai/glm-4.7` +- OpenAI: `openai/gpt-5.4`, oppure `openai/gpt-5.4-mini` +- Anthropic: `anthropic/claude-opus-4-6`, oppure `anthropic/claude-sonnet-4-6` +- Google: `google/gemini-3-flash-preview`, oppure `google/gemini-3.1-pro-preview` +- Z.AI, GLM: `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Copertura aggiuntiva facoltativa (utile avere): +Copertura aggiuntiva facoltativa, utile ma non indispensabile: -- xAI: `xai/grok-4` (oppure l'ultima versione disponibile) -- Mistral: `mistral/`… (scegli un modello abilitato ai “tools” che hai attivato) -- Cerebras: `cerebras/`… (se hai accesso) -- LM Studio: `lmstudio/`… (locale; il tool calling dipende dalla modalità API) +- xAI: `xai/grok-4`, oppure l'ultima disponibile +- Mistral: `mistral/`… scegli un modello abilitato ai “tools” che hai attivato +- Cerebras: `cerebras/`… se hai accesso +- LM Studio: `lmstudio/`… locale; il tool calling dipende dalla modalità API -### Vision: invio immagine (allegato → messaggio multimodale) +### Vision: invio immagine, allegato → messaggio multimodale -Includi almeno un modello con capability per immagini in `OPENCLAW_LIVE_GATEWAY_MODELS` (varianti Claude/Gemini/OpenAI con supporto vision, ecc.) per esercitare la probe immagine. +Includi almeno un modello con capacità di immagini in `OPENCLAW_LIVE_GATEWAY_MODELS`, varianti Claude/Gemini/OpenAI con capacità vision e così via, per esercitare la probe immagine. ### Aggregatori / gateway alternativi -Se hai chiavi abilitate, supportiamo anche i test tramite: +Se hai le chiavi abilitate, supportiamo anche i test tramite: -- OpenRouter: `openrouter/...` (centinaia di modelli; usa `openclaw models scan` per trovare candidati con supporto a tool+immagini) -- OpenCode: `opencode/...` per Zen e `opencode-go/...` per Go (auth tramite `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) +- OpenRouter: `openrouter/...`, centinaia di modelli; usa `openclaw models scan` per trovare candidati con capacità di tool+immagini +- OpenCode: `opencode/...` per Zen e `opencode-go/...` per Go, autenticazione tramite `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY` -Altri provider che puoi includere nella matrice live (se hai credenziali/config): +Altri provider che puoi includere nella matrice live, se hai credenziali/configurazione: - 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.) +- Tramite `models.providers`, endpoint personalizzati: `minimax`, cloud/API, più qualsiasi proxy compatibile OpenAI/Anthropic, LM Studio, vLLM, LiteLLM e così via -Suggerimento: non cercare di codificare “tutti i modelli” nella documentazione. L'elenco autorevole è ciò che restituisce `discoverModels(...)` sulla tua macchina + le chiavi effettivamente disponibili. +Suggerimento: non provare a fissare nei documenti “tutti i modelli”. L'elenco autorevole è qualunque cosa restituisca `discoverModels(...)` sulla tua macchina più le chiavi disponibili. -## Credenziali (non fare mai commit) +## Credenziali, non fare mai commit -I test live scoprono 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 per `openclaw models list` / selezione del modello. +- Se un test live dice “no creds”, esegui il debug nello stesso modo in cui faresti con `openclaw models list` / selezione del modello. -- Profili auth per agente: `~/.openclaw/agents//agent/auth-profiles.json` (questo è ciò che significa “profile keys” nei test live) -- Config: `~/.openclaw/openclaw.json` (oppure `OPENCLAW_CONFIG_PATH`) -- Directory di stato legacy: `~/.openclaw/credentials/` (copiata nella home live preparata quando presente, ma non è l'archivio principale delle chiavi profilo) -- Le esecuzioni live locali copiano per impostazione predefinita la config attiva, i file `auth-profiles.json` per agente, `credentials/` legacy e le directory auth CLI esterne supportate in una home di test temporanea; le home live preparate 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 agente: `~/.openclaw/agents//agent/auth-profiles.json`, questo è il significato di “profile keys” nei test live +- Configurazione: `~/.openclaw/openclaw.json`, oppure `OPENCLAW_CONFIG_PATH` +- Directory di stato legacy: `~/.openclaw/credentials/`, copiata nella home live preparata quando presente, ma non è lo store principale delle chiavi di profilo +- Le esecuzioni live locali copiano per impostazione predefinita la configurazione attiva, i file `auth-profiles.json` per agente, `credentials/` legacy e le directory auth delle CLI esterne supportate in una home temporanea di test; le home live preparate saltano `workspace/` e `sandboxes/`, e gli override di percorso `agents.*.workspace` / `agentDir` vengono rimossi così le probe restano fuori dal tuo workspace reale sull'host. -Se vuoi basarti sulle 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 basarti su chiavi env, per esempio esportate nel tuo `~/.profile`, esegui i test locali dopo `source ~/.profile`, oppure usa i runner Docker qui sotto, che possono montare `~/.profile` nel container. -## Live Deepgram (trascrizione audio) +## Live Deepgram, trascrizione audio - Test: `src/media-understanding/providers/deepgram/audio.live.test.ts` -- Abilita: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` +- Abilitazione: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` -## Live del piano di coding BytePlus +## Live BytePlus, piano di coding - Test: `src/agents/byteplus.live.test.ts` -- Abilita: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live 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 facoltativo: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Live dei media di workflow ComfyUI +## Live ComfyUI, media del workflow - Test: `extensions/comfy/comfy.live.test.ts` -- Abilita: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- 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 bundled comfy per immagini, video e `music_generate` - - Salta ogni capability a meno che `models.providers.comfy.` non sia configurato - - Utile dopo modifiche all'invio dei workflow comfy, al polling, ai download o alla registrazione del plugin + - Salta ogni capacità a meno che `models.providers.comfy.` non sia configurato + - Utile dopo modifiche all'invio del workflow comfy, polling, download o registrazione del plugin -## Live della generazione immagini +## Live: generazione immagini - 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 della probe - - Per impostazione predefinita usa 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 utilizzabili - - Esegue le varianti standard di generazione immagini tramite la capability runtime condivisa: + - Carica le variabili env mancanti dei provider dalla tua shell di login, `~/.profile`, prima di eseguire le 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 credenziali reali della shell + - Salta i provider senza auth/profilo/modello utilizzabile + - Esegue le varianti standard di generazione immagini tramite la capacità runtime condivisa: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` @@ -501,198 +523,200 @@ Se vuoi basarti sulle chiavi env (ad esempio esportate nel tuo `~/.profile`), es - Provider bundled attualmente coperti: - `openai` - `google` -- Restringimento facoltativo: +- 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 facoltativo: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre l'auth dell'archivio profili e ignorare gli override solo env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre auth dallo store dei profili e ignorare gli override solo-env -## Live della generazione musicale +## Live: generazione musica - Test: `extensions/music-generation-providers.live.test.ts` -- Abilita: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- 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 bundled del provider di generazione musicale + - Esercita il percorso condiviso bundled del provider di generazione musica - Attualmente copre Google e MiniMax - - Carica le variabili env provider dalla tua shell di login (`~/.profile`) prima della probe - - Per impostazione predefinita usa 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 utilizzabili + - Carica le variabili env dei provider dalla tua shell di login, `~/.profile`, prima di eseguire le 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 credenziali reali della shell + - Salta i provider senza auth/profilo/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 corsia condivisa: + - Copertura attuale della lane condivisa: - `google`: `generate`, `edit` - `minimax`: `generate` - `comfy`: file live Comfy separato, non questo sweep condiviso -- Restringimento facoltativo: +- 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 facoltativo: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre l'auth dell'archivio profili e ignorare gli override solo env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre auth dallo store dei profili e ignorare gli override solo-env -## Live della generazione video +## Live: generazione video - Test: `extensions/video-generation-providers.live.test.ts` -- Abilita: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- 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 bundled del provider di generazione video - - Carica le variabili env provider dalla tua shell di login (`~/.profile`) prima della probe - - Per impostazione predefinita usa 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 utilizzabili + - Carica le variabili env dei provider dalla tua shell di login, `~/.profile`, prima di eseguire le 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 credenziali reali della shell + - Salta i provider senza auth/profilo/modello utilizzabile - Esegue entrambe le modalità runtime dichiarate quando disponibili: - `generate` con input solo prompt - - `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 basato su buffer nello sweep condiviso + - `videoToVideo` quando il provider dichiara `capabilities.videoToVideo.enabled` e il provider/modello selezionato accetta input video locale basato su buffer nello sweep condiviso - Provider `imageToVideo` attualmente dichiarati ma saltati nello sweep condiviso: - - `vydra` perché `veo3` bundled è solo testo e `kling` bundled richiede un URL immagine remoto - - Copertura Vydra specifica per provider: + - `vydra` perché il bundled `veo3` è solo testo e il bundled `kling` richiede un URL immagine remoto + - Copertura Vydra specifica del provider: - `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 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` + - quel file esegue `veo3` text-to-video più una lane `kling` che usa per impostazione predefinita un fixture con URL immagine remoto + - Copertura live `videoToVideo` attuale: + - `runway` solo quando il modello selezionato è `runway/gen4_aleph` - Provider `videoToVideo` attualmente dichiarati ma saltati nello sweep condiviso: - - `alibaba`, `qwen`, `xai` perché questi percorsi richiedono attualmente URL di riferimento remoti `http(s)` / MP4 - - `google` perché l'attuale corsia Gemini/Veo condivisa usa input locale supportato da buffer e quel percorso non viene accettato nello sweep condiviso - - `openai` perché l'attuale corsia condivisa non garantisce l'accesso specifico dell'organizzazione al video inpaint/remix -- Restringimento facoltativo: + - `alibaba`, `qwen`, `xai` perché questi percorsi al momento richiedono URL di riferimento remoti `http(s)` / MP4 + - `google` perché l'attuale lane condivisa Gemini/Veo usa input locale basato su buffer e quel percorso non è accettato nello sweep condiviso + - `openai` perché l'attuale lane condivisa non garantisce accesso specifico all'organizzazione per 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"` - Comportamento auth facoltativo: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre l'auth dell'archivio profili e ignorare gli override solo env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre auth dallo store dei profili e ignorare gli override solo-env -## Harness live dei media +## Harness live per media - Comando: `pnpm test:live:media` - Scopo: - - Esegue le suite live condivise di immagini, musica e video tramite un unico entrypoint nativo del repository - - Carica automaticamente le variabili env provider mancanti da `~/.profile` - - Per impostazione predefinita restringe automaticamente ogni suite ai provider che al momento hanno auth utilizzabile - - Riutilizza `scripts/test-live.mjs`, così heartbeat e modalità silenziosa restano coerenti + - Esegue le suite live condivise per immagini, musica e video tramite un unico entrypoint nativo del repo + - Carica automaticamente le variabili env mancanti dei provider 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 quiet mode resta coerente - 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 facoltativi “funziona su Linux”) +## Runner Docker, controlli facoltativi “funziona su Linux” -Questi runner Docker si dividono in due gruppi: +Questi runner Docker sono suddivisi in due categorie: -- Runner di modelli live: `test:docker:live-models` e `test:docker:live-gateway` eseguono solo il rispettivo file live di profile-key corrispondente all'interno dell'immagine Docker del repository (`src/agents/models.profiles.live.test.ts` e `src/gateway/gateway-models.profiles.live.test.ts`), montando la directory di config locale e il workspace (e caricando `~/.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: +- Runner live-model: `test:docker:live-models` e `test:docker:live-gateway` eseguono solo il rispettivo file live con chiavi di profilo dentro l'immagine Docker del repo, `src/agents/models.profiles.live.test.ts` e `src/gateway/gateway-models.profiles.live.test.ts`, montando la directory di configurazione locale e il workspace, e caricando `~/.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 in modo che uno sweep Docker completo resti 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 + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Esegui l'override di queste variabili env quando vuoi esplicitamente una scansione esaustiva più ampia. -- `test:docker:all` compila una volta l'immagine Docker live tramite `test:docker:live-build`, quindi la riutilizza per le due corsie live Docker. -- I runner smoke dei 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 lane Docker live. +- 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 dei modelli live montano inoltre in bind solo le home auth CLI necessarie (o tutte quelle supportate quando l'esecuzione non è ristretta), quindi le copiano nella home del container prima dell'esecuzione così l'OAuth CLI esterno può aggiornare i token senza modificare l'archivio auth dell'host: +I runner Docker live-model montano anche in bind solo le home di autenticazione CLI necessarie, oppure tutte quelle supportate quando l'esecuzione non è ristretta, poi le copiano nella home del container prima dell'esecuzione in modo che l'OAuth delle CLI esterne possa aggiornare i token senza modificare lo store di autenticazione 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`) -- Gateway + agente 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`) -- Procedura guidata 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 canale MCP (Gateway seedato + bridge stdio + smoke raw del notification-frame di Claude): `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`) +- 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` +- Gateway + agente 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, autenticazione WS + health: `pnpm test:docker:gateway-network`, script: `scripts/e2e/gateway-network-docker.sh` +- Bridge del canale MCP, Gateway inizializzato + 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` -I runner Docker dei modelli live montano inoltre in bind il checkout corrente in sola lettura e -lo preparano in una workdir temporanea all'interno del container. Questo mantiene snella l'immagine runtime -pur eseguendo Vitest sulla tua esatta sorgente/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 locali `.build` dell'app o output -Gradle così le esecuzioni live Docker non passano minuti a copiare artefatti specifici della macchina. -Impostano inoltre `OPENCLAW_SKIP_CHANNELS=1` così le probe live del gateway non avviano -worker di canale reali Telegram/Discord/ecc. dentro il container. -`test:docker:live-models` esegue comunque `pnpm test:live`, quindi passa anche -`OPENCLAW_LIVE_GATEWAY_*` quando devi restringere o escludere la copertura live del gateway da quella corsia Docker. +I runner Docker live-model montano inoltre in bind il checkout corrente in sola lettura e +lo preparano in una workdir temporanea dentro il container. Questo mantiene l'immagine runtime +leggera pur continuando a eseguire Vitest sulla tua esatta configurazione/sorgente locale. +Il passaggio di preparazione salta cache locali di grandi dimensioni e output di build delle app +come `.pnpm-store`, `.worktrees`, `__openclaw_vitest__` e directory `.build` locali dell'app o +directory di output Gradle, così le esecuzioni Docker live non passano minuti a copiare +artefatti specifici della macchina. +Impostano anche `OPENCLAW_SKIP_CHANNELS=1` così le probe live del gateway non avviano +veri worker di canale Telegram/Discord/ecc. dentro il container. +`test:docker:live-models` esegue comunque `pnpm test:live`, quindi fai passare +anche `OPENCLAW_LIVE_GATEWAY_*` quando devi restringere o escludere la copertura +live del gateway da quella lane Docker. `test:docker:openwebui` è uno smoke di compatibilità di livello superiore: avvia un -container gateway OpenClaw con 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 +container gateway OpenClaw con gli endpoint HTTP compatibili con OpenAI abilitati, +avvia un container Open WebUI fissato contro quel gateway, esegue l'accesso 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 corsia richiede una chiave di modello live utilizzabile, e `OPENCLAW_PROFILE_FILE` -(`~/.profile` per impostazione predefinita) è il modo principale per fornirla nelle esecuzioni Dockerizzate. +La prima esecuzione può essere sensibilmente più lenta perché Docker potrebbe dover scaricare +l'immagine Open WebUI e Open WebUI potrebbe dover completare la propria configurazione iniziale. +Questa lane richiede una chiave di modello live utilizzabile, e `OPENCLAW_PROFILE_FILE`, +`~/.profile` per impostazione predefinita, è il modo principale per fornirla nelle esecuzioni Docker. Le esecuzioni riuscite stampano un piccolo payload JSON come `{ "ok": true, "model": "openclaw/default", ... }`. -`test:docker:mcp-channels` è intenzionalmente deterministico e non richiede un -vero account Telegram, Discord o iMessage. Avvia un container Gateway seedato, -avvia un secondo container che esegue `openclaw mcp serve`, quindi -verifica discovery delle conversazioni instradate, letture della trascrizione, metadati degli allegati, -comportamento della coda eventi live, instradamento degli invii in uscita e notifiche in stile Claude su canale + -permessi 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 realmente, non solo ciò che una specifica SDK client decide di esporre. +`test:docker:mcp-channels` è intenzionalmente deterministico e non richiede un vero +account Telegram, Discord o iMessage. Avvia un container Gateway inizializzato, +avvia un secondo container che esegue `openclaw mcp serve`, poi +verifica il rilevamento delle conversazioni instradate, la lettura delle trascrizioni, i metadati degli allegati, +il comportamento della coda eventi live, l'instradamento degli invii in uscita e le notifiche di canale + +permessi in stile Claude sul vero bridge MCP stdio. Il controllo delle notifiche +ispeziona direttamente i frame MCP stdio raw così lo smoke convalida ciò che il +bridge emette davvero, non solo ciò che un determinato SDK client capita di esporre. -Smoke manuale ACP di thread in linguaggio naturale (non CI): +Smoke manuale ACP di thread in linguaggio naturale, non CI: - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Mantieni questo script per i flussi di regressione/debug. Potrebbe servire di nuovo per la validazione del routing dei thread ACP, quindi non eliminarlo. +- Mantieni questo script per i flussi di lavoro di regressione/debug. Potrebbe servire di nuovo per la convalida del routing dei thread ACP, quindi non eliminarlo. Variabili env utili: -- `OPENCLAW_CONFIG_DIR=...` (predefinito: `~/.openclaw`) montato su `/home/node/.openclaw` -- `OPENCLAW_WORKSPACE_DIR=...` (predefinito: `~/.openclaw/workspace`) montato su `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (predefinito: `~/.profile`) montato su `/home/node/.profile` e caricato prima di eseguire i test -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (predefinito: `~/.cache/openclaw/docker-cli-tools`) montato su `/home/node/.npm-global` per installazioni CLI in cache dentro Docker -- Directory/file auth CLI esterni sotto `$HOME` vengono montati in sola lettura sotto `/host-auth...`, quindi copiati in `/home/node/...` prima dell'avvio dei test +- `OPENCLAW_CONFIG_DIR=...`, predefinito: `~/.openclaw`, montata in `/home/node/.openclaw` +- `OPENCLAW_WORKSPACE_DIR=...`, predefinito: `~/.openclaw/workspace`, montata in `/home/node/.openclaw/workspace` +- `OPENCLAW_PROFILE_FILE=...`, predefinito: `~/.profile`, montata in `/home/node/.profile` e caricata prima di eseguire i test +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`, predefinito: `~/.cache/openclaw/docker-cli-tools`, montata in `/home/node/.npm-global` per installazioni CLI in cache dentro Docker +- Directory/file di autenticazione CLI esterni sotto `$HOME` sono 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/i 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` + - 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` oppure un elenco separato 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_LIVE_REQUIRE_PROFILE_KEYS=1` per garantire che le credenziali provengano dall'archivio profili (non dall'env) +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per garantire che le credenziali provengano dallo store dei profili, 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 immagine Open WebUI fissato +- `OPENCLAW_OPENWEBUI_PROMPT=...` per eseguire l'override del prompt di controllo nonce usato dallo smoke Open WebUI +- `OPENWEBUI_IMAGE=...` per eseguire l'override del tag immagine Open WebUI fissato -## Verifica della documentazione +## Verifica rapida della documentazione -Esegui i controlli della documentazione dopo le modifiche ai documenti: `pnpm check:docs`. -Esegui la validazione completa degli anchor Mintlify quando ti servono anche i controlli delle intestazioni nella pagina: `pnpm docs:check-links:anchors`. +Esegui i controlli della documentazione dopo modifiche ai documenti: `pnpm check:docs`. +Esegui la validazione completa degli anchor Mintlify quando ti servono anche controlli sugli heading nella pagina: `pnpm docs:check-links:anchors`. -## Regressione offline (sicura per CI) +## Regressione offline, sicura per CI Queste sono regressioni della “pipeline reale” senza provider reali: -- Tool calling del gateway (OpenAI simulato, vero loop gateway + agente): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Procedura guidata del 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") +- Tool calling del gateway, OpenAI simulato, vero loop gateway + 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" -## Valutazioni di affidabilità dell'agente (Skills) +## Valutazioni di affidabilità dell'agente, Skills Abbiamo già alcuni test sicuri per CI che si comportano come “valutazioni di affidabilità dell'agente”: -- Tool-calling simulato attraverso il vero loop gateway + agente (`src/gateway/gateway.test.ts`). -- Flussi end-to-end della procedura guidata che validano il wiring delle sessioni e gli effetti della config (`src/gateway/gateway.test.ts`). +- Mock del tool-calling tramite il vero loop gateway + agente, `src/gateway/gateway.test.ts`. +- Flussi wizard end-to-end che convalidano il wiring della sessione e gli effetti della configurazione, `src/gateway/gateway.test.ts`. -Cosa manca ancora per le 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)? +- **Decisioning:** quando le Skills sono elencate nel prompt, l'agente sceglie la Skill corretta, o evita quelle irrilevanti? - **Compliance:** l'agente legge `SKILL.md` prima dell'uso e segue i passaggi/gli argomenti richiesti? -- **Workflow contracts:** scenari multi-turno che verificano ordine dei tool, riporto della cronologia della sessione e confini del sandbox. +- **Workflow contracts:** scenari multi-turno che verificano ordine degli strumenti, riporto della cronologia della sessione e boundary della sandbox. -Le valutazioni future dovrebbero rimanere prima di tutto deterministiche: +Le valutazioni future dovrebbero prima di tutto restare deterministiche: -- Un runner di scenari che usa provider simulati per verificare chiamate ai tool + ordine, letture dei file skill e wiring delle sessioni. -- 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 è stata messa in atto. +- Un runner di scenari che usa provider simulati per verificare chiamate agli strumenti + ordine, lettura dei file skill e wiring della sessione. +- Una piccola suite di scenari focalizzati sulle skill, usare vs evitare, gating, prompt injection. +- Valutazioni live facoltative, opt-in e controllate da env, solo dopo che la suite sicura per CI sarà pronta. -## Test di contratto (forma di plugin e channel) +## Test di contratto, forma di plugin e channel -I test di contratto verificano che ogni plugin e channel registrato sia conforme al proprio -contratto di interfaccia. Iterano su tutti i plugin individuati ed eseguono una suite di -verifiche di forma e comportamento. La corsia unit predefinita `pnpm test` +I test di contratto verificano che ogni plugin e channel 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 lane unit predefinita di `pnpm test` salta intenzionalmente questi file condivisi di seam e smoke; esegui esplicitamente i comandi di contratto quando modifichi superfici condivise di channel o provider. @@ -704,55 +728,55 @@ i comandi di contratto quando modifichi superfici condivise di channel o provide ### Contratti dei channel -Situati in `src/channels/plugins/contracts/*.contract.test.ts`: +Si trovano in `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Forma di base del plugin (id, nome, capability) -- **setup** - Contratto della procedura guidata di configurazione +- **plugin** - Forma base del plugin, id, nome, capacità +- **setup** - Contratto del wizard di configurazione - **session-binding** - Comportamento di associazione della sessione - **outbound-payload** - Struttura del payload del messaggio - **inbound** - Gestione dei messaggi in ingresso - **actions** - Handler delle azioni del channel -- **threading** - Gestione dell'ID del thread +- **threading** - Gestione degli id dei thread - **directory** - API di directory/roster -- **group-policy** - Applicazione della group policy +- **group-policy** - Applicazione della policy di gruppo -### Contratti di stato del provider +### Contratti di stato dei provider -Situati in `src/plugins/contracts/*.contract.test.ts`. +Si trovano in `src/plugins/contracts/*.contract.test.ts`. - **status** - Probe di stato del channel -- **registry** - Forma del registro plugin +- **registry** - Forma del registro dei plugin ### Contratti dei provider -Situati in `src/plugins/contracts/*.contract.test.ts`: +Si trovano in `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Contratto del flusso di auth -- **auth-choice** - Scelta/selezione dell'auth -- **catalog** - API del catalogo modelli -- **discovery** - Discovery del plugin -- **loader** - Caricamento del plugin +- **auth** - Contratto del flusso di autenticazione +- **auth-choice** - Scelta/selezione dell'autenticazione +- **catalog** - API del catalogo dei modelli +- **discovery** - Rilevamento dei plugin +- **loader** - Caricamento dei plugin - **runtime** - Runtime del provider - **shape** - Forma/interfaccia del plugin -- **wizard** - Procedura guidata di configurazione +- **wizard** - Wizard di configurazione ### Quando eseguirli -- Dopo aver modificato export o sottopercorsi di plugin-sdk +- Dopo aver modificato export o subpath del plugin-sdk - Dopo aver aggiunto o modificato un plugin channel o provider -- Dopo aver rifattorizzato la registrazione o la discovery dei plugin +- Dopo aver rifattorizzato la registrazione o il rilevamento dei plugin I test di contratto vengono eseguiti in CI e non richiedono chiavi API reali. -## Aggiunta di regressioni (linee guida) +## Aggiungere regressioni, linee guida -Quando correggi un problema di provider/modello scoperto in live: +Quando correggi un problema provider/modello scoperto in live: -- Aggiungi, se possibile, una regressione sicura per CI (provider simulato/stub, o cattura dell'esatta trasformazione della forma della richiesta) -- Se è intrinsecamente solo live (rate limit, policy di auth), mantieni il test live ristretto e opt-in tramite variabili env +- Aggiungi una regressione sicura per CI se possibile, provider simulato/stub oppure acquisizione dell'esatta trasformazione della forma della richiesta +- Se è intrinsecamente solo live, rate limit, policy di autenticazione, mantieni il test live ristretto e opt-in tramite variabili env - Preferisci puntare al livello più piccolo che intercetta il bug: - - bug nella conversione/riproduzione della richiesta del provider → test modelli diretti - - bug nella pipeline gateway session/history/tool → gateway live smoke o test gateway simulato sicuro per CI -- Guardrail sull'attraversamento SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva un target campionato per classe SecretRef dai metadati del registro (`listSecretTargetRegistryEntries()`), quindi verifica che gli id exec dei segmenti di attraversamento vengano rifiutati. + - bug di conversione/replay della richiesta del provider → test direct models + - bug della pipeline gateway sessione/cronologia/tool → gateway live smoke o test mock del gateway sicuro per CI +- Guardrail di attraversamento SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` ricava un target campionato per classe SecretRef dai metadati del registro, `listSecretTargetRegistryEntries()`, poi 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 sugli id target non classificati così le nuove classi non possono essere saltate in silenzio. diff --git a/docs/it/reference/memory-config.md b/docs/it/reference/memory-config.md index b50145444..6d008e7e2 100644 --- a/docs/it/reference/memory-config.md +++ b/docs/it/reference/memory-config.md @@ -1,43 +1,54 @@ --- read_when: - - Vuoi configurare provider di memory search o modelli di embedding + - Vuoi configurare i provider di ricerca nella memoria o i modelli di embedding - Vuoi configurare il backend QMD - - Vuoi regolare la ricerca ibrida, MMR o il decadimento temporale - - Vuoi abilitare l'indicizzazione memory multimodale -summary: Tutte le opzioni di configurazione per memory search, provider di embedding, QMD, ricerca ibrida e indicizzazione multimodale -title: Riferimento della configurazione memory + - Vuoi ottimizzare la ricerca ibrida, MMR o il decadimento temporale + - Vuoi abilitare l'indicizzazione multimodale della memoria +summary: Tutte le opzioni di configurazione per la ricerca nella memoria, i provider di embedding, QMD, la ricerca ibrida e l'indicizzazione multimodale +title: Riferimento della configurazione della memoria x-i18n: - generated_at: "2026-04-06T03:12:17Z" + generated_at: "2026-04-10T08:13:49Z" model: gpt-5.4 provider: openai - source_hash: 0de0b85125443584f4e575cf673ca8d9bd12ecd849d73c537f4a17545afa93fd + source_hash: 5f9076bdfad95b87bd70625821bf401326f8eaeb53842b70823881419dbe43cb source_path: reference/memory-config.md workflow: 15 --- -# Riferimento della configurazione memory +# Riferimento della configurazione della memoria -Questa pagina elenca ogni opzione di configurazione per memory search 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 memory](/it/concepts/memory) -- come funziona memory +- [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 -- [Memory Search](/it/concepts/memory-search) -- pipeline di ricerca e regolazione +- [Motore QMD](/it/concepts/memory-qmd) -- sidecar locale-first +- [Ricerca nella memoria](/it/concepts/memory-search) -- pipeline di ricerca e ottimizzazione +- [Memoria attiva](/it/concepts/active-memory) -- abilitazione del sub-agente di memoria per sessioni interattive -Tutte le impostazioni di memory search si trovano in `agents.defaults.memorySearch` in +Tutte le impostazioni della ricerca nella memoria si trovano in `agents.defaults.memorySearch` in `openclaw.json`, salvo diversa indicazione. +Se stai cercando l'interruttore della funzionalità **memoria attiva** e la configurazione del sub-agente, +si trovano in `plugins.entries.active-memory` invece che in `memorySearch`. + +La memoria attiva usa un modello a due condizioni: + +1. il plugin deve essere abilitato e avere come destinazione l'ID dell'agente corrente +2. la richiesta deve essere una sessione di chat interattiva persistente idonea + +Vedi [Memoria attiva](/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 | +| Chiave | Tipo | Predefinito | Descrizione | | ---------- | --------- | ---------------- | ------------------------------------------------------------------------------------------ | -| `provider` | `string` | rilevato automaticamente | ID adattatore di embedding: `openai`, `gemini`, `voyage`, `mistral`, `bedrock`, `ollama`, `local` | +| `provider` | `string` | rilevato automaticamente | ID dell'adapter di embedding: `openai`, `gemini`, `voyage`, `mistral`, `bedrock`, `ollama`, `local` | | `model` | `string` | predefinito del provider | Nome del modello di embedding | -| `fallback` | `string` | `"none"` | ID adattatore di fallback quando il primario fallisce | -| `enabled` | `boolean` | `true` | Abilita o disabilita memory search | +| `fallback` | `string` | `"none"` | ID dell'adapter di fallback quando quello primario fallisce | +| `enabled` | `boolean` | `true` | Abilita o disabilita la ricerca nella memoria | ### Ordine di rilevamento automatico @@ -48,26 +59,26 @@ Quando `provider` non è impostato, OpenClaw seleziona il primo disponibile: 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 AWS SDK viene risolta (ruolo istanza, chiavi di accesso, profilo, SSO, web identity o configurazione condivisa). +6. `bedrock` -- se la catena di credenziali dell'SDK AWS viene risolta (ruolo dell'istanza, chiavi di accesso, profilo, SSO, web identity 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 predefinita -di credenziali AWS SDK (ruoli istanza, SSO, chiavi di accesso). +Gli embeddings remoti richiedono una chiave API. Bedrock usa invece la catena +di credenziali predefinita dell'SDK AWS (ruoli dell'istanza, SSO, chiavi di accesso). -| Provider | Variabile d'ambiente | Chiave di configurazione | -| -------- | ---------------------------- | --------------------------------- | -| 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 | +| -------- | ------------------------------ | --------------------------------- | +| 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) | -- | -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 embedding. --- @@ -75,11 +86,11 @@ richieste di embedding. Per endpoint personalizzati compatibili con OpenAI o per sovrascrivere 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) | +| Chiave | Tipo | Descrizione | +| ---------------- | -------- | ------------------------------------------------ | +| `remote.baseUrl` | `string` | URL base API personalizzato | +| `remote.apiKey` | `string` | Sovrascrive la chiave API | +| `remote.headers` | `object` | Header HTTP aggiuntivi (uniti a quelli predefiniti del provider) | ```json5 { @@ -102,21 +113,21 @@ Per endpoint personalizzati compatibili con OpenAI o per sovrascrivere i valori ## Configurazione specifica di Gemini -| Chiave | Tipo | Predefinito | Descrizione | -| ---------------------- | -------- | ---------------------- | ------------------------------------------ | +| Chiave | Tipo | Predefinito | Descrizione | +| ---------------------- | -------- | --------------------- | ------------------------------------------ | | `model` | `string` | `gemini-embedding-001` | Supporta anche `gemini-embedding-2-preview` | -| `outputDimensionality` | `number` | `3072` | Per Embedding 2: 768, 1536 o 3072 | +| `outputDimensionality` | `number` | `3072` | Per Embedding 2: 768, 1536 o 3072 | -Cambiare il modello o `outputDimensionality` attiva automaticamente una reindicizzazione completa. +La modifica di `model` o `outputDimensionality` attiva automaticamente una reindicizzazione completa. --- ## Configurazione degli embedding Bedrock -Bedrock usa la catena predefinita di credenziali AWS SDK -- non servono chiavi API. -Se OpenClaw viene eseguito su EC2 con un ruolo di istanza Bedrock-enabled, basta impostare +Bedrock usa la catena di credenziali predefinita dell'SDK AWS -- non servono chiavi API. +Se OpenClaw viene eseguito su EC2 con un ruolo dell'istanza abilitato per Bedrock, imposta semplicemente provider e modello: ```json5 @@ -132,48 +143,48 @@ provider e modello: } ``` -| Chiave | Tipo | Predefinito | Descrizione | -| ---------------------- | -------- | ------------------------------ | ------------------------------ | -| `model` | `string` | `amazon.titan-embed-text-v2:0` | Qualsiasi ID modello embedding Bedrock | -| `outputDimensionality` | `number` | predefinito del modello | Per Titan V2: 256, 512 o 1024 | +| Chiave | Tipo | Predefinito | Descrizione | +| ---------------------- | -------- | ----------------------------- | ------------------------------ | +| `model` | `string` | `amazon.titan-embed-text-v2:0` | Qualsiasi ID di modello di embedding 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 predefiniti -delle dimensioni): +Sono supportati i seguenti modelli (con rilevamento della famiglia e dimensioni +predefinite): -| 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 | 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 | -- | Le varianti con suffisso di throughput (ad esempio `amazon.titan-embed-text-v1:2:8k`) ereditano -la configurazione del modello base. +la configurazione del modello di base. ### Autenticazione -L'autenticazione Bedrock usa l'ordine standard di risoluzione delle credenziali AWS SDK: +L'autenticazione Bedrock usa l'ordine standard di risoluzione delle credenziali dell'SDK AWS: 1. Variabili d'ambiente (`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`) 2. Cache dei token SSO 3. Credenziali del token web identity 4. File condivisi di credenziali e configurazione -5. Credenziali 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 `us-east-1` come predefinito. +`baseUrl` del provider `amazon-bedrock`, oppure per impostazione predefinita da `us-east-1`. ### Permessi IAM -Il ruolo o l'utente IAM richiede: +Il ruolo o l'utente IAM deve avere: ```json { @@ -193,42 +204,42 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0 ## Configurazione degli embedding locali -| Chiave | Tipo | Predefinito | Descrizione | -| --------------------- | -------- | ------------------------ | ----------------------------- | -| `local.modelPath` | `string` | scaricato automaticamente | Percorso del file modello GGUF | +| Chiave | Tipo | Predefinito | Descrizione | +| --------------------- | -------- | ------------------------ | ----------------------------------- | +| `local.modelPath` | `string` | scaricato automaticamente | Percorso del file del modello GGUF | | `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`. +Richiede una build nativa: `pnpm approve-builds` poi `pnpm rebuild node-llama-cpp`. --- ## Configurazione della ricerca ibrida -Tutto in `memorySearch.query.hybrid`: +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 dei punteggi vettoriali (0-1) | -| `textWeight` | `number` | `0.3` | Peso dei punteggi BM25 (0-1) | +| `vectorWeight` | `number` | `0.7` | Peso per i punteggi vettoriali (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à) -| Chiave | Tipo | Predefinito | Descrizione | -| ------------- | --------- | ----------- | ---------------------------------------- | -| `mmr.enabled` | `boolean` | `false` | Abilita il riordinamento MMR | -| `mmr.lambda` | `number` | `0.7` | 0 = massima diversità, 1 = massima rilevanza | +| Chiave | Tipo | Predefinito | Descrizione | +| ------------- | --------- | ----------- | ----------------------------------------- | +| `mmr.enabled` | `boolean` | `false` | Abilita il riordinamento MMR | +| `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 di recency | +| `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 non datati in `memory/`) non decadono mai. +I file sempre validi (`MEMORY.md`, file non datati in `memory/`) non subiscono mai decadimento. ### Esempio completo @@ -253,7 +264,7 @@ I file evergreen (`MEMORY.md`, file non datati in `memory/`) non decadono mai. --- -## Percorsi memory aggiuntivi +## Percorsi di memoria aggiuntivi | Chiave | Tipo | Descrizione | | ------------ | ---------- | ---------------------------------------- | @@ -273,10 +284,10 @@ I file evergreen (`MEMORY.md`, file non datati in `memory/`) non decadono mai. I percorsi possono essere assoluti o relativi al workspace. Le directory vengono analizzate ricorsivamente per i file `.md`. La gestione dei symlink dipende dal backend attivo: -il motore integrato ignora i symlink, 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 transcript cross-agent scoped per agente, usa +Per la ricerca nelle trascrizioni cross-agent 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 preservare nomi condivisi espliciti quando il percorso @@ -287,17 +298,17 @@ duplicato. --- -## Memory multimodale (Gemini) +## Memoria multimodale (Gemini) -Indicizza immagini e audio insieme a Markdown usando Gemini Embedding 2: +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"]` o `["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 memory predefinite restano solo Markdown. +Si applica solo ai file in `extraPaths`. Le radici di memoria predefinite restano solo Markdown. Richiede `gemini-embedding-2-preview`. `fallback` deve essere `"none"`. Formati supportati: `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.heic`, `.heif` @@ -307,65 +318,65 @@ Formati supportati: `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.heic`, `.heif` ## Cache degli embedding -| Chiave | Tipo | Predefinito | Descrizione | -| ------------------ | --------- | ----------- | ----------------------------------- | -| `cache.enabled` | `boolean` | `false` | Memorizza nella 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 in cache | -Impedisce il ri-embedding del testo invariato durante reindicizzazione o aggiornamenti dei transcript. +Evita di ricalcolare gli embedding 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 embedding 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 è di solito -il più rapido ed economico per grandi backfill. +Disponibile per `openai`, `gemini` e `voyage`. Il batch OpenAI è in genere +il più rapido e conveniente per grandi backfill. --- -## Session memory search (sperimentale) +## Ricerca nella memoria di sessione (sperimentale) -Indicizza i transcript di sessione e li 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 i transcript | -| `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 -obsoleti. I log di sessione vivono su disco, quindi considera l'accesso al filesystem come il -confine di trust. +L'indicizzazione delle sessioni è su base opt-in e viene eseguita in modo asincrono. I risultati possono essere leggermente +non aggiornati. I log delle sessioni sono archiviati su disco, quindi considera l'accesso al filesystem come confine +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` | bundled | Sovrascrive il percorso sqlite-vec | +| Chiave | Tipo | Predefinito | Descrizione | +| -------------------------- | --------- | ----------- | -------------------------------------- | +| `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 ripiega automaticamente sulla +Quando `sqlite-vec` non è disponibile, OpenClaw usa automaticamente come fallback la 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`) | --- @@ -380,17 +391,18 @@ Imposta `memory.backend = "qmd"` per abilitarlo. Tutte le impostazioni QMD si tr | `searchMode` | `string` | `search` | Comando di ricerca: `search`, `vsearch`, `query` | | `includeDefaultMemory` | `boolean` | `true` | Indicizza automaticamente `MEMORY.md` + `memory/**/*.md` | | `paths[]` | `array` | -- | Percorsi aggiuntivi: `{ name, path, pattern? }` | -| `sessions.enabled` | `boolean` | `false` | Indicizza i transcript di sessione | -| `sessions.retentionDays` | `number` | -- | Conservazione dei transcript | +| `sessions.enabled` | `boolean` | `false` | Indicizza le trascrizioni delle sessioni | +| `sessions.retentionDays` | `number` | -- | Conservazione delle trascrizioni | | `sessions.exportDir` | `string` | -- | Directory di esportazione | -OpenClaw preferisce le attuali forme di raccolta QMD e query MCP, ma mantiene -funzionanti le versioni QMD meno recenti ripiegando sui flag legacy di raccolta `--mask` -e sui vecchi nomi degli strumenti MCP quando necessario. +OpenClaw preferisce le forme correnti delle raccolte QMD e delle query MCP, ma mantiene +compatibili anche le versioni meno recenti di QMD usando come fallback i flag legacy di raccolta `--mask` +e i vecchi nomi 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 runtime del gateway. +`QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` e `QMD_GENERATE_MODEL` nell'ambiente di runtime +del gateway. ### Pianificazione degli aggiornamenti @@ -414,7 +426,7 @@ sovrascrivere globalmente i modelli di QMD, imposta variabili d'ambiente come | `limits.maxInjectedChars` | `number` | -- | Limita il totale dei caratteri iniettati | | `limits.timeoutMs` | `number` | `4000` | Timeout della ricerca | -### Scope +### Ambito Controlla quali sessioni possono ricevere risultati di ricerca QMD. Stesso schema di [`session.sendPolicy`](/it/gateway/configuration-reference#session): @@ -432,17 +444,17 @@ Controlla quali sessioni possono ricevere risultati di ricerca QMD. Stesso schem } ``` -Il valore predefinito è solo DM. `match.keyPrefix` corrisponde alla chiave di sessione normalizzata; -`match.rawKeyPrefix` corrisponde alla chiave raw inclusa `agent::`. +L'impostazione predefinita è solo DM. `match.keyPrefix` corrisponde alla chiave di sessione normalizzata; +`match.rawKeyPrefix` corrisponde alla chiave grezza che include `agent::`. ### Citazioni `memory.citations` si applica a tutti i backend: -| Valore | Comportamento | -| ---------------- | --------------------------------------------------- | +| Valore | Comportamento | +| ---------------- | -------------------------------------------------- | | `auto` (predefinito) | Include il footer `Source: ` negli snippet | -| `on` | Include sempre il footer | +| `on` | Include sempre il footer | | `off` | Omette il footer (il percorso viene comunque passato internamente all'agente) | ### Esempio completo QMD @@ -470,20 +482,20 @@ Il valore predefinito è solo DM. `match.keyPrefix` corrisponde alla chiave di s ## Dreaming (sperimentale) -Dreaming viene configurato in `plugins.entries.memory-core.config.dreaming`, +Dreaming è configurato in `plugins.entries.memory-core.config.dreaming`, non in `agents.defaults.memorySearch`. -Dreaming viene eseguito come una scansione pianificata unica e usa fasi interne light/deep/REM come +Dreaming viene eseguito come una singola esecuzione pianificata e usa fasi interne light/deep/REM come dettaglio di implementazione. -Per il comportamento concettuale e i comandi slash, vedi [Dreaming](/concepts/dreaming). +Per il comportamento concettuale e i comandi slash, vedi [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 facoltativa per l'esecuzione completa di Dreaming | ### Esempio @@ -506,6 +518,6 @@ Per il comportamento concettuale e i comandi slash, vedi [Dreaming](/concepts/dr Note: -- Dreaming scrive lo stato della macchina in `memory/.dreams/`. -- Dreaming scrive output narrativo leggibile da esseri umani in `DREAMS.md` (o nell'esistente `dreams.md`). -- La policy e le soglie delle fasi light/deep/REM sono comportamento interno, non configurazione esposta all'utente. +- Dreaming scrive lo stato macchina in `memory/.dreams/`. +- Dreaming scrive l'output narrativo leggibile dagli esseri umani in `DREAMS.md` (o nell'esistente `dreams.md`). +- La politica e le soglie delle fasi light/deep/REM sono comportamento interno, non configurazione esposta all'utente. diff --git a/docs/it/tools/browser.md b/docs/it/tools/browser.md index 5f3425342..b9c679fa5 100644 --- a/docs/it/tools/browser.md +++ b/docs/it/tools/browser.md @@ -1,22 +1,22 @@ --- read_when: - - Aggiunta di automazione del browser controllata dall'agente - - Debug del motivo per cui openclaw interferisce con il tuo Chrome - - Implementazione delle impostazioni del browser e del ciclo di vita nell'app macOS + - Aggiungere l'automazione del browser controllata dall'agente + - Debuggare il motivo per cui openclaw interferisce con il tuo Chrome + - Implementare impostazioni + ciclo di vita del browser nell'app macOS summary: Servizio di controllo del browser integrato + comandi di azione title: Browser (gestito da OpenClaw) x-i18n: - generated_at: "2026-04-05T14:07:08Z" + generated_at: "2026-04-10T08:14:01Z" model: gpt-5.4 provider: openai - source_hash: a41162efd397ea918469e16aa67e554bcbb517b3112df1d3e7927539b6a0926a + source_hash: cd3424f62178bbf25923b8bc8e4d9f70e330f35428d01fe153574e5fa45d7604 source_path: tools/browser.md workflow: 15 --- # Browser (gestito da openclaw) -OpenClaw può eseguire un **profilo Chrome/Brave/Edge/Chromium dedicato** controllato dall'agente. +OpenClaw può eseguire un **profilo Chrome/Brave/Edge/Chromium dedicato** che l'agente controlla. È isolato dal tuo browser personale ed è gestito tramite un piccolo servizio di controllo locale all'interno del Gateway (solo loopback). @@ -24,18 +24,18 @@ Vista per principianti: - Consideralo come un **browser separato, solo per l'agente**. - Il profilo `openclaw` **non** tocca il profilo del tuo browser personale. -- L'agente può **aprire schede, leggere pagine, fare clic e digitare** in un percorso sicuro. -- Il profilo integrato `user` si collega alla tua vera sessione Chrome autenticata tramite Chrome MCP. +- L'agente può **aprire schede, leggere pagine, fare clic e digitare** in una lane sicura. +- Il profilo `user` integrato si collega alla tua vera sessione Chrome con accesso effettuato tramite Chrome MCP. ## Cosa ottieni - Un profilo browser separato chiamato **openclaw** (accento arancione per impostazione predefinita). -- Controllo deterministico delle schede (elenco/apri/metti a fuoco/chiudi). -- Azioni dell'agente (clic/digita/trascina/seleziona), snapshot, screenshot, PDF. +- Controllo deterministico delle schede (elencare/aprire/mettere a fuoco/chiudere). +- Azioni dell'agente (clic/digitazione/trascinamento/selezione), snapshot, screenshot, PDF. - Supporto opzionale per più profili (`openclaw`, `work`, `remote`, ...). Questo browser **non** è il tuo browser quotidiano. È una superficie sicura e isolata per -l'automazione e la verifica da parte dell'agente. +l'automazione e la verifica dell'agente. ## Avvio rapido @@ -50,11 +50,11 @@ Se ricevi “Browser disabled”, abilitalo nella configurazione (vedi sotto) e Gateway. Se `openclaw browser` manca del tutto, oppure l'agente dice che lo strumento browser -non è disponibile, vai a [Comando o strumento browser mancante](/tools/browser#missing-browser-command-or-tool). +non è disponibile, vai a [Comando o strumento browser mancante](/it/tools/browser#missing-browser-command-or-tool). ## Controllo del plugin -Lo strumento `browser` predefinito ora è un plugin incluso che viene distribuito abilitato per +Lo strumento predefinito `browser` ora è un plugin bundle che viene distribuito abilitato per impostazione predefinita. Questo significa che puoi disabilitarlo o sostituirlo senza rimuovere il resto del sistema di plugin di OpenClaw: @@ -70,33 +70,33 @@ sistema di plugin di OpenClaw: } ``` -Disabilita il plugin incluso prima di installare un altro plugin che fornisce lo +Disabilita il plugin bundle prima di installare un altro plugin che fornisce lo stesso nome di strumento `browser`. L'esperienza browser predefinita richiede entrambi: - `plugins.entries.browser.enabled` non disabilitato - `browser.enabled=true` -Se disattivi solo il plugin, la CLI browser inclusa (`openclaw browser`), -il metodo gateway (`browser.request`), lo strumento dell'agente e il servizio di controllo browser -predefinito scompaiono tutti insieme. La tua configurazione `browser.*` rimane intatta per essere riutilizzata da un -plugin sostitutivo. +Se disattivi solo il plugin, la CLI browser bundle (`openclaw browser`), +il metodo gateway (`browser.request`), lo strumento agente e il servizio di controllo browser predefinito +scompaiono tutti insieme. La tua configurazione `browser.*` rimane intatta perché possa essere riutilizzata da +un plugin sostitutivo. -Il plugin browser incluso ora possiede anche l'implementazione runtime del browser. -Il core conserva solo helper condivisi del Plugin SDK più re-export di compatibilità per -vecchi percorsi di importazione interni. In pratica, rimuovere o sostituire il pacchetto plugin browser -rimuove l'insieme delle funzionalità browser invece di lasciare dietro una seconda implementazione runtime -posseduta dal core. +Il plugin browser bundle ora possiede anche l'implementazione runtime del browser. +Il core mantiene solo helper condivisi del Plugin SDK più re-export di compatibilità per +i vecchi percorsi di import interni. In pratica, rimuovere o sostituire il pacchetto del plugin browser +rimuove l'insieme di funzionalità del browser invece di lasciare dietro un secondo runtime posseduto dal +core. -Le modifiche alla configurazione del browser richiedono comunque un riavvio del Gateway affinché il plugin incluso -possa registrare nuovamente il suo servizio browser con le nuove impostazioni. +Le modifiche alla configurazione del browser richiedono comunque un riavvio del Gateway in modo che il plugin bundle +possa registrare di nuovo il suo servizio browser con le nuove impostazioni. ## Comando o strumento browser mancante Se `openclaw browser` diventa improvvisamente un comando sconosciuto dopo un aggiornamento, oppure -l'agente segnala che lo strumento browser manca, la causa più comune è una -lista `plugins.allow` restrittiva che non include `browser`. +l'agente segnala che manca lo strumento browser, la causa più comune è un elenco `plugins.allow` +restrittivo che non include `browser`. -Esempio di configurazione errata: +Esempio di configurazione non funzionante: ```json5 { @@ -106,7 +106,7 @@ Esempio di configurazione errata: } ``` -Correggila aggiungendo `browser` alla allowlist dei plugin: +Correggilo aggiungendo `browser` alla allowlist dei plugin: ```json5 { @@ -120,8 +120,8 @@ Note importanti: - `browser.enabled=true` da solo non è sufficiente quando è impostato `plugins.allow`. - Anche `plugins.entries.browser.enabled=true` da solo non è sufficiente quando è impostato `plugins.allow`. -- `tools.alsoAllow: ["browser"]` **non** carica il plugin browser incluso. Regola soltanto la policy degli strumenti dopo che il plugin è già stato caricato. -- Se non hai bisogno di una allowlist restrittiva dei plugin, rimuovere `plugins.allow` ripristina anche il comportamento predefinito del browser incluso. +- `tools.alsoAllow: ["browser"]` **non** carica il plugin browser bundle. Regola solo la policy degli strumenti dopo che il plugin è già stato caricato. +- Se non hai bisogno di una allowlist plugin restrittiva, rimuovere `plugins.allow` ripristina anche il comportamento browser bundle predefinito. Sintomi tipici: @@ -132,16 +132,16 @@ Sintomi tipici: ## Profili: `openclaw` vs `user` - `openclaw`: browser gestito e isolato (nessuna estensione richiesta). -- `user`: profilo di collegamento Chrome MCP integrato per la tua **vera sessione Chrome autenticata**. +- `user`: profilo integrato di collegamento Chrome MCP per la tua **vera sessione Chrome con accesso effettuato**. Per le chiamate allo strumento browser dell'agente: - Predefinito: usa il browser isolato `openclaw`. -- Preferisci `profile="user"` quando le sessioni già autenticate sono importanti e l'utente - è al computer per fare clic/approvare eventuali richieste di collegamento. -- `profile` è la sovrascrittura esplicita quando vuoi una modalità browser specifica. +- Preferisci `profile="user"` quando contano le sessioni già connesse e l'utente + è al computer per fare clic/approvare eventuali prompt di collegamento. +- `profile` è la sostituzione esplicita quando vuoi una modalità browser specifica. -Imposta `browser.defaultProfile: "openclaw"` se vuoi la modalità gestita come predefinita. +Imposta `browser.defaultProfile: "openclaw"` se vuoi la modalità gestita per impostazione predefinita. ## Configurazione @@ -150,14 +150,14 @@ Le impostazioni del browser si trovano in `~/.openclaw/openclaw.json`. ```json5 { browser: { - enabled: true, // default: true + enabled: true, // predefinito: true ssrfPolicy: { dangerouslyAllowPrivateNetwork: true, // modalità trusted-network predefinita // allowPrivateNetwork: true, // alias legacy // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, - // cdpUrl: "http://127.0.0.1:18792", // sovrascrittura legacy per profilo singolo + // cdpUrl: "http://127.0.0.1:18792", // sostituzione legacy a profilo singolo remoteCdpTimeoutMs: 1500, // timeout HTTP CDP remoto (ms) remoteCdpHandshakeTimeoutMs: 3000, // timeout handshake WebSocket CDP remoto (ms) defaultProfile: "openclaw", @@ -188,32 +188,32 @@ Le impostazioni del browser si trovano in `~/.openclaw/openclaw.json`. Note: -- Il servizio di controllo browser si collega al loopback su una porta derivata da `gateway.port` - (predefinita: `18791`, che corrisponde a gateway + 2). -- Se sovrascrivi la porta del Gateway (`gateway.port` o `OPENCLAW_GATEWAY_PORT`), - le porte browser derivate si spostano per rimanere nella stessa “famiglia”. +- Il servizio di controllo del browser si collega a loopback su una porta derivata da `gateway.port` + (predefinita: `18791`, che è gateway + 2). +- Se sostituisci la porta del Gateway (`gateway.port` o `OPENCLAW_GATEWAY_PORT`), + le porte browser derivate cambiano per rimanere nella stessa “famiglia”. - `cdpUrl` usa per impostazione predefinita la porta CDP locale gestita quando non è impostato. -- `remoteCdpTimeoutMs` si applica ai controlli di raggiungibilità CDP remota (non loopback). -- `remoteCdpHandshakeTimeoutMs` si applica ai controlli di raggiungibilità WebSocket CDP remoti. -- La navigazione/apertura scheda del browser è protetta contro SSRF prima della navigazione e ricontrollata al meglio sull'URL finale `http(s)` dopo la navigazione. -- In modalità SSRF rigida vengono controllati anche il rilevamento/sonde degli endpoint CDP remoti (`cdpUrl`, incluse le ricerche `/json/version`). -- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` è `true` per impostazione predefinita (modello trusted-network). Impostalo su `false` per una navigazione rigorosa solo pubblica. -- `browser.ssrfPolicy.allowPrivateNetwork` resta supportato come alias legacy per compatibilità. +- `remoteCdpTimeoutMs` si applica ai controlli di raggiungibilità CDP remoti (non loopback). +- `remoteCdpHandshakeTimeoutMs` si applica ai controlli di raggiungibilità handshake WebSocket CDP remoti. +- La navigazione/apertura di schede del browser è protetta da SSRF prima della navigazione e ricontrollata con la massima accuratezza possibile sull'URL `http(s)` finale dopo la navigazione. +- In modalità SSRF rigorosa, anche il rilevamento/i probe degli endpoint CDP remoti (`cdpUrl`, incluse le ricerche `/json/version`) vengono controllati. +- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` usa per impostazione predefinita `true` (modello trusted-network). Impostalo su `false` per una navigazione rigorosa solo pubblica. +- `browser.ssrfPolicy.allowPrivateNetwork` rimane supportato come alias legacy per compatibilità. - `attachOnly: true` significa “non avviare mai un browser locale; collegarsi solo se è già in esecuzione.” -- `color` + `color` per profilo colorano l'interfaccia del browser così puoi vedere quale profilo è attivo. -- Il profilo predefinito è `openclaw` (browser standalone gestito da OpenClaw). Usa `defaultProfile: "user"` per scegliere il browser utente autenticato. -- Ordine di rilevamento automatico: browser predefinito di sistema se basato su Chromium; altrimenti Chrome → Brave → Edge → Chromium → Chrome Canary. -- I profili `openclaw` locali assegnano automaticamente `cdpPort`/`cdpUrl` — impostali solo per CDP remoto. -- `driver: "existing-session"` usa Chrome DevTools MCP invece del CDP grezzo. Non +- `color` + `color` per profilo colorano l'interfaccia del browser in modo che tu possa vedere quale profilo è attivo. +- Il profilo predefinito è `openclaw` (browser standalone gestito da OpenClaw). Usa `defaultProfile: "user"` per scegliere il browser dell'utente con accesso effettuato. +- Ordine di rilevamento automatico: browser di sistema predefinito se basato su Chromium; altrimenti Chrome → Brave → Edge → Chromium → Chrome Canary. +- I profili locali `openclaw` assegnano automaticamente `cdpPort`/`cdpUrl` — impostali solo per CDP remoto. +- `driver: "existing-session"` usa Chrome DevTools MCP invece di CDP raw. Non impostare `cdpUrl` per quel driver. - Imposta `browser.profiles..userDataDir` quando un profilo existing-session deve collegarsi a un profilo utente Chromium non predefinito come Brave o Edge. ## Usare Brave (o un altro browser basato su Chromium) -Se il tuo browser **predefinito di sistema** è basato su Chromium (Chrome/Brave/Edge/ecc.), -OpenClaw lo usa automaticamente. Imposta `browser.executablePath` per sovrascrivere il -rilevamento automatico: +Se il tuo browser **di sistema predefinito** è basato su Chromium (Chrome/Brave/Edge/ecc.), +OpenClaw lo usa automaticamente. Imposta `browser.executablePath` per sostituire +il rilevamento automatico: Esempio CLI: @@ -246,9 +246,9 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome" ## Controllo locale vs remoto -- **Controllo locale (predefinito):** il Gateway avvia il servizio di controllo loopback e può avviare un browser locale. -- **Controllo remoto (host del nodo):** esegui un host del nodo sulla macchina che ha il browser; il Gateway inoltra le azioni del browser a esso. -- **CDP remoto:** imposta `browser.profiles..cdpUrl` (oppure `browser.cdpUrl`) per +- **Controllo locale (predefinito):** il Gateway avvia il servizio di controllo loopback e può lanciare un browser locale. +- **Controllo remoto (host nodo):** esegui un host nodo sulla macchina che ha il browser; il Gateway instrada tramite proxy le azioni del browser verso di esso. +- **CDP remoto:** imposta `browser.profiles..cdpUrl` (o `browser.cdpUrl`) per collegarti a un browser remoto basato su Chromium. In questo caso, OpenClaw non avvierà un browser locale. Il comportamento di arresto varia in base alla modalità del profilo: @@ -256,31 +256,31 @@ Il comportamento di arresto varia in base alla modalità del profilo: - profili gestiti locali: `openclaw browser stop` arresta il processo browser che OpenClaw ha avviato - profili attach-only e CDP remoti: `openclaw browser stop` chiude la sessione di - controllo attiva e rilascia le sovrascritture di emulazione Playwright/CDP (viewport, - schema colori, impostazioni locali, fuso orario, modalità offline e stato simile), anche + controllo attiva e rilascia le sostituzioni di emulazione Playwright/CDP (viewport, + schema di colori, lingua, fuso orario, modalità offline e stato simile), anche se nessun processo browser è stato avviato da OpenClaw Gli URL CDP remoti possono includere autenticazione: -- Token in query (ad es. `https://provider.example?token=`) -- HTTP Basic auth (ad es. `https://user:pass@provider.example`) +- Token di query (ad esempio `https://provider.example?token=`) +- Autenticazione HTTP Basic (ad esempio `https://user:pass@provider.example`) OpenClaw preserva l'autenticazione quando chiama gli endpoint `/json/*` e quando si collega -al WebSocket CDP. Preferisci variabili d'ambiente o gestori di segreti per i -token invece di salvarli nei file di configurazione. +al WebSocket CDP. Preferisci variabili di ambiente o gestori di segreti per i +token invece di eseguirne il commit nei file di configurazione. ## Proxy browser del nodo (predefinito zero-config) -Se esegui un **host del nodo** sulla macchina che ha il browser, OpenClaw può +Se esegui un **host nodo** sulla macchina che ha il tuo browser, OpenClaw può instradare automaticamente le chiamate allo strumento browser verso quel nodo senza alcuna configurazione browser aggiuntiva. -Questo è il percorso predefinito per i Gateway remoti. +Questo è il percorso predefinito per i gateway remoti. Note: -- L'host del nodo espone il proprio server locale di controllo browser tramite un **comando proxy**. +- L'host nodo espone il suo server locale di controllo browser tramite un **comando proxy**. - I profili provengono dalla configurazione `browser.profiles` del nodo stesso (uguale a quella locale). -- `nodeHost.browserProxy.allowProfiles` è facoltativo. Lascialo vuoto per il comportamento legacy/predefinito: tutti i profili configurati restano raggiungibili tramite il proxy, comprese le route di creazione/eliminazione profilo. -- Se imposti `nodeHost.browserProxy.allowProfiles`, OpenClaw lo tratta come un confine di privilegio minimo: solo i profili nella allowlist possono essere destinati e le route persistenti di creazione/eliminazione profilo vengono bloccate sulla superficie proxy. +- `nodeHost.browserProxy.allowProfiles` è opzionale. Lascialo vuoto per il comportamento legacy/predefinito: tutti i profili configurati restano raggiungibili tramite il proxy, incluse le route di creazione/eliminazione dei profili. +- Se imposti `nodeHost.browserProxy.allowProfiles`, OpenClaw lo tratta come un confine di privilegio minimo: solo i profili nella allowlist possono essere selezionati, e le route di creazione/eliminazione dei profili persistenti vengono bloccate sulla superficie proxy. - Disabilitalo se non lo vuoi: - Sul nodo: `nodeHost.browserProxy.enabled=false` - Sul gateway: `gateway.nodes.browser.mode="off"` @@ -288,7 +288,7 @@ Note: ## Browserless (CDP remoto ospitato) [Browserless](https://browserless.io) è un servizio Chromium ospitato che espone -URL di connessione CDP tramite HTTPS e WebSocket. OpenClaw può usare entrambe le forme, ma +URL di connessione CDP su HTTPS e WebSocket. OpenClaw può usare entrambe le forme, ma per un profilo browser remoto l'opzione più semplice è l'URL WebSocket diretto dalla documentazione di connessione di Browserless. @@ -314,19 +314,19 @@ Esempio: Note: - Sostituisci `` con il tuo vero token Browserless. -- Scegli l'endpoint regionale corrispondente al tuo account Browserless (vedi la loro documentazione). +- Scegli l'endpoint regionale che corrisponde al tuo account Browserless (vedi la loro documentazione). - Se Browserless ti fornisce un URL base HTTPS, puoi convertirlo in `wss://` per una connessione CDP diretta oppure mantenere l'URL HTTPS e lasciare che OpenClaw - scopra `/json/version`. + rilevi `/json/version`. -## Provider CDP WebSocket diretti +## Provider CDP WebSocket diretto -Alcuni servizi browser ospitati espongono un endpoint **WebSocket diretto** invece -del rilevamento CDP standard basato su HTTP (`/json/version`). OpenClaw supporta entrambi: +Alcuni servizi browser ospitati espongono un endpoint **WebSocket diretto** invece del +rilevamento CDP standard basato su HTTP (`/json/version`). OpenClaw supporta entrambe le forme: -- **Endpoint HTTP(S)** — OpenClaw chiama `/json/version` per scoprire l'URL - WebSocket del debugger, quindi si collega. -- **Endpoint WebSocket** (`ws://` / `wss://`) — OpenClaw si collega direttamente, +- **Endpoint HTTP(S)** — OpenClaw chiama `/json/version` per rilevare l'URL + del debugger WebSocket, quindi si connette. +- **Endpoint WebSocket** (`ws://` / `wss://`) — OpenClaw si connette direttamente, saltando `/json/version`. Usalo per servizi come [Browserless](https://browserless.io), [Browserbase](https://www.browserbase.com), o qualsiasi provider che ti fornisca un @@ -335,8 +335,8 @@ del rilevamento CDP standard basato su HTTP (`/json/version`). OpenClaw supporta ### Browserbase [Browserbase](https://www.browserbase.com) è una piattaforma cloud per eseguire -browser headless con risoluzione CAPTCHA integrata, modalità stealth e -proxy residenziali. +browser headless con risoluzione CAPTCHA integrata, modalità stealth e proxy +residenziali. ```json5 { @@ -359,58 +359,58 @@ Note: - [Registrati](https://www.browserbase.com/sign-up) e copia la tua **API Key** dalla [dashboard Overview](https://www.browserbase.com/overview). -- Sostituisci `` con la tua vera chiave API Browserbase. +- Sostituisci `` con la tua vera API key Browserbase. - Browserbase crea automaticamente una sessione browser alla connessione WebSocket, quindi - non è necessario alcun passaggio manuale di creazione sessione. -- Il livello gratuito consente una sessione concorrente e un'ora di browser al mese. + non è necessario alcun passaggio manuale di creazione della sessione. +- Il piano gratuito consente una sessione concorrente e un'ora browser al mese. Vedi i [prezzi](https://www.browserbase.com/pricing) per i limiti dei piani a pagamento. -- Consulta la [documentazione Browserbase](https://docs.browserbase.com) per il riferimento API - completo, le guide SDK e gli esempi di integrazione. +- Consulta la [documentazione Browserbase](https://docs.browserbase.com) per il riferimento + API completo, le guide SDK e gli esempi di integrazione. ## Sicurezza Concetti chiave: -- Il controllo browser è solo loopback; l'accesso passa tramite l'autenticazione del Gateway o l'associazione del nodo. -- L'API HTTP browser standalone su loopback usa **solo autenticazione con segreto condiviso**: - autenticazione bearer con token gateway, `x-openclaw-password`, oppure HTTP Basic auth con la +- Il controllo del browser è solo loopback; l'accesso passa tramite l'autenticazione del Gateway o l'abbinamento del nodo. +- L'API HTTP browser loopback standalone usa **solo autenticazione con segreto condiviso**: + auth bearer del token gateway, `x-openclaw-password`, oppure autenticazione HTTP Basic con la password gateway configurata. - Gli header di identità Tailscale Serve e `gateway.auth.mode: "trusted-proxy"` **non** - autenticano questa API browser standalone su loopback. -- Se il controllo browser è abilitato e non è configurata alcuna autenticazione con segreto condiviso, OpenClaw + autenticano questa API browser loopback standalone. +- Se il controllo del browser è abilitato e non è configurata alcuna autenticazione con segreto condiviso, OpenClaw genera automaticamente `gateway.auth.token` all'avvio e lo salva nella configurazione. - OpenClaw **non** genera automaticamente quel token quando `gateway.auth.mode` è già `password`, `none` o `trusted-proxy`. -- Mantieni il Gateway e gli eventuali host del nodo su una rete privata (Tailscale); evita l'esposizione pubblica. -- Tratta URL/token CDP remoti come segreti; preferisci variabili d'ambiente o un gestore di segreti. +- Mantieni il Gateway e qualsiasi host nodo su una rete privata (Tailscale); evita l'esposizione pubblica. +- Tratta gli URL/token CDP remoti come segreti; preferisci variabili di ambiente o un gestore di segreti. Suggerimenti per CDP remoto: -- Preferisci endpoint cifrati (HTTPS o WSS) e token di breve durata quando possibile. -- Evita di incorporare token di lunga durata direttamente nei file di configurazione. +- Preferisci endpoint cifrati (HTTPS o WSS) e token a breve durata quando possibile. +- Evita di incorporare direttamente token a lunga durata nei file di configurazione. -## Profili (multi-browser) +## Profili (browser multipli) OpenClaw supporta più profili nominati (configurazioni di instradamento). I profili possono essere: -- **gestiti da openclaw**: un'istanza browser dedicata basata su Chromium con propria directory dati utente + porta CDP -- **remoti**: un URL CDP esplicito (browser basato su Chromium in esecuzione altrove) -- **sessione esistente**: il tuo profilo Chrome esistente tramite collegamento automatico Chrome DevTools MCP +- **gestiti da openclaw**: un'istanza dedicata di browser basato su Chromium con la propria directory dati utente + porta CDP +- **remoto**: un URL CDP esplicito (browser basato su Chromium in esecuzione altrove) +- **sessione esistente**: il tuo profilo Chrome esistente tramite connessione automatica Chrome DevTools MCP -Predefiniti: +Valori predefiniti: - Il profilo `openclaw` viene creato automaticamente se manca. - Il profilo `user` è integrato per il collegamento existing-session di Chrome MCP. - I profili existing-session sono opt-in oltre a `user`; creali con `--driver existing-session`. -- Le porte CDP locali vengono allocate nell'intervallo **18800–18899** per impostazione predefinita. +- Le porte CDP locali vengono allocate da **18800–18899** per impostazione predefinita. - L'eliminazione di un profilo sposta la sua directory dati locale nel Cestino. Tutti gli endpoint di controllo accettano `?profile=`; la CLI usa `--browser-profile`. ## Existing-session tramite Chrome DevTools MCP -OpenClaw può anche collegarsi a un profilo browser basato su Chromium in esecuzione tramite il -server ufficiale Chrome DevTools MCP. Questo riutilizza le schede e lo stato di accesso +OpenClaw può anche collegarsi a un profilo di browser basato su Chromium già in esecuzione tramite il +server MCP ufficiale di Chrome DevTools. Questo riutilizza le schede e lo stato di accesso già aperti in quel profilo browser. Riferimenti ufficiali di contesto e configurazione: @@ -422,13 +422,13 @@ Profilo integrato: - `user` -Opzionale: crea il tuo profilo existing-session personalizzato se vuoi un -nome, un colore o una directory dati del browser diversi. +Facoltativo: crea il tuo profilo existing-session personalizzato se vuoi un +nome, colore o directory dati browser diversi. Comportamento predefinito: -- Il profilo integrato `user` usa il collegamento automatico Chrome MCP, che punta al - profilo locale predefinito di Google Chrome. +- Il profilo `user` integrato usa la connessione automatica Chrome MCP, che punta al + profilo Google Chrome locale predefinito. Usa `userDataDir` per Brave, Edge, Chromium o un profilo Chrome non predefinito: @@ -451,7 +451,7 @@ Poi, nel browser corrispondente: 1. Apri la pagina inspect di quel browser per il debug remoto. 2. Abilita il debug remoto. -3. Tieni il browser in esecuzione e approva la richiesta di connessione quando OpenClaw si collega. +3. Mantieni il browser in esecuzione e approva il prompt di connessione quando OpenClaw si collega. Pagine inspect comuni: @@ -459,7 +459,7 @@ Pagine inspect comuni: - Brave: `brave://inspect/#remote-debugging` - Edge: `edge://inspect/#remote-debugging` -Smoke test live del collegamento: +Smoke test di collegamento live: ```bash openclaw browser --browser-profile user start @@ -468,73 +468,74 @@ openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot --format ai ``` -Che aspetto ha il successo: +Ecco come si presenta il successo: - `status` mostra `driver: existing-session` - `status` mostra `transport: chrome-mcp` - `status` mostra `running: true` -- `tabs` elenca le tue schede browser già aperte +- `tabs` elenca le schede browser già aperte - `snapshot` restituisce ref dalla scheda live selezionata Cosa controllare se il collegamento non funziona: -- il browser di destinazione basato su Chromium è alla versione `144+` +- il browser basato su Chromium di destinazione è alla versione `144+` - il debug remoto è abilitato nella pagina inspect di quel browser -- il browser ha mostrato e tu hai accettato la richiesta di consenso al collegamento +- il browser ha mostrato il prompt di consenso al collegamento e tu lo hai accettato - `openclaw doctor` migra la vecchia configurazione browser basata su estensione e controlla che - Chrome sia installato localmente per i profili predefiniti con collegamento automatico, ma non può - abilitare il debug remoto lato browser al posto tuo + Chrome sia installato localmente per i profili predefiniti con connessione automatica, ma non può + abilitare per te il debug remoto lato browser Uso da parte dell'agente: -- Usa `profile="user"` quando hai bisogno dello stato del browser autenticato dell'utente. -- Se usi un profilo existing-session personalizzato, passa quel nome di profilo esplicito. -- Scegli questa modalità solo quando l'utente è al computer per approvare la richiesta - di collegamento. -- il Gateway o l'host del nodo possono avviare `npx chrome-devtools-mcp@latest --autoConnect` +- Usa `profile="user"` quando ti serve lo stato del browser dell'utente con accesso effettuato. +- Se usi un profilo existing-session personalizzato, passa quel nome profilo esplicito. +- Scegli questa modalità solo quando l'utente è al computer per approvare il + prompt di collegamento. +- il Gateway o l'host nodo possono avviare `npx chrome-devtools-mcp@latest --autoConnect` Note: -- Questo percorso è più rischioso del profilo isolato `openclaw` perché può - agire all'interno della tua sessione browser autenticata. +- Questo percorso ha un rischio maggiore rispetto al profilo isolato `openclaw` perché può + agire all'interno della tua sessione browser con accesso effettuato. - OpenClaw non avvia il browser per questo driver; si collega solo a una sessione esistente. -- OpenClaw usa qui il flusso ufficiale Chrome DevTools MCP `--autoConnect`. Se - `userDataDir` è impostato, OpenClaw lo passa per puntare a quella specifica - directory dati utente Chromium. -- Gli screenshot existing-session supportano acquisizioni di pagina e acquisizioni di elemento con `--ref` - dagli output snapshot, ma non selettori CSS `--element`. +- OpenClaw usa qui il flusso ufficiale `--autoConnect` di Chrome DevTools MCP. Se + `userDataDir` è impostato, OpenClaw lo passa attraverso per puntare a quella + directory dati utente Chromium esplicita. +- Gli screenshot existing-session supportano catture di pagina e catture di elemento `--ref` + dagli output snapshot, ma non i selettori CSS `--element`. - Gli screenshot di pagina existing-session funzionano senza Playwright tramite Chrome MCP. - Anche gli screenshot di elementi basati su ref (`--ref`) funzionano lì, ma `--full-page` + Anche gli screenshot di elemento basati su ref (`--ref`) funzionano lì, ma `--full-page` non può essere combinato con `--ref` o `--element`. -- Le azioni existing-session sono ancora più limitate rispetto al percorso del browser gestito: +- Le azioni existing-session sono ancora più limitate rispetto al percorso del browser + gestito: - `click`, `type`, `hover`, `scrollIntoView`, `drag` e `select` richiedono - ref dello snapshot invece di selettori CSS - - `click` supporta solo il pulsante sinistro (nessuna sovrascrittura del pulsante o modificatori) + ref snapshot invece dei selettori CSS + - `click` è solo con tasto sinistro (nessuna sostituzione del pulsante o modificatore) - `type` non supporta `slowly=true`; usa `fill` o `press` - `press` non supporta `delayMs` - `hover`, `scrollIntoView`, `drag`, `select`, `fill` ed `evaluate` non - supportano sovrascritture del timeout per chiamata - - `select` al momento supporta un solo valore -- Existing-session `wait --url` supporta pattern esatti, per sottostringa e glob + supportano sostituzioni timeout per chiamata + - `select` attualmente supporta solo un singolo valore +- Existing-session `wait --url` supporta pattern esatti, di sottostringa e glob come gli altri driver browser. `wait --load networkidle` non è ancora supportato. - Gli hook di upload existing-session richiedono `ref` o `inputRef`, supportano un file alla volta e non supportano il targeting CSS `element`. -- Gli hook di dialog existing-session non supportano sovrascritture del timeout. -- Alcune funzionalità richiedono ancora il percorso del browser gestito, incluse azioni batch, - esportazione PDF, intercettazione dei download e `responsebody`. -- Existing-session è locale all'host. Se Chrome si trova su una macchina diversa o in - uno spazio dei nomi di rete diverso, usa invece CDP remoto o un host del nodo. +- Gli hook dialog existing-session non supportano sostituzioni timeout. +- Alcune funzionalità richiedono ancora il percorso browser gestito, tra cui + azioni batch, esportazione PDF, intercettazione download e `responsebody`. +- Existing-session è locale all'host. Se Chrome si trova su un'altra macchina o in un + namespace di rete diverso, usa invece CDP remoto o un host nodo. ## Garanzie di isolamento - **Directory dati utente dedicata**: non tocca mai il profilo del tuo browser personale. - **Porte dedicate**: evita `9222` per prevenire collisioni con i flussi di lavoro di sviluppo. -- **Controllo deterministico delle schede**: le schede vengono indirizzate tramite `targetId`, non tramite “ultima scheda”. +- **Controllo deterministico delle schede**: indirizza le schede tramite `targetId`, non “ultima scheda”. ## Selezione del browser -Quando viene avviato localmente, OpenClaw sceglie il primo disponibile: +Quando esegue l'avvio locale, OpenClaw sceglie il primo disponibile: 1. Chrome 2. Brave @@ -542,7 +543,7 @@ Quando viene avviato localmente, OpenClaw sceglie il primo disponibile: 4. Chromium 5. Chrome Canary -Puoi sovrascriverlo con `browser.executablePath`. +Puoi sostituire questa scelta con `browser.executablePath`. Piattaforme: @@ -552,7 +553,7 @@ Piattaforme: ## API di controllo (facoltativa) -Solo per integrazioni locali, il Gateway espone una piccola API HTTP su loopback: +Solo per integrazioni locali, il Gateway espone una piccola API HTTP loopback: - Stato/avvio/arresto: `GET /`, `POST /start`, `POST /stop` - Schede: `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId` @@ -572,36 +573,57 @@ Tutti gli endpoint accettano `?profile=`. Se è configurata l'autenticazione gateway con segreto condiviso, anche le route HTTP browser richiedono autenticazione: - `Authorization: Bearer ` -- `x-openclaw-password: ` oppure HTTP Basic auth con quella password +- `x-openclaw-password: ` oppure autenticazione HTTP Basic con quella password Note: -- Questa API browser standalone su loopback **non** usa trusted-proxy o +- Questa API browser loopback standalone **non** usa trusted-proxy o gli header di identità Tailscale Serve. -- Se `gateway.auth.mode` è `none` o `trusted-proxy`, queste route browser su loopback - non ereditano quelle modalità basate sull'identità; mantienile solo su loopback. +- Se `gateway.auth.mode` è `none` o `trusted-proxy`, queste route browser loopback + non ereditano quelle modalità con identità; mantienile solo loopback. + +### Contratto di errore `/act` + +`POST /act` usa una risposta di errore strutturata per la validazione a livello di route e +per gli errori di policy: + +```json +{ "error": "", "code": "ACT_*" } +``` + +Valori `code` attuali: + +- `ACT_KIND_REQUIRED` (HTTP 400): `kind` manca o non è riconosciuto. +- `ACT_INVALID_REQUEST` (HTTP 400): il payload dell'azione non ha superato normalizzazione o validazione. +- `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): `selector` è stato usato con un tipo di azione non supportato. +- `ACT_EVALUATE_DISABLED` (HTTP 403): `evaluate` (o `wait --fn`) è disabilitato dalla configurazione. +- `ACT_TARGET_ID_MISMATCH` (HTTP 403): `targetId` di primo livello o batch è in conflitto con la destinazione della richiesta. +- `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): l'azione non è supportata per i profili existing-session. + +Altri errori runtime possono ancora restituire `{ "error": "" }` senza un +campo `code`. ### Requisito Playwright -Alcune funzionalità (navigate/act/AI snapshot/role snapshot, screenshot di elementi, +Alcune funzionalità (navigate/act/snapshot AI/snapshot ruolo, screenshot di elementi, PDF) richiedono Playwright. Se Playwright non è installato, quegli endpoint restituiscono un chiaro errore 501. -Cosa funziona ancora senza Playwright: +Cosa continua a funzionare senza Playwright: -- Snapshot ARIA -- Screenshot di pagina per il browser `openclaw` gestito quando è disponibile un - WebSocket CDP per scheda -- Screenshot di pagina per profili `existing-session` / Chrome MCP -- Screenshot existing-session basati su ref (`--ref`) dall'output snapshot +- snapshot ARIA +- screenshot di pagina per il browser `openclaw` gestito quando è disponibile un WebSocket + CDP per scheda +- screenshot di pagina per i profili `existing-session` / Chrome MCP +- screenshot existing-session basati su ref (`--ref`) dall'output snapshot Cosa richiede ancora Playwright: - `navigate` - `act` -- Snapshot AI / role snapshot -- Screenshot di elementi con selettore CSS (`--element`) -- Esportazione PDF completa del browser +- snapshot AI / snapshot ruolo +- screenshot di elementi con selettore CSS (`--element`) +- esportazione PDF completa del browser Gli screenshot di elementi rifiutano anche `--full-page`; la route restituisce `fullPage is not supported for element screenshots`. @@ -613,7 +635,7 @@ OpenClaw con supporto browser. #### Installazione di Playwright in Docker Se il tuo Gateway è in esecuzione in Docker, evita `npx playwright` (conflitti con gli override npm). -Usa invece la CLI inclusa: +Usa invece la CLI bundle: ```bash docker compose run --rm openclaw-cli \ @@ -626,23 +648,23 @@ Per rendere persistenti i download del browser, imposta `PLAYWRIGHT_BROWSERS_PAT ## Come funziona (interno) -Flusso di alto livello: +Flusso ad alto livello: - Un piccolo **server di controllo** accetta richieste HTTP. -- Si collega ai browser basati su Chromium (Chrome/Brave/Edge/Chromium) tramite **CDP**. +- Si connette ai browser basati su Chromium (Chrome/Brave/Edge/Chromium) tramite **CDP**. - Per azioni avanzate (clic/digitazione/snapshot/PDF), usa **Playwright** sopra CDP. -- Quando Playwright manca, sono disponibili solo le operazioni non basate su Playwright. +- Quando Playwright non è presente, sono disponibili solo le operazioni che non usano Playwright. -Questo design mantiene l'agente su un'interfaccia stabile e deterministica, permettendoti allo stesso tempo -di cambiare browser e profili locali/remoti. +Questo design mantiene l'agente su un'interfaccia stabile e deterministica, consentendoti al tempo stesso +di sostituire browser e profili locali/remoti. ## Riferimento rapido CLI -Tutti i comandi accettano `--browser-profile ` per destinare un profilo specifico. -Tutti i comandi accettano anche `--json` per output leggibili dalla macchina (payload stabili). +Tutti i comandi accettano `--browser-profile ` per indirizzare un profilo specifico. +Tutti i comandi accettano anche `--json` per output leggibile dalla macchina (payload stabili). -Elementi di base: +Di base: - `openclaw browser status` - `openclaw browser start` @@ -674,9 +696,9 @@ Ispezione: Nota sul ciclo di vita: - Per i profili attach-only e CDP remoti, `openclaw browser stop` è comunque il - comando corretto di pulizia dopo i test. Chiude la sessione di controllo attiva e - cancella le sovrascritture temporanee di emulazione invece di terminare il browser - sottostante. + comando di pulizia corretto dopo i test. Chiude la sessione di controllo attiva e + cancella le sostituzioni temporanee di emulazione invece di terminare il + browser sottostante. - `openclaw browser errors --clear` - `openclaw browser requests --filter api --clear` - `openclaw browser pdf` @@ -727,25 +749,25 @@ Stato: Note: -- `upload` e `dialog` sono chiamate di **preparazione**; eseguirle prima del clic/premi - che attiva il selettore file/dialog. -- I percorsi di output per download e trace sono vincolati alle radici temp di OpenClaw: +- `upload` e `dialog` sono chiamate di **armamento**; eseguirle prima del clic/della pressione + che attiva il selettore/la finestra di dialogo. +- I percorsi di output per download e trace sono vincolati alle root temporanee di OpenClaw: - trace: `/tmp/openclaw` (fallback: `${os.tmpdir()}/openclaw`) - download: `/tmp/openclaw/downloads` (fallback: `${os.tmpdir()}/openclaw/downloads`) -- I percorsi di upload sono vincolati a una radice temp uploads di OpenClaw: - - uploads: `/tmp/openclaw/uploads` (fallback: `${os.tmpdir()}/openclaw/uploads`) +- I percorsi di upload sono vincolati a una root temporanea di upload OpenClaw: + - upload: `/tmp/openclaw/uploads` (fallback: `${os.tmpdir()}/openclaw/uploads`) - `upload` può anche impostare direttamente input file tramite `--input-ref` o `--element`. - `snapshot`: - `--format ai` (predefinito quando Playwright è installato): restituisce uno snapshot AI con ref numerici (`aria-ref=""`). - `--format aria`: restituisce l'albero di accessibilità (nessun ref; solo ispezione). - - `--efficient` (oppure `--mode efficient`): preset di role snapshot compatto (interactive + compact + depth + maxChars inferiore). - - Predefinito di configurazione (solo tool/CLI): imposta `browser.snapshotDefaults.mode: "efficient"` per usare snapshot efficienti quando il chiamante non passa una modalità (vedi [configurazione del Gateway](/it/gateway/configuration-reference#browser)). - - Le opzioni role snapshot (`--interactive`, `--compact`, `--depth`, `--selector`) forzano uno snapshot basato sui ruoli con ref come `ref=e12`. - - `--frame "