From cc2fdc1d5ee74e542017f51b103728b9e1c348b7 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Mon, 6 Apr 2026 08:21:32 +0000 Subject: [PATCH] chore(i18n): refresh it translations --- docs/it/channels/matrix.md | 568 ++++++------ docs/it/channels/slack.md | 343 +++++--- docs/it/concepts/dreaming.md | 155 ++-- docs/it/gateway/configuration-reference.md | 964 +++++++++++---------- docs/it/plugins/sdk-migration.md | 370 ++++---- docs/it/plugins/sdk-overview.md | 501 +++++------ docs/it/tools/image-generation.md | 115 ++- docs/it/tools/video-generation.md | 152 ++-- 8 files changed, 1657 insertions(+), 1511 deletions(-) diff --git a/docs/it/channels/matrix.md b/docs/it/channels/matrix.md index 3b2784c35..00477d1a5 100644 --- a/docs/it/channels/matrix.md +++ b/docs/it/channels/matrix.md @@ -1,29 +1,29 @@ --- read_when: - Configurare Matrix in OpenClaw - - Configurare E2EE e la verifica di Matrix -summary: Stato del supporto Matrix, configurazione e esempi di configurazione + - Configurare Matrix E2EE e la verifica +summary: Stato del supporto Matrix, configurazione ed esempi di configurazione title: Matrix x-i18n: - generated_at: "2026-04-06T03:08:12Z" + generated_at: "2026-04-06T08:17:28Z" model: gpt-5.4 provider: openai - source_hash: 3e2d84c08d7d5b96db14b914e54f08d25334401cdd92eb890bc8dfb37b0ca2dc + source_hash: 06f833bf0ede81bad69f140994c32e8cc5d1635764f95fc5db4fc5dc25f2b85e source_path: channels/matrix.md workflow: 15 --- # Matrix -Matrix è il plugin di canale Matrix incluso per OpenClaw. -Usa il `matrix-js-sdk` ufficiale e supporta DM, stanze, thread, contenuti multimediali, reazioni, sondaggi, posizione ed E2EE. +Matrix è il plugin di canale Matrix incluso con OpenClaw. +Usa il pacchetto ufficiale `matrix-js-sdk` e supporta DM, stanze, thread, contenuti multimediali, reazioni, sondaggi, posizione ed E2EE. ## Plugin incluso -Matrix è incluso come plugin incluso nelle versioni correnti di OpenClaw, quindi le +Matrix viene distribuito come plugin incluso nelle versioni attuali di OpenClaw, quindi le build pacchettizzate normali non richiedono un'installazione separata. -Se stai usando una build meno recente o un'installazione personalizzata che esclude Matrix, installalo +Se usi una build meno recente o un'installazione personalizzata che esclude Matrix, installalo manualmente: Installa da npm: @@ -46,7 +46,7 @@ Vedi [Plugins](/it/tools/plugin) per il comportamento dei plugin e le regole di - Le versioni pacchettizzate correnti di OpenClaw lo includono già. - Le installazioni meno recenti/personalizzate possono aggiungerlo manualmente con i comandi sopra. 2. Crea un account Matrix sul tuo homeserver. -3. Configura `channels.matrix` con uno dei seguenti: +3. Configura `channels.matrix` con una delle seguenti opzioni: - `homeserver` + `accessToken`, oppure - `homeserver` + `userId` + `password`. 4. Riavvia il gateway. @@ -59,22 +59,22 @@ openclaw channels add openclaw configure --section channels ``` -Cosa chiede effettivamente la procedura guidata Matrix: +Cosa chiede effettivamente la procedura guidata di Matrix: - URL dell'homeserver -- metodo di autenticazione: access token o password -- ID utente solo quando scegli l'autenticazione con password +- metodo di autenticazione: token di accesso o password +- ID utente solo se scegli l'autenticazione con password - nome dispositivo facoltativo - se abilitare E2EE -- se configurare ora l'accesso alla stanza Matrix +- se configurare ora l'accesso alle stanze Matrix -Comportamenti importanti della procedura guidata: +Comportamento della procedura guidata da tenere presente: -- Se le variabili d'ambiente di autenticazione Matrix esistono già per l'account selezionato e quell'account non ha già l'autenticazione salvata nella configurazione, la procedura guidata offre una scorciatoia tramite env e scrive solo `enabled: true` per quell'account. -- Quando aggiungi interattivamente un altro account Matrix, il nome account inserito viene normalizzato nell'ID account usato nella configurazione e nelle variabili env. Per esempio, `Ops Bot` diventa `ops-bot`. -- I prompt della allowlist DM accettano immediatamente valori completi `@user:server`. I nomi visualizzati funzionano solo quando la ricerca live nella directory trova una corrispondenza esatta; altrimenti la procedura guidata ti chiede di riprovare con un ID Matrix completo. -- I prompt della allowlist delle stanze accettano direttamente ID stanza e alias. Possono anche risolvere in tempo reale i nomi delle stanze a cui si è iscritti, ma i nomi non risolti vengono mantenuti solo come digitati durante la configurazione e vengono ignorati in seguito dalla risoluzione della allowlist a runtime. Preferisci `!room:server` o `#alias:server`. -- L'identità di stanza/sessione a runtime usa l'ID stabile della stanza Matrix. Gli alias dichiarati dalla stanza vengono usati solo come input di ricerca, non come chiave di sessione a lungo termine o identità stabile del gruppo. +- Se le variabili d'ambiente di autenticazione Matrix esistono già per l'account selezionato e per quell'account l'autenticazione non è già salvata nella configurazione, la procedura guidata offre una scorciatoia tramite env e scrive solo `enabled: true` per quell'account. +- Quando aggiungi in modo interattivo un altro account Matrix, il nome account inserito viene normalizzato nell'ID account usato nella configurazione e nelle variabili d'ambiente. Ad esempio, `Ops Bot` diventa `ops-bot`. +- I prompt della allowlist DM accettano subito valori completi `@user:server`. I nomi visualizzati funzionano solo quando la ricerca live nella directory trova una sola corrispondenza esatta; altrimenti la procedura guidata ti chiede di riprovare con un ID Matrix completo. +- I prompt della allowlist delle stanze accettano direttamente ID stanza e alias. Possono anche risolvere in tempo reale i nomi delle stanze già unite, ma i nomi non risolti vengono mantenuti solo come digitati durante la configurazione e vengono ignorati più tardi dalla risoluzione runtime della allowlist. Preferisci `!room:server` o `#alias:server`. +- L'identità runtime di stanza/sessione usa l'ID stanza Matrix stabile. Gli alias dichiarati nella stanza vengono usati solo come input di ricerca, non come chiave di sessione a lungo termine o identità stabile del gruppo. - Per risolvere i nomi delle stanze prima di salvarli, usa `openclaw channels resolve --channel matrix "Project Room"`. Configurazione minima basata su token: @@ -108,9 +108,9 @@ Configurazione basata su password (il token viene memorizzato nella cache dopo i } ``` -Matrix memorizza le credenziali nella cache in `~/.openclaw/credentials/matrix/`. +Matrix memorizza le credenziali in cache in `~/.openclaw/credentials/matrix/`. L'account predefinito usa `credentials.json`; gli account con nome usano `credentials-.json`. -Quando lì esistono credenziali nella cache, OpenClaw considera Matrix configurato per setup, doctor e rilevamento dello stato del canale, anche se l'autenticazione corrente non è impostata direttamente nella configurazione. +Quando lì esistono credenziali in cache, OpenClaw considera Matrix configurato per setup, doctor e individuazione dello stato del canale anche se l'autenticazione corrente non è impostata direttamente nella configurazione. Equivalenti come variabili d'ambiente (usati quando la chiave di configurazione non è impostata): @@ -121,7 +121,7 @@ Equivalenti come variabili d'ambiente (usati quando la chiave di configurazione - `MATRIX_DEVICE_ID` - `MATRIX_DEVICE_NAME` -Per account non predefiniti, usa variabili env con ambito account: +Per account non predefiniti, usa variabili d'ambiente con ambito account: - `MATRIX__HOMESERVER` - `MATRIX__ACCESS_TOKEN` @@ -140,10 +140,10 @@ Per l'ID account normalizzato `ops-bot`, usa: - `MATRIX_OPS_X2D_BOT_HOMESERVER` - `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN` -Matrix esegue l'escape della punteggiatura negli ID account per mantenere le variabili env con ambito prive di collisioni. -Per esempio, `-` diventa `_X2D_`, quindi `ops-prod` viene mappato a `MATRIX_OPS_X2D_PROD_*`. +Matrix esegue l'escape della punteggiatura negli ID account per evitare collisioni nelle variabili d'ambiente con ambito. +Ad esempio, `-` diventa `_X2D_`, quindi `ops-prod` corrisponde a `MATRIX_OPS_X2D_PROD_*`. -La procedura guidata interattiva offre la scorciatoia tramite variabile env solo quando quelle variabili env di autenticazione sono già presenti e l'account selezionato non ha già l'autenticazione Matrix salvata nella configurazione. +La procedura guidata interattiva offre la scorciatoia con variabili d'ambiente solo quando quelle variabili env di autenticazione sono già presenti e l'account selezionato non ha già l'autenticazione Matrix salvata nella configurazione. ## Esempio di configurazione @@ -182,13 +182,20 @@ Questa è una configurazione di base pratica con pairing DM, allowlist delle sta } ``` +`autoJoin` si applica agli inviti Matrix in generale, non solo agli inviti di stanze/gruppi. +Ciò include i nuovi inviti in stile DM. Al momento dell'invito, OpenClaw non sa in modo affidabile se la +stanza invitata verrà trattata come DM o come gruppo, quindi tutti gli inviti passano prima attraverso la stessa +decisione di `autoJoin`. `dm.policy` continua ad applicarsi dopo che il bot è entrato e la stanza è +classificata come DM, quindi `autoJoin` controlla il comportamento di ingresso mentre `dm.policy` controlla +il comportamento di risposta/accesso. + ## Anteprime in streaming Lo streaming delle risposte Matrix è opt-in. Imposta `channels.matrix.streaming` su `"partial"` quando vuoi che OpenClaw invii una singola anteprima live -della risposta, modifichi quell'anteprima sul posto mentre il modello genera il testo e poi la -finalizzi quando la risposta è completata: +di risposta, modifichi quell'anteprima sul posto mentre il modello genera testo, e poi la finalizzi quando la +risposta è terminata: ```json5 { @@ -200,24 +207,24 @@ finalizzi quando la risposta è completata: } ``` -- `streaming: "off"` è l'impostazione predefinita. OpenClaw attende la risposta finale e la invia una sola volta. -- `streaming: "partial"` crea un messaggio di anteprima modificabile per il blocco corrente dell'assistente usando normali messaggi di testo Matrix. Questo preserva il comportamento legacy di Matrix di notifica basata sulla prima anteprima, quindi i client standard possono notificare sul primo testo in streaming invece che sul blocco completato. -- `streaming: "quiet"` crea un'anteprima modificabile silenziosa per il blocco corrente dell'assistente. Usalo solo quando configuri anche regole push lato destinatario per le modifiche finalizzate dell'anteprima. -- `blockStreaming: true` abilita messaggi di avanzamento Matrix separati. Con lo streaming di anteprima abilitato, Matrix mantiene la bozza live per il blocco corrente e conserva i blocchi completati come messaggi separati. -- Quando lo streaming di anteprima è attivo e `blockStreaming` è disattivato, Matrix modifica la bozza live sul posto e finalizza quello stesso evento quando il blocco o il turno termina. -- Se l'anteprima non entra più in un singolo evento Matrix, OpenClaw interrompe lo streaming di anteprima e torna alla consegna finale normale. +- `streaming: "off"` è il valore predefinito. OpenClaw aspetta la risposta finale e la invia una sola volta. +- `streaming: "partial"` crea un singolo messaggio di anteprima modificabile per il blocco corrente dell'assistente usando normali messaggi di testo Matrix. Questo preserva il comportamento legacy di Matrix con notifica sulla prima anteprima, quindi i client standard possono notificare sul primo testo dell'anteprima in streaming invece che sul blocco completato. +- `streaming: "quiet"` crea un singolo avviso di anteprima silenzioso e modificabile per il blocco corrente dell'assistente. Usalo solo quando configuri anche regole push per i destinatari sulle modifiche finalizzate dell'anteprima. +- `blockStreaming: true` abilita messaggi di avanzamento Matrix separati. Con l'anteprima in streaming abilitata, Matrix mantiene la bozza live per il blocco corrente e conserva i blocchi completati come messaggi separati. +- Quando l'anteprima in streaming è attiva e `blockStreaming` è disattivato, Matrix modifica la bozza live sul posto e finalizza quello stesso evento quando il blocco o il turno termina. +- Se l'anteprima non entra più in un singolo evento Matrix, OpenClaw interrompe lo streaming dell'anteprima e torna alla normale consegna finale. - Le risposte multimediali continuano a inviare normalmente gli allegati. Se un'anteprima obsoleta non può più essere riutilizzata in sicurezza, OpenClaw la redige prima di inviare la risposta multimediale finale. -- Le modifiche di anteprima comportano chiamate API Matrix aggiuntive. Lascia disattivato lo streaming se vuoi il comportamento più conservativo rispetto ai limiti di frequenza. +- Le modifiche all'anteprima comportano chiamate API Matrix aggiuntive. Lascia lo streaming disattivato se vuoi il comportamento più conservativo possibile rispetto ai limiti di velocità. -`blockStreaming` da solo non abilita le anteprime bozza. -Usa `streaming: "partial"` o `streaming: "quiet"` per le modifiche di anteprima; poi aggiungi `blockStreaming: true` solo se vuoi anche che i blocchi completati dell'assistente rimangano visibili come messaggi di avanzamento separati. +`blockStreaming` da solo non abilita le anteprime in bozza. +Usa `streaming: "partial"` o `streaming: "quiet"` per le modifiche di anteprima; poi aggiungi `blockStreaming: true` solo se vuoi anche che i blocchi dell'assistente completati restino visibili come messaggi di avanzamento separati. -Se hai bisogno delle notifiche standard Matrix senza regole push personalizzate, usa `streaming: "partial"` per il comportamento con anteprima iniziale oppure lascia `streaming` disattivato per la consegna solo finale. Con `streaming: "off"`: +Se ti servono notifiche Matrix standard senza regole push personalizzate, usa `streaming: "partial"` per il comportamento con anteprima iniziale oppure lascia `streaming` disattivato per la consegna solo finale. Con `streaming: "off"`: -- `blockStreaming: true` invia ogni blocco completato come un normale messaggio Matrix che genera notifiche. -- `blockStreaming: false` invia solo la risposta finale completata come un normale messaggio Matrix che genera notifiche. +- `blockStreaming: true` invia ogni blocco completato come normale messaggio Matrix con notifica. +- `blockStreaming: false` invia solo la risposta finale completata come normale messaggio Matrix con notifica. -### Regole push self-hosted per anteprime finalizzate silenziose +### Regole push self-hosted per anteprime silenziose finalizzate Se gestisci la tua infrastruttura Matrix e vuoi che le anteprime silenziose notifichino solo quando un blocco o la risposta finale è pronta, imposta `streaming: "quiet"` e aggiungi una regola push per utente per le modifiche finalizzate dell'anteprima. @@ -228,8 +235,8 @@ Mappa rapida prima di iniziare: - utente destinatario = la persona che deve ricevere la notifica - utente bot = l'account Matrix OpenClaw che invia la risposta -- usa l'access token dell'utente destinatario per le chiamate API qui sotto -- fai corrispondere `sender` nella regola push con l'MXID completo dell'utente bot +- usa il token di accesso dell'utente destinatario per le chiamate API qui sotto +- fai corrispondere `sender` nella regola push al MXID completo dell'utente bot 1. Configura OpenClaw per usare anteprime silenziose: @@ -243,13 +250,13 @@ Mappa rapida prima di iniziare: } ``` -2. Assicurati che l'account destinatario riceva già le normali notifiche push Matrix. Le regole - per anteprima silenziosa funzionano solo se quell'utente ha già pusher/dispositivi funzionanti. +2. Assicurati che l'account destinatario riceva già le normali notifiche push Matrix. Le regole per + le anteprime silenziose funzionano solo se quell'utente ha già pusher/dispositivi funzionanti. -3. Ottieni l'access token dell'utente destinatario. +3. Ottieni il token di accesso dell'utente destinatario. - Usa il token dell'utente che riceve, non quello del bot. - - Riutilizzare un token di sessione client esistente è in genere la soluzione più semplice. - - Se devi generare un token nuovo, puoi effettuare il login tramite la normale API Client-Server Matrix: + - Riutilizzare un token di sessione client esistente di solito è la soluzione più semplice. + - Se devi generare un nuovo token, puoi accedere tramite la normale API Client-Server Matrix: ```bash curl -sS -X POST \ @@ -265,7 +272,7 @@ curl -sS -X POST \ }' ``` -4. Verifica che l'account destinatario abbia già pusher: +4. Verifica che l'account destinatario abbia già dei pusher: ```bash curl -sS \ @@ -273,10 +280,10 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushers" ``` -Se questo restituisce zero pusher/dispositivi attivi, correggi prima le normali notifiche Matrix prima di aggiungere la -regola OpenClaw qui sotto. +Se questo comando non restituisce pusher/dispositivi attivi, correggi prima le normali notifiche Matrix prima di aggiungere +la regola OpenClaw qui sotto. -OpenClaw contrassegna le modifiche finalizzate di anteprima solo testuale con: +OpenClaw contrassegna le modifiche finalizzate dell'anteprima solo testuale con: ```json { @@ -316,21 +323,21 @@ curl -sS -X PUT \ Sostituisci questi valori prima di eseguire il comando: -- `https://matrix.example.org`: URL base del tuo homeserver -- `$USER_ACCESS_TOKEN`: l'access token dell'utente che riceve -- `openclaw-finalized-preview-botname`: un ID regola univoco per questo bot per questo utente ricevente -- `@bot:example.org`: l'MXID del tuo bot Matrix OpenClaw, non l'MXID dell'utente ricevente +- `https://matrix.example.org`: URL di base del tuo homeserver +- `$USER_ACCESS_TOKEN`: token di accesso dell'utente destinatario +- `openclaw-finalized-preview-botname`: un ID regola univoco per questo bot per questo utente destinatario +- `@bot:example.org`: il MXID del tuo bot Matrix OpenClaw, non il MXID dell'utente destinatario -Importante per le configurazioni multi-bot: +Importante per configurazioni multi-bot: - Le regole push sono indicizzate da `ruleId`. Rieseguire `PUT` sullo stesso ID regola aggiorna quella singola regola. -- Se un utente ricevente deve ricevere notifiche per più account bot Matrix OpenClaw, crea una regola per bot con un ID regola univoco per ogni corrispondenza `sender`. -- Un pattern semplice è `openclaw-finalized-preview-`, per esempio `openclaw-finalized-preview-ops` o `openclaw-finalized-preview-support`. +- Se un utente destinatario deve ricevere notifiche per più account bot Matrix OpenClaw, crea una regola per bot con un ID regola univoco per ogni corrispondenza del sender. +- Un modello semplice è `openclaw-finalized-preview-`, ad esempio `openclaw-finalized-preview-ops` o `openclaw-finalized-preview-support`. La regola viene valutata rispetto al mittente dell'evento: -- autentica usando il token dell'utente ricevente -- fai corrispondere `sender` con l'MXID del bot OpenClaw +- autenticati con il token dell'utente destinatario +- fai corrispondere `sender` al MXID del bot OpenClaw 6. Verifica che la regola esista: @@ -340,10 +347,10 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" ``` -7. Prova una risposta in streaming. In modalità silenziosa, la stanza dovrebbe mostrare una bozza di anteprima silenziosa e la - modifica finale sul posto dovrebbe notificare una volta terminato il blocco o il turno. +7. Prova una risposta in streaming. In modalità silenziosa, la stanza dovrebbe mostrare una bozza di anteprima silenziosa e la modifica finale + sul posto dovrebbe inviare una notifica quando il blocco o il turno termina. -Se devi rimuovere la regola in seguito, elimina quello stesso ID regola con il token dell'utente ricevente: +Se in seguito devi rimuovere la regola, elimina quello stesso ID regola con il token dell'utente destinatario: ```bash curl -sS -X DELETE \ @@ -353,37 +360,37 @@ curl -sS -X DELETE \ Note: -- Crea la regola con l'access token dell'utente ricevente, non con quello del bot. -- Le nuove regole `override` definite dall'utente vengono inserite prima delle regole di soppressione predefinite, quindi non serve alcun parametro di ordinamento aggiuntivo. -- Questo influisce solo sulle modifiche di anteprima solo testuale che OpenClaw può finalizzare in sicurezza sul posto. I fallback per contenuti multimediali e i fallback per anteprime obsolete usano comunque la normale consegna Matrix. -- Se `GET /_matrix/client/v3/pushers` non mostra pusher, l'utente non ha ancora una consegna push Matrix funzionante per questo account/dispositivo. +- Crea la regola con il token di accesso dell'utente destinatario, non con quello del bot. +- Le nuove regole `override` definite dall'utente vengono inserite prima delle regole di soppressione predefinite, quindi non è necessario alcun parametro di ordinamento aggiuntivo. +- Questo influisce solo sulle modifiche di anteprima solo testuali che OpenClaw può finalizzare in sicurezza sul posto. I fallback per contenuti multimediali e per anteprime obsolete usano ancora la normale consegna Matrix. +- Se `GET /_matrix/client/v3/pushers` non mostra alcun pusher, l'utente non ha ancora una consegna push Matrix funzionante per questo account/dispositivo. #### Synapse -Per Synapse, la configurazione sopra di solito è sufficiente da sola: +Per Synapse, la configurazione sopra di solito è già sufficiente da sola: -- Non è richiesta alcuna modifica speciale a `homeserver.yaml` per le notifiche di anteprima OpenClaw finalizzate. -- Se il deployment Synapse invia già normali notifiche push Matrix, il token utente + la chiamata `pushrules` sopra sono il principale passaggio di configurazione. -- Se esegui Synapse dietro un reverse proxy o worker, assicurati che `/_matrix/client/.../pushrules/` raggiunga correttamente Synapse. -- Se esegui worker Synapse, assicurati che i pusher siano integri. La consegna push è gestita dal processo principale o da `synapse.app.pusher` / dai worker pusher configurati. +- Non è richiesta alcuna modifica speciale a `homeserver.yaml` per le notifiche delle anteprime OpenClaw finalizzate. +- Se il tuo deployment Synapse invia già le normali notifiche push Matrix, il token utente + la chiamata `pushrules` sopra sono il passaggio principale della configurazione. +- Se esegui Synapse dietro un reverse proxy o dei worker, assicurati che `/_matrix/client/.../pushrules/` raggiunga correttamente Synapse. +- Se usi i worker Synapse, assicurati che i pusher siano in salute. La consegna push è gestita dal processo principale o da `synapse.app.pusher` / worker pusher configurati. #### Tuwunel -Per Tuwunel, usa lo stesso flusso di configurazione e la chiamata API `pushrules` mostrata sopra: +Per Tuwunel, usa lo stesso flusso di configurazione e la stessa chiamata API `pushrules` mostrata sopra: -- Non è richiesta alcuna configurazione specifica di Tuwunel per il marcatore di anteprima finalizzata stesso. -- Se le normali notifiche Matrix funzionano già per quell'utente, il token utente + la chiamata `pushrules` sopra sono il principale passaggio di configurazione. -- Se le notifiche sembrano scomparire mentre l'utente è attivo su un altro dispositivo, verifica se `suppress_push_when_active` è abilitato. Tuwunel ha aggiunto questa opzione in Tuwunel 1.4.2 il 12 settembre 2025 e può sopprimere intenzionalmente le notifiche push verso altri dispositivi mentre un dispositivo è attivo. +- Non è richiesta alcuna configurazione specifica di Tuwunel per il marcatore di anteprima finalizzata in sé. +- Se le normali notifiche Matrix funzionano già per quell'utente, il token utente + la chiamata `pushrules` sopra sono il passaggio principale della configurazione. +- Se le notifiche sembrano scomparire mentre l'utente è attivo su un altro dispositivo, controlla se `suppress_push_when_active` è abilitato. Tuwunel ha aggiunto questa opzione in Tuwunel 1.4.2 il 12 settembre 2025, e può sopprimere intenzionalmente le push verso altri dispositivi mentre un dispositivo è attivo. -## Crittografia e verifica +## Cifratura e verifica -Nelle stanze crittografate (E2EE), gli eventi immagine in uscita usano `thumbnail_file` così le anteprime immagine vengono crittografate insieme all'allegato completo. Le stanze non crittografate continuano a usare `thumbnail_url` semplice. Non è necessaria alcuna configurazione: il plugin rileva automaticamente lo stato E2EE. +Nelle stanze cifrate (E2EE), gli eventi immagine in uscita usano `thumbnail_file` così che le anteprime immagine siano cifrate insieme all'allegato completo. Le stanze non cifrate continuano a usare `thumbnail_url` semplice. Non è necessaria alcuna configurazione: il plugin rileva automaticamente lo stato E2EE. ### Stanze bot-to-bot Per impostazione predefinita, i messaggi Matrix provenienti da altri account Matrix OpenClaw configurati vengono ignorati. -Usa `allowBots` quando vuoi intenzionalmente traffico Matrix inter-agent: +Usa `allowBots` quando vuoi intenzionalmente traffico Matrix tra agenti: ```json5 { @@ -400,15 +407,15 @@ Usa `allowBots` quando vuoi intenzionalmente traffico Matrix inter-agent: } ``` -- `allowBots: true` accetta messaggi da altri account bot Matrix configurati in stanze e DM consentiti. -- `allowBots: "mentions"` accetta quei messaggi solo quando menzionano visibilmente questo bot nelle stanze. I DM restano comunque consentiti. +- `allowBots: true` accetta messaggi da altri account bot Matrix configurati nelle stanze e nei DM consentiti. +- `allowBots: "mentions"` accetta quei messaggi solo quando menzionano visibilmente questo bot nelle stanze. I DM sono comunque consentiti. - `groups..allowBots` sovrascrive l'impostazione a livello account per una singola stanza. -- OpenClaw continua a ignorare i messaggi provenienti dallo stesso ID utente Matrix per evitare cicli di auto-risposta. -- Qui Matrix non espone un flag bot nativo; OpenClaw considera "creato da bot" come "inviato da un altro account Matrix configurato su questo gateway OpenClaw". +- OpenClaw continua a ignorare i messaggi provenienti dallo stesso ID utente Matrix per evitare cicli di autorisposta. +- Matrix qui non espone un flag bot nativo; OpenClaw considera "scritto da un bot" come "inviato da un altro account Matrix configurato su questo gateway OpenClaw". -Usa allowlist rigorose delle stanze e requisiti di menzione quando abiliti traffico bot-to-bot in stanze condivise. +Usa allowlist rigorose per le stanze e requisiti di menzione quando abiliti il traffico bot-to-bot in stanze condivise. -Abilita la crittografia: +Abilita la cifratura: ```json5 { @@ -436,19 +443,19 @@ Stato dettagliato (diagnostica completa): openclaw matrix verify status --verbose ``` -Includi la recovery key memorizzata nell'output leggibile dalla macchina: +Includi la chiave di ripristino memorizzata nell'output leggibile da macchina: ```bash openclaw matrix verify status --include-recovery-key --json ``` -Inizializza lo stato di cross-signing e verifica: +Inizializza cross-signing e stato di verifica: ```bash openclaw matrix verify bootstrap ``` -Supporto multi-account: usa `channels.matrix.accounts` con credenziali per account e `name` facoltativo. Vedi [Configuration reference](/it/gateway/configuration-reference#multi-account-all-channels) per il pattern condiviso. +Supporto multi-account: usa `channels.matrix.accounts` con credenziali per account e `name` facoltativo. Vedi [Configuration reference](/it/gateway/configuration-reference#multi-account-all-channels) per il modello condiviso. Diagnostica dettagliata del bootstrap: @@ -456,37 +463,37 @@ Diagnostica dettagliata del bootstrap: openclaw matrix verify bootstrap --verbose ``` -Forza un nuovo reset dell'identità di cross-signing prima del bootstrap: +Forza un reset di una nuova identità cross-signing prima del bootstrap: ```bash openclaw matrix verify bootstrap --force-reset-cross-signing ``` -Verifica questo dispositivo con una recovery key: +Verifica questo dispositivo con una chiave di ripristino: ```bash openclaw matrix verify device "" ``` -Dettagli verbosi della verifica del dispositivo: +Dettagli dettagliati della verifica del dispositivo: ```bash openclaw matrix verify device "" --verbose ``` -Controlla lo stato di salute del backup delle chiavi stanza: +Controlla lo stato di salute del backup delle chiavi della stanza: ```bash openclaw matrix verify backup status ``` -Diagnostica dettagliata dello stato di salute del backup: +Diagnostica dettagliata dello stato del backup: ```bash openclaw matrix verify backup status --verbose ``` -Ripristina le chiavi stanza dal backup sul server: +Ripristina le chiavi della stanza dal backup del server: ```bash openclaw matrix verify backup restore @@ -498,20 +505,20 @@ Diagnostica dettagliata del ripristino: openclaw matrix verify backup restore --verbose ``` -Elimina il backup server corrente e crea una nuova baseline di backup. Se la chiave di backup -memorizzata non può essere caricata correttamente, questo reset può anche ricreare il secret storage così che -i futuri avvii a freddo possano caricare la nuova chiave di backup: +Elimina il backup corrente sul server e crea una nuova baseline di backup. Se la chiave di +backup memorizzata non può essere caricata correttamente, questo reset può anche ricreare lo storage dei segreti così che +i futuri cold start possano caricare la nuova chiave di backup: ```bash openclaw matrix verify backup reset --yes ``` -Tutti i comandi `verify` sono concisi per impostazione predefinita (incluso il logging interno SDK silenzioso) e mostrano una diagnostica dettagliata solo con `--verbose`. -Usa `--json` per output completi leggibili dalla macchina negli script. +Tutti i comandi `verify` sono sintetici per impostazione predefinita (incluso il logging SDK interno silenzioso) e mostrano diagnostica dettagliata solo con `--verbose`. +Usa `--json` per l'output completo leggibile da macchina negli script. -Nelle configurazioni multi-account, i comandi CLI Matrix usano l'account predefinito Matrix implicito a meno che tu non passi `--account `. -Se configuri più account con nome, imposta prima `channels.matrix.defaultAccount` oppure queste operazioni CLI implicite si fermeranno e ti chiederanno di scegliere esplicitamente un account. -Usa `--account` ogni volta che vuoi che operazioni di verifica o sui dispositivi puntino esplicitamente a un account con nome: +Nelle configurazioni multi-account, i comandi CLI Matrix usano l'account predefinito implicito di Matrix a meno che non passi `--account `. +Se configuri più account con nome, imposta prima `channels.matrix.defaultAccount` altrimenti quelle operazioni CLI implicite si fermeranno e ti chiederanno di scegliere esplicitamente un account. +Usa `--account` ogni volta che vuoi che le operazioni di verifica o sui dispositivi prendano esplicitamente di mira un account con nome: ```bash openclaw matrix verify status --account assistant @@ -519,43 +526,43 @@ openclaw matrix verify backup restore --account assistant openclaw matrix devices list --account assistant ``` -Quando la crittografia è disabilitata o non disponibile per un account con nome, gli avvisi Matrix e gli errori di verifica puntano alla chiave di configurazione di quell'account, per esempio `channels.matrix.accounts.assistant.encryption`. +Quando la cifratura è disabilitata o non disponibile per un account con nome, gli avvisi Matrix e gli errori di verifica puntano alla chiave di configurazione di quell'account, per esempio `channels.matrix.accounts.assistant.encryption`. ### Cosa significa "verified" -OpenClaw considera questo dispositivo Matrix verificato solo quando viene verificato dalla tua identità di cross-signing. +OpenClaw considera questo dispositivo Matrix verificato solo quando è verificato dalla tua identità cross-signing. In pratica, `openclaw matrix verify status --verbose` espone tre segnali di attendibilità: -- `Locally trusted`: questo dispositivo è attendibile solo dal client corrente -- `Cross-signing verified`: l'SDK riporta il dispositivo come verificato tramite cross-signing +- `Locally trusted`: questo dispositivo è attendibile solo per il client corrente +- `Cross-signing verified`: l'SDK segnala il dispositivo come verificato tramite cross-signing - `Signed by owner`: il dispositivo è firmato dalla tua stessa chiave self-signing -`Verified by owner` diventa `yes` solo quando è presente la verifica cross-signing o la firma del proprietario. +`Verified by owner` diventa `yes` solo quando è presente la verifica tramite cross-signing o la firma del proprietario. La fiducia locale da sola non basta perché OpenClaw tratti il dispositivo come completamente verificato. ### Cosa fa il bootstrap -`openclaw matrix verify bootstrap` è il comando di riparazione e configurazione per gli account Matrix crittografati. -Esegue tutto quanto segue, in questo ordine: +`openclaw matrix verify bootstrap` è il comando di riparazione e configurazione per gli account Matrix cifrati. +Esegue tutto quanto segue in quest'ordine: -- inizializza il secret storage, riutilizzando una recovery key esistente quando possibile -- inizializza il cross-signing e carica le chiavi pubbliche di cross-signing mancanti -- tenta di contrassegnare e firmare tramite cross-signing il dispositivo corrente -- crea un nuovo backup lato server delle chiavi stanza se non ne esiste già uno +- inizializza lo storage dei segreti, riutilizzando una chiave di ripristino esistente quando possibile +- inizializza il cross-signing e carica le chiavi pubbliche cross-signing mancanti +- prova a contrassegnare e firmare tramite cross-signing il dispositivo corrente +- crea un nuovo backup lato server delle chiavi della stanza se non ne esiste già uno -Se l'homeserver richiede autenticazione interattiva per caricare le chiavi di cross-signing, OpenClaw prova prima il caricamento senza autenticazione, poi con `m.login.dummy`, poi con `m.login.password` quando `channels.matrix.password` è configurato. +Se l'homeserver richiede autenticazione interattiva per caricare chiavi cross-signing, OpenClaw prova prima il caricamento senza autenticazione, poi con `m.login.dummy`, poi con `m.login.password` quando `channels.matrix.password` è configurato. -Usa `--force-reset-cross-signing` solo quando vuoi intenzionalmente scartare l'identità di cross-signing corrente e crearne una nuova. +Usa `--force-reset-cross-signing` solo quando vuoi intenzionalmente scartare l'identità cross-signing corrente e crearne una nuova. -Se vuoi intenzionalmente scartare il backup corrente delle chiavi stanza e avviare una nuova +Se vuoi intenzionalmente scartare il backup corrente delle chiavi della stanza e avviare una nuova baseline di backup per i messaggi futuri, usa `openclaw matrix verify backup reset --yes`. -Fallo solo se accetti che la cronologia crittografata precedente non recuperabile rimanga -indisponibile e che OpenClaw possa ricreare il secret storage se il secret di backup corrente -non può essere caricato in sicurezza. +Fallo solo se accetti che la vecchia cronologia cifrata irrecuperabile resti +non disponibile e che OpenClaw possa ricreare lo storage dei segreti se l'attuale +segreto di backup non può essere caricato in sicurezza. ### Nuova baseline di backup -Se vuoi mantenere funzionanti i futuri messaggi crittografati e accetti di perdere la vecchia cronologia non recuperabile, esegui questi comandi in ordine: +Se vuoi mantenere funzionanti i futuri messaggi cifrati e accetti di perdere la vecchia cronologia irrecuperabile, esegui questi comandi nell'ordine seguente: ```bash openclaw matrix verify backup reset --yes @@ -563,115 +570,115 @@ openclaw matrix verify backup status --verbose openclaw matrix verify status ``` -Aggiungi `--account ` a ogni comando quando vuoi puntare esplicitamente a un account Matrix con nome. +Aggiungi `--account ` a ogni comando quando vuoi prendere esplicitamente di mira un account Matrix con nome. ### Comportamento all'avvio -Quando `encryption: true`, Matrix imposta per default `startupVerification` su `"if-unverified"`. +Quando `encryption: true`, Matrix imposta `startupVerification` su `"if-unverified"` per impostazione predefinita. All'avvio, se questo dispositivo non è ancora verificato, Matrix richiederà l'autoverifica in un altro client Matrix, salterà le richieste duplicate quando una è già in sospeso e applicherà un cooldown locale prima di riprovare dopo i riavvii. -Per impostazione predefinita, i tentativi di richiesta falliti vengono ritentati prima rispetto alla creazione riuscita della richiesta. +Per impostazione predefinita, i tentativi di richiesta falliti vengono ritentati prima rispetto alla creazione riuscita di una richiesta. Imposta `startupVerification: "off"` per disabilitare le richieste automatiche all'avvio, oppure regola `startupVerificationCooldownHours` -se desideri una finestra di nuovo tentativo più breve o più lunga. +se vuoi una finestra di ritentativo più breve o più lunga. -All'avvio viene eseguito automaticamente anche un passaggio conservativo di bootstrap crittografico. -Quel passaggio prova prima a riutilizzare il secret storage e l'identità di cross-signing correnti ed evita di reimpostare il cross-signing a meno che tu non esegua un flusso esplicito di riparazione bootstrap. +All'avvio viene inoltre eseguito automaticamente un passaggio conservativo di bootstrap crittografico. +Quel passaggio prova prima a riutilizzare lo storage dei segreti corrente e l'identità cross-signing corrente, ed evita di reimpostare il cross-signing a meno che tu non esegua un flusso esplicito di riparazione bootstrap. -Se all'avvio viene rilevato uno stato bootstrap danneggiato e `channels.matrix.password` è configurato, OpenClaw può tentare un percorso di riparazione più rigoroso. +Se all'avvio viene rilevato uno stato bootstrap danneggiato e `channels.matrix.password` è configurato, OpenClaw può provare un percorso di riparazione più rigoroso. Se il dispositivo corrente è già firmato dal proprietario, OpenClaw preserva quell'identità invece di reimpostarla automaticamente. Aggiornamento dal precedente plugin Matrix pubblico: -- OpenClaw riutilizza automaticamente lo stesso account Matrix, access token e identità del dispositivo quando possibile. -- Prima che venga eseguita qualsiasi modifica di migrazione Matrix utilizzabile, OpenClaw crea o riutilizza uno snapshot di recupero in `~/Backups/openclaw-migrations/`. -- Se usi più account Matrix, imposta `channels.matrix.defaultAccount` prima di aggiornare dal vecchio layout flat-store così OpenClaw sa quale account deve ricevere quello stato legacy condiviso. -- Se il plugin precedente aveva memorizzato localmente una chiave di decrittazione del backup delle chiavi stanza Matrix, l'avvio o `openclaw doctor --fix` la importeranno automaticamente nel nuovo flusso recovery-key. -- Se l'access token Matrix è cambiato dopo che la migrazione era stata preparata, all'avvio ora viene eseguita la scansione delle root di storage sibling basate sull'hash del token per cercare stato legacy di ripristino in sospeso prima di rinunciare al ripristino automatico del backup. -- Se l'access token Matrix cambia in seguito per lo stesso account, homeserver e utente, OpenClaw ora preferisce riutilizzare la root di storage esistente più completa basata sull'hash del token invece di iniziare da una directory di stato Matrix vuota. -- Al successivo avvio del gateway, le chiavi stanza sottoposte a backup vengono ripristinate automaticamente nel nuovo crypto store. -- Se il vecchio plugin aveva chiavi stanza solo locali che non sono mai state sottoposte a backup, OpenClaw mostrerà un avviso chiaro. Queste chiavi non possono essere esportate automaticamente dal precedente rust crypto store, quindi una parte della vecchia cronologia crittografata potrebbe rimanere non disponibile finché non viene recuperata manualmente. -- Vedi [Matrix migration](/it/install/migrating-matrix) per il flusso completo di aggiornamento, i limiti, i comandi di recupero e i messaggi di migrazione comuni. +- OpenClaw riutilizza automaticamente lo stesso account Matrix, token di accesso e identità del dispositivo quando possibile. +- Prima di eseguire modifiche di migrazione Matrix applicabili, OpenClaw crea o riutilizza uno snapshot di recupero in `~/Backups/openclaw-migrations/`. +- Se usi più account Matrix, imposta `channels.matrix.defaultAccount` prima di aggiornare dal vecchio layout flat-store così OpenClaw saprà quale account deve ricevere quello stato legacy condiviso. +- Se il plugin precedente memorizzava localmente una chiave di decrittazione per il backup delle chiavi della stanza Matrix, l'avvio o `openclaw doctor --fix` la importeranno automaticamente nel nuovo flusso della chiave di ripristino. +- Se il token di accesso Matrix è cambiato dopo che la migrazione è stata preparata, l'avvio ora esegue la scansione delle radici di storage sibling hash del token alla ricerca di stato legacy di ripristino in sospeso prima di rinunciare al ripristino automatico del backup. +- Se il token di accesso Matrix cambia in seguito per lo stesso account, homeserver e utente, OpenClaw ora preferisce riutilizzare la radice di storage hash del token esistente più completa invece di partire da una directory di stato Matrix vuota. +- Al successivo avvio del gateway, le chiavi della stanza sottoposte a backup vengono ripristinate automaticamente nel nuovo crypto store. +- Se il vecchio plugin aveva chiavi di stanza solo locali che non erano mai state sottoposte a backup, OpenClaw mostrerà un avviso chiaro. Queste chiavi non possono essere esportate automaticamente dal precedente rust crypto store, quindi parte della vecchia cronologia cifrata potrebbe restare non disponibile finché non viene recuperata manualmente. +- Vedi [Matrix migration](/it/install/migrating-matrix) per il flusso completo di aggiornamento, limiti, comandi di recupero e messaggi di migrazione comuni. -Lo stato runtime crittografato è organizzato in root per account, utente e hash del token in +Lo stato runtime cifrato è organizzato in radici per-account, per-utente con hash del token in `~/.openclaw/matrix/accounts//__//`. Quella directory contiene il sync store (`bot-storage.json`), il crypto store (`crypto/`), -il file della recovery key (`recovery-key.json`), lo snapshot IndexedDB (`crypto-idb-snapshot.json`), -i binding dei thread (`thread-bindings.json`) e lo stato di verifica all'avvio (`startup-verification.json`) +il file della chiave di ripristino (`recovery-key.json`), lo snapshot IndexedDB (`crypto-idb-snapshot.json`), +i binding dei thread (`thread-bindings.json`) e lo stato della verifica all'avvio (`startup-verification.json`) quando queste funzionalità sono in uso. -Quando il token cambia ma l'identità dell'account rimane la stessa, OpenClaw riutilizza la migliore root esistente -per quella tupla account/homeserver/utente così lo stato di sincronizzazione precedente, lo stato crittografico, i binding dei thread -e lo stato di verifica all'avvio restano visibili. +Quando il token cambia ma l'identità dell'account resta la stessa, OpenClaw riutilizza la migliore +radice esistente per quella tupla account/homeserver/utente così che lo stato di sync precedente, lo stato crittografico, i binding dei thread +e lo stato della verifica all'avvio restino visibili. -### Modello del crypto store Node +### Modello crypto store Node -L'E2EE Matrix in questo plugin usa il percorso Rust crypto ufficiale di `matrix-js-sdk` in Node. -Quel percorso si aspetta persistenza basata su IndexedDB quando vuoi che lo stato crittografico sopravviva ai riavvii. +Matrix E2EE in questo plugin usa il percorso Rust crypto ufficiale di `matrix-js-sdk` in Node. +Quel percorso richiede una persistenza basata su IndexedDB quando vuoi che lo stato crittografico sopravviva ai riavvii. -Attualmente OpenClaw lo fornisce in Node tramite: +OpenClaw al momento fornisce questa funzionalità in Node in questo modo: -- uso di `fake-indexeddb` come shim API IndexedDB richiesto dall'SDK -- ripristino del contenuto IndexedDB del Rust crypto da `crypto-idb-snapshot.json` prima di `initRustCrypto` -- persistenza del contenuto IndexedDB aggiornato di nuovo in `crypto-idb-snapshot.json` dopo l'inizializzazione e durante il runtime -- serializzazione del ripristino e della persistenza dello snapshot rispetto a `crypto-idb-snapshot.json` con un lock file advisory così la persistenza del runtime del gateway e la manutenzione CLI non entrano in competizione sullo stesso file snapshot +- usa `fake-indexeddb` come shim API IndexedDB atteso dall'SDK +- ripristina il contenuto IndexedDB del Rust crypto da `crypto-idb-snapshot.json` prima di `initRustCrypto` +- salva il contenuto IndexedDB aggiornato di nuovo in `crypto-idb-snapshot.json` dopo l'inizializzazione e durante il runtime +- serializza il ripristino e la persistenza dello snapshot rispetto a `crypto-idb-snapshot.json` con un lock file advisory così che la persistenza runtime del gateway e la manutenzione CLI non vadano in concorrenza sullo stesso file snapshot Si tratta di infrastruttura di compatibilità/storage, non di un'implementazione crittografica personalizzata. -Il file snapshot è uno stato runtime sensibile ed è memorizzato con permessi di file restrittivi. -Nel modello di sicurezza di OpenClaw, l'host gateway e la directory di stato locale di OpenClaw sono già all'interno del confine dell'operatore fidato, quindi questa è principalmente una questione di durabilità operativa piuttosto che un confine di fiducia remoto separato. +Il file snapshot è uno stato runtime sensibile ed è memorizzato con permessi file restrittivi. +Nel modello di sicurezza di OpenClaw, l'host del gateway e la directory di stato locale di OpenClaw sono già all'interno del confine dell'operatore fidato, quindi questo è principalmente un problema di durabilità operativa piuttosto che un confine di fiducia remoto separato. Miglioramento pianificato: -- aggiungere il supporto SecretRef per il materiale di chiave Matrix persistente così recovery key e relativi secret di crittografia dello store possano provenire dai provider di secret OpenClaw invece che solo da file locali +- aggiungere il supporto SecretRef per il materiale chiave Matrix persistente così che le chiavi di ripristino e i relativi segreti di cifratura dello store possano essere ottenuti dai provider di segreti OpenClaw invece che solo da file locali ## Gestione del profilo -Aggiorna l'auto-profilo Matrix per l'account selezionato con: +Aggiorna il profilo Matrix dell'account selezionato con: ```bash openclaw matrix profile set --name "OpenClaw Assistant" openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png ``` -Aggiungi `--account ` quando vuoi puntare esplicitamente a un account Matrix con nome. +Aggiungi `--account ` quando vuoi prendere esplicitamente di mira un account Matrix con nome. -Matrix accetta direttamente URL avatar `mxc://`. Quando passi un URL avatar `http://` o `https://`, OpenClaw lo carica prima su Matrix e memorizza l'URL `mxc://` risolto in `channels.matrix.avatarUrl` (o nell'override dell'account selezionato). +Matrix accetta direttamente URL avatar `mxc://`. Quando passi un URL avatar `http://` o `https://`, OpenClaw lo carica prima su Matrix e memorizza l'URL `mxc://` risolto in `channels.matrix.avatarUrl` (o nella sovrascrittura dell'account selezionato). ## Avvisi automatici di verifica -Matrix ora pubblica gli avvisi del ciclo di vita della verifica direttamente nella stanza DM stretta di verifica come messaggi `m.notice`. -Questo include: +Matrix ora pubblica gli avvisi del ciclo di vita della verifica direttamente nella stanza DM di verifica rigorosa come messaggi `m.notice`. +Ciò include: - avvisi di richiesta di verifica -- avvisi di verifica pronta (con istruzioni esplicite "Verifica tramite emoji") +- avvisi di verifica pronta (con indicazioni esplicite "Verifica tramite emoji") - avvisi di inizio e completamento della verifica - dettagli SAS (emoji e decimali) quando disponibili -Le richieste di verifica in arrivo da un altro client Matrix vengono tracciate e accettate automaticamente da OpenClaw. +Le richieste di verifica in ingresso da un altro client Matrix vengono tracciate e accettate automaticamente da OpenClaw. Per i flussi di autoverifica, OpenClaw avvia automaticamente anche il flusso SAS quando la verifica tramite emoji diventa disponibile e conferma il proprio lato. Per le richieste di verifica da un altro utente/dispositivo Matrix, OpenClaw accetta automaticamente la richiesta e poi aspetta che il flusso SAS proceda normalmente. Devi comunque confrontare l'emoji o il SAS decimale nel tuo client Matrix e confermare lì "Corrispondono" per completare la verifica. -OpenClaw non accetta automaticamente alla cieca i flussi duplicati auto-avviati. All'avvio viene evitata la creazione di una nuova richiesta quando è già presente una richiesta di autoverifica in sospeso. +OpenClaw non accetta automaticamente alla cieca i flussi duplicati avviati da sé. All'avvio salta la creazione di una nuova richiesta quando una richiesta di autoverifica è già in sospeso. -Gli avvisi di protocollo/sistema della verifica non vengono inoltrati alla pipeline di chat dell'agente, quindi non producono `NO_REPLY`. +Gli avvisi di verifica di protocollo/sistema non vengono inoltrati alla pipeline della chat dell'agente, quindi non producono `NO_REPLY`. ### Igiene dei dispositivi -I vecchi dispositivi Matrix gestiti da OpenClaw possono accumularsi sull'account e rendere più difficile interpretare l'attendibilità delle stanze crittografate. +Sul tuo account possono accumularsi vecchi dispositivi Matrix gestiti da OpenClaw, rendendo più difficile interpretare l'affidabilità delle stanze cifrate. Elencali con: ```bash openclaw matrix devices list ``` -Rimuovi i dispositivi obsoleti gestiti da OpenClaw con: +Rimuovi i dispositivi OpenClaw obsoleti con: ```bash openclaw matrix devices prune-stale ``` -### Riparazione diretta della stanza +### Riparazione Direct Room -Se lo stato dei messaggi diretti va fuori sincronia, OpenClaw può ritrovarsi con mapping `m.direct` obsoleti che puntano a vecchie stanze singole invece che al DM attivo. Esamina il mapping corrente per un peer con: +Se lo stato dei messaggi diretti va fuori sincrono, OpenClaw può ritrovarsi con mapping `m.direct` obsoleti che puntano a vecchie stanze singole invece che al DM live. Ispeziona il mapping corrente per un peer con: ```bash openclaw matrix direct inspect --user-id @alice:example.org @@ -683,41 +690,41 @@ Riparalo con: openclaw matrix direct repair --user-id @alice:example.org ``` -La riparazione mantiene nel plugin la logica specifica di Matrix: +La riparazione mantiene la logica specifica di Matrix all'interno del plugin: -- preferisce un DM stretto 1:1 che è già mappato in `m.direct` -- altrimenti ricorre a qualsiasi DM stretto 1:1 attualmente unito con quell'utente -- se non esiste alcun DM integro, crea una nuova stanza diretta e riscrive `m.direct` perché punti a essa +- preferisce un DM rigoroso 1:1 già mappato in `m.direct` +- altrimenti ripiega su qualunque DM rigoroso 1:1 attualmente unito con quell'utente +- se non esiste alcun DM sano, crea una nuova stanza diretta e riscrive `m.direct` in modo che punti a essa -Il flusso di riparazione non elimina automaticamente le vecchie stanze. Seleziona solo il DM integro e aggiorna il mapping così nuovi invii Matrix, avvisi di verifica e altri flussi di messaggi diretti puntino di nuovo alla stanza corretta. +Il flusso di riparazione non elimina automaticamente le vecchie stanze. Si limita a scegliere il DM sano e aggiornare il mapping così che i nuovi invii Matrix, gli avvisi di verifica e gli altri flussi di messaggi diretti tornino a prendere di mira la stanza corretta. ## Thread -Matrix supporta i thread Matrix nativi sia per le risposte automatiche sia per gli invii con strumenti di messaggistica. +Matrix supporta i thread Matrix nativi sia per le risposte automatiche sia per gli invii del message tool. -- `dm.sessionScope: "per-user"` (predefinito) mantiene l'instradamento dei DM Matrix con ambito mittente, quindi più stanze DM possono condividere una sessione quando vengono risolte sullo stesso peer. -- `dm.sessionScope: "per-room"` isola ogni stanza DM Matrix nella propria chiave di sessione pur continuando a usare i normali controlli di autenticazione DM e allowlist. -- I binding espliciti di conversazione Matrix hanno comunque la precedenza su `dm.sessionScope`, quindi stanze e thread associati mantengono la sessione di destinazione scelta. -- `threadReplies: "off"` mantiene le risposte a livello superiore e mantiene i messaggi in ingresso nei thread sulla sessione padre. -- `threadReplies: "inbound"` risponde dentro un thread solo quando il messaggio in ingresso era già in quel thread. -- `threadReplies: "always"` mantiene le risposte delle stanze in un thread con radice nel messaggio attivante e instrada quella conversazione attraverso la sessione con ambito thread corrispondente a partire dal primo messaggio attivante. -- `dm.threadReplies` sovrascrive l'impostazione di livello superiore solo per i DM. Per esempio, puoi mantenere isolati i thread delle stanze mantenendo piatti i DM. -- I messaggi in ingresso nei thread includono il messaggio radice del thread come contesto agente aggiuntivo. -- Gli invii con strumenti di messaggistica ora ereditano automaticamente il thread Matrix corrente quando la destinazione è la stessa stanza, o lo stesso utente DM di destinazione, a meno che non venga fornito un `threadId` esplicito. -- Il riutilizzo della stessa sessione con destinazione utente DM si attiva solo quando i metadati della sessione corrente dimostrano lo stesso peer DM sullo stesso account Matrix; altrimenti OpenClaw torna al normale instradamento con ambito utente. -- Quando OpenClaw rileva che una stanza DM Matrix entra in collisione con un'altra stanza DM sulla stessa sessione DM Matrix condivisa, pubblica un `m.notice` una tantum in quella stanza con la via di fuga `/focus` quando i binding dei thread sono abilitati e con l'indicazione `dm.sessionScope`. -- I binding runtime dei thread sono supportati per Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` e `/acp spawn` associato a thread ora funzionano in stanze e DM Matrix. +- `dm.sessionScope: "per-user"` (predefinito) mantiene il routing DM Matrix con ambito mittente, quindi più stanze DM possono condividere una sessione quando si risolvono allo stesso peer. +- `dm.sessionScope: "per-room"` isola ogni stanza DM Matrix nella propria chiave di sessione pur continuando a usare normali controlli di autenticazione e allowlist dei DM. +- I binding espliciti delle conversazioni Matrix continuano ad avere la precedenza su `dm.sessionScope`, quindi stanze e thread associati mantengono la sessione di destinazione scelta. +- `threadReplies: "off"` mantiene le risposte al livello superiore e conserva i messaggi in thread in ingresso sulla sessione padre. +- `threadReplies: "inbound"` risponde all'interno di un thread solo quando il messaggio in ingresso era già in quel thread. +- `threadReplies: "always"` mantiene le risposte della stanza in un thread radicato nel messaggio che ha attivato la risposta e instrada quella conversazione attraverso la sessione con ambito thread corrispondente fin dal primo messaggio che l'ha attivata. +- `dm.threadReplies` sovrascrive l'impostazione di livello superiore solo per i DM. Ad esempio, puoi mantenere isolati i thread delle stanze lasciando piatti i DM. +- I messaggi in thread in ingresso includono il messaggio radice del thread come contesto aggiuntivo per l'agente. +- Gli invii del message tool ora ereditano automaticamente il thread Matrix corrente quando la destinazione è la stessa stanza, o lo stesso target utente DM, a meno che non venga fornito un `threadId` esplicito. +- Il riuso della stessa sessione per destinazione utente DM scatta solo quando i metadati della sessione corrente dimostrano lo stesso peer DM sullo stesso account Matrix; altrimenti OpenClaw torna al normale routing con ambito utente. +- Quando OpenClaw vede una stanza DM Matrix entrare in collisione con un'altra stanza DM sulla stessa sessione DM Matrix condivisa, pubblica un unico `m.notice` in quella stanza con l'uscita di emergenza `/focus` quando i binding dei thread sono abilitati e con il suggerimento `dm.sessionScope`. +- I binding runtime dei thread sono supportati per Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` e `/acp spawn` associato a un thread ora funzionano in stanze e DM Matrix. - `/focus` a livello superiore in una stanza/DM Matrix crea un nuovo thread Matrix e lo associa alla sessione di destinazione quando `threadBindings.spawnSubagentSessions=true`. - Eseguire `/focus` o `/acp spawn --thread here` all'interno di un thread Matrix esistente associa invece quel thread corrente. -## Binding di conversazione ACP +## Binding delle conversazioni ACP -Stanze, DM e thread Matrix esistenti possono essere trasformati in workspace ACP persistenti senza cambiare la superficie di chat. +Stanze Matrix, DM e thread Matrix esistenti possono essere trasformati in workspace ACP durevoli senza cambiare la superficie di chat. -Flusso rapido per operatori: +Flusso rapido per l'operatore: - Esegui `/acp spawn codex --bind here` nel DM Matrix, nella stanza o nel thread esistente che vuoi continuare a usare. -- In un DM o stanza Matrix di primo livello, il DM/stanza corrente rimane la superficie di chat e i messaggi futuri vengono instradati alla sessione ACP generata. +- In un DM o stanza Matrix di livello superiore, il DM/stanza corrente resta la superficie di chat e i messaggi futuri vengono instradati alla sessione ACP generata. - All'interno di un thread Matrix esistente, `--bind here` associa sul posto quel thread corrente. - `/new` e `/reset` reimpostano sul posto la stessa sessione ACP associata. - `/acp close` chiude la sessione ACP e rimuove il binding. @@ -727,9 +734,9 @@ Note: - `--bind here` non crea un thread Matrix figlio. - `threadBindings.spawnAcpSessions` è richiesto solo per `/acp spawn --thread auto|here`, quando OpenClaw deve creare o associare un thread Matrix figlio. -### Configurazione dei binding dei thread +### Configurazione Thread Binding -Matrix eredita i valori predefiniti globali da `session.threadBindings` e supporta anche override per canale: +Matrix eredita i valori predefiniti globali da `session.threadBindings` e supporta anche sovrascritture per canale: - `threadBindings.enabled` - `threadBindings.idleHours` @@ -737,29 +744,29 @@ Matrix eredita i valori predefiniti globali da `session.threadBindings` e suppor - `threadBindings.spawnSubagentSessions` - `threadBindings.spawnAcpSessions` -I flag di generazione associata a thread Matrix sono opt-in: +I flag di avvio associati ai thread Matrix sono opt-in: -- Imposta `threadBindings.spawnSubagentSessions: true` per consentire a `/focus` di primo livello di creare e associare nuovi thread Matrix. +- Imposta `threadBindings.spawnSubagentSessions: true` per consentire a `/focus` di livello superiore di creare e associare nuovi thread Matrix. - Imposta `threadBindings.spawnAcpSessions: true` per consentire a `/acp spawn --thread auto|here` di associare sessioni ACP ai thread Matrix. ## Reazioni -Matrix supporta azioni di reazione in uscita, notifiche di reazione in ingresso e reazioni di ack in ingresso. +Matrix supporta azioni di reazione in uscita, notifiche di reazione in ingresso e reazioni ack in ingresso. -- Gli strumenti di reazione in uscita sono controllati da `channels["matrix"].actions.reactions`. +- Il tooling delle reazioni in uscita è controllato da `channels["matrix"].actions.reactions`. - `react` aggiunge una reazione a uno specifico evento Matrix. - `reactions` elenca il riepilogo corrente delle reazioni per uno specifico evento Matrix. - `emoji=""` rimuove le reazioni dell'account bot su quell'evento. -- `remove: true` rimuove solo la reazione con l'emoji specificata dall'account bot. +- `remove: true` rimuove solo la specifica reazione emoji dall'account bot. -L'ambito delle reazioni di ack viene risolto nell'ordine standard di OpenClaw: +L'ambito delle reazioni ack viene risolto in base a questo ordine: - `channels["matrix"].accounts..ackReaction` - `channels["matrix"].ackReaction` - `messages.ackReaction` -- fallback all'emoji di identità dell'agente +- fallback all'emoji dell'identità dell'agente -L'ambito della reazione di ack viene risolto in questo ordine: +L'ambito della reazione ack viene risolto in questo ordine: - `channels["matrix"].accounts..ackReactionScope` - `channels["matrix"].ackReactionScope` @@ -773,29 +780,29 @@ La modalità di notifica delle reazioni viene risolta in questo ordine: Comportamento attuale: -- `reactionNotifications: "own"` inoltra gli eventi `m.reaction` aggiunti quando puntano a messaggi Matrix creati dal bot. +- `reactionNotifications: "own"` inoltra gli eventi `m.reaction` aggiunti quando prendono di mira messaggi Matrix scritti dal bot. - `reactionNotifications: "off"` disabilita gli eventi di sistema delle reazioni. -- Le rimozioni delle reazioni non vengono ancora sintetizzate in eventi di sistema perché Matrix le espone come redazioni, non come rimozioni autonome di `m.reaction`. +- Le rimozioni di reazione non vengono ancora sintetizzate in eventi di sistema perché Matrix le espone come redazioni, non come rimozioni `m.reaction` autonome. ## Contesto della cronologia -- `channels.matrix.historyLimit` controlla quanti messaggi recenti della stanza sono inclusi come `InboundHistory` quando un messaggio di una stanza Matrix attiva l'agente. -- Come fallback usa `messages.groupChat.historyLimit`. Imposta `0` per disabilitare. +- `channels.matrix.historyLimit` controlla quanti messaggi recenti della stanza vengono inclusi come `InboundHistory` quando un messaggio di una stanza Matrix attiva l'agente. +- Usa come fallback `messages.groupChat.historyLimit`. Se entrambi non sono impostati, il valore predefinito effettivo è `0`, quindi i messaggi di stanza con attivazione tramite menzione non vengono bufferizzati. Imposta `0` per disabilitare. - La cronologia delle stanze Matrix è solo di stanza. I DM continuano a usare la normale cronologia della sessione. -- La cronologia delle stanze Matrix è solo pending: OpenClaw mette in buffer i messaggi della stanza che non hanno ancora attivato una risposta, poi cattura uno snapshot di quella finestra quando arriva una menzione o un altro trigger. -- Il messaggio trigger corrente non è incluso in `InboundHistory`; rimane nel corpo principale in ingresso per quel turno. -- I retry dello stesso evento Matrix riutilizzano lo snapshot originale della cronologia invece di avanzare verso messaggi della stanza più recenti. +- La cronologia delle stanze Matrix è solo pending: OpenClaw bufferizza i messaggi della stanza che non hanno ancora attivato una risposta, poi acquisisce uno snapshot di quella finestra quando arriva una menzione o un altro trigger. +- Il messaggio di attivazione corrente non è incluso in `InboundHistory`; resta nel corpo principale in ingresso per quel turno. +- I tentativi ripetuti dello stesso evento Matrix riutilizzano lo snapshot originale della cronologia invece di spostarsi in avanti verso messaggi di stanza più recenti. ## Visibilità del contesto -Matrix supporta il controllo condiviso `contextVisibility` per il contesto supplementare della stanza come testo di risposta recuperato, radici dei thread e cronologia pending. +Matrix supporta il controllo condiviso `contextVisibility` per il contesto supplementare della stanza, come testo di risposta recuperato, radici dei thread e cronologia pending. - `contextVisibility: "all"` è il valore predefinito. Il contesto supplementare viene mantenuto così come ricevuto. -- `contextVisibility: "allowlist"` filtra il contesto supplementare ai mittenti consentiti dai controlli attivi di allowlist della stanza/utente. +- `contextVisibility: "allowlist"` filtra il contesto supplementare ai mittenti consentiti dai controlli attivi della allowlist di stanza/utente. - `contextVisibility: "allowlist_quote"` si comporta come `allowlist`, ma mantiene comunque una risposta citata esplicita. -Questa impostazione influisce sulla visibilità del contesto supplementare, non sulla possibilità che il messaggio in ingresso stesso attivi una risposta. -L'autorizzazione del trigger continua a derivare da `groupPolicy`, `groups`, `groupAllowFrom` e dalle impostazioni di policy DM. +Questa impostazione influisce sulla visibilità del contesto supplementare, non sul fatto che il messaggio in ingresso stesso possa attivare una risposta. +L'autorizzazione del trigger continua a dipendere da `groupPolicy`, `groups`, `groupAllowFrom` e dalle impostazioni dei criteri DM. ## Esempio di policy per DM e stanze @@ -820,56 +827,56 @@ L'autorizzazione del trigger continua a derivare da `groupPolicy`, `groups`, `gr } ``` -Vedi [Groups](/it/channels/groups) per il comportamento di gating delle menzioni e della allowlist. +Vedi [Groups](/it/channels/groups) per il comportamento della menzione obbligatoria e della allowlist. -Esempio di pairing per DM Matrix: +Esempio di pairing per i DM Matrix: ```bash openclaw pairing list matrix openclaw pairing approve matrix ``` -Se un utente Matrix non approvato continua a scriverti prima dell'approvazione, OpenClaw riutilizza lo stesso codice di pairing in sospeso e può inviare di nuovo una risposta di promemoria dopo un breve cooldown invece di generare un nuovo codice. +Se un utente Matrix non approvato continua a inviarti messaggi prima dell'approvazione, OpenClaw riutilizza lo stesso codice di pairing in sospeso e può inviare di nuovo una risposta di promemoria dopo un breve cooldown invece di generarne uno nuovo. -Vedi [Pairing](/it/channels/pairing) per il flusso condiviso di pairing DM e il layout di storage. +Vedi [Pairing](/it/channels/pairing) per il flusso condiviso di pairing dei DM e il layout di storage. ## Approvazioni exec Matrix può agire come client di approvazione exec per un account Matrix. - `channels.matrix.execApprovals.enabled` -- `channels.matrix.execApprovals.approvers` (facoltativo; come fallback usa `channels.matrix.dm.allowFrom`) +- `channels.matrix.execApprovals.approvers` (facoltativo; usa come fallback `channels.matrix.dm.allowFrom`) - `channels.matrix.execApprovals.target` (`dm` | `channel` | `both`, predefinito: `dm`) - `channels.matrix.execApprovals.agentFilter` - `channels.matrix.execApprovals.sessionFilter` -Gli approvatori devono essere ID utente Matrix come `@owner:example.org`. Matrix abilita automaticamente le approvazioni exec native quando `enabled` non è impostato oppure è `"auto"` e può essere risolto almeno un approvatore, da `execApprovals.approvers` oppure da `channels.matrix.dm.allowFrom`. Imposta `enabled: false` per disabilitare esplicitamente Matrix come client di approvazione nativo. In caso contrario, le richieste di approvazione ricadono su altre route di approvazione configurate o sulla policy di fallback di approvazione exec. +Gli approvatori devono essere ID utente Matrix come `@owner:example.org`. Matrix abilita automaticamente le approvazioni exec native quando `enabled` non è impostato oppure è `"auto"` e almeno un approvatore può essere risolto, sia da `execApprovals.approvers` sia da `channels.matrix.dm.allowFrom`. Imposta `enabled: false` per disabilitare esplicitamente Matrix come client di approvazione nativo. Altrimenti le richieste di approvazione usano come fallback altri percorsi di approvazione configurati o la policy di fallback per l'approvazione exec. -L'instradamento nativo Matrix oggi è solo per exec: +Il routing nativo Matrix oggi è solo per exec: -- `channels.matrix.execApprovals.*` controlla l'instradamento nativo DM/canale solo per le approvazioni exec. -- Le approvazioni dei plugin continuano a usare `/approve` condiviso nella stessa chat più qualsiasi inoltro configurato in `approvals.plugin`. -- Matrix può comunque riutilizzare `channels.matrix.dm.allowFrom` per l'autorizzazione delle approvazioni plugin quando può dedurre in sicurezza gli approvatori, ma non espone un percorso separato nativo DM/canale per il fanout delle approvazioni plugin. +- `channels.matrix.execApprovals.*` controlla il routing DM/canale nativo solo per le approvazioni exec. +- Le approvazioni dei plugin usano ancora il comando condiviso `/approve` nella stessa chat più l'eventuale inoltro configurato in `approvals.plugin`. +- Matrix può ancora riutilizzare `channels.matrix.dm.allowFrom` per l'autorizzazione delle approvazioni dei plugin quando può dedurre in sicurezza gli approvatori, ma non espone un percorso nativo separato di fanout DM/canale per le approvazioni dei plugin. Regole di consegna: - `target: "dm"` invia i prompt di approvazione ai DM degli approvatori -- `target: "channel"` invia il prompt alla stanza Matrix o al DM di origine -- `target: "both"` invia ai DM degli approvatori e alla stanza Matrix o al DM di origine +- `target: "channel"` rimanda il prompt alla stanza o al DM Matrix di origine +- `target: "both"` invia ai DM degli approvatori e alla stanza o al DM Matrix di origine -I prompt di approvazione Matrix inizializzano scorciatoie tramite reazione sul messaggio di approvazione principale: +I prompt di approvazione Matrix inizializzano scorciatoie tramite reazioni sul messaggio di approvazione principale: - `✅` = consenti una volta - `❌` = nega - `♾️` = consenti sempre quando quella decisione è permessa dalla policy exec effettiva -Gli approvatori possono reagire su quel messaggio oppure usare i comandi slash di fallback: `/approve allow-once`, `/approve allow-always` oppure `/approve deny`. +Gli approvatori possono reagire a quel messaggio o usare i comandi slash di fallback: `/approve allow-once`, `/approve allow-always` oppure `/approve deny`. Solo gli approvatori risolti possono approvare o negare. La consegna sul canale include il testo del comando, quindi abilita `channel` o `both` solo in stanze fidate. -I prompt di approvazione Matrix riutilizzano il planner condiviso di approvazione core. La superficie nativa specifica di Matrix è solo di trasporto per le approvazioni exec: instradamento stanza/DM e comportamento di invio/aggiornamento/eliminazione dei messaggi. +I prompt di approvazione Matrix riutilizzano il planner di approvazione condiviso del core. La superficie nativa specifica di Matrix è solo il trasporto per le approvazioni exec: routing stanza/DM e comportamento di invio/aggiornamento/eliminazione dei messaggi. -Override per account: +Sovrascrittura per account: - `channels.matrix.accounts..execApprovals` @@ -905,21 +912,21 @@ Documentazione correlata: [Exec approvals](/it/tools/exec-approvals) } ``` -I valori di primo livello `channels.matrix` agiscono come predefiniti per gli account con nome a meno che un account non li sovrascriva. -Puoi assegnare una voce stanza ereditata a un solo account Matrix con `groups..account` (o il legacy `rooms..account`). -Le voci senza `account` rimangono condivise tra tutti gli account Matrix, e le voci con `account: "default"` continuano a funzionare quando l'account predefinito è configurato direttamente in `channels.matrix.*` di primo livello. -I predefiniti di autenticazione condivisa parziale non creano da soli un account predefinito implicito separato. OpenClaw sintetizza l'account `default` di primo livello solo quando quel predefinito ha autenticazione fresca (`homeserver` più `accessToken`, oppure `homeserver` più `userId` e `password`); gli account con nome possono comunque rimanere individuabili da `homeserver` più `userId` quando le credenziali nella cache soddisfano in seguito l'autenticazione. -Se Matrix ha già esattamente un account con nome, oppure `defaultAccount` punta a una chiave account con nome esistente, la promozione di riparazione/configurazione da account singolo a multi-account preserva quell'account invece di creare una nuova voce `accounts.default`. Solo le chiavi di autenticazione/bootstrap Matrix vengono spostate in quell'account promosso; le chiavi condivise di policy di consegna restano al livello superiore. -Imposta `defaultAccount` quando vuoi che OpenClaw preferisca un account Matrix con nome per instradamento implicito, probing e operazioni CLI. +I valori di livello superiore in `channels.matrix` fungono da predefiniti per gli account con nome, a meno che un account non li sovrascriva. +Puoi assegnare una voce stanza ereditata a un singolo account Matrix con `groups..account` (o il legacy `rooms..account`). +Le voci senza `account` restano condivise tra tutti gli account Matrix, e le voci con `account: "default"` continuano a funzionare quando l'account predefinito è configurato direttamente al livello superiore in `channels.matrix.*`. +I predefiniti di autenticazione condivisa parziale non creano da soli un account predefinito implicito separato. OpenClaw sintetizza l'account `default` di livello superiore solo quando quel predefinito ha autenticazione valida (`homeserver` più `accessToken`, oppure `homeserver` più `userId` e `password`); gli account con nome possono comunque restare individuabili da `homeserver` più `userId` quando in seguito le credenziali in cache soddisfano l'autenticazione. +Se Matrix ha già esattamente un account con nome, oppure `defaultAccount` punta a una chiave account con nome esistente, la promozione di riparazione/configurazione da account singolo a multi-account preserva quell'account invece di creare una nuova voce `accounts.default`. Solo le chiavi di autenticazione/bootstrap Matrix vengono spostate in quell'account promosso; le chiavi condivise della policy di consegna restano al livello superiore. +Imposta `defaultAccount` quando vuoi che OpenClaw preferisca un account Matrix con nome per routing implicito, probing e operazioni CLI. Se configuri più account con nome, imposta `defaultAccount` oppure passa `--account ` per i comandi CLI che dipendono dalla selezione implicita dell'account. -Passa `--account ` a `openclaw matrix verify ...` e `openclaw matrix devices ...` quando vuoi sovrascrivere quella selezione implicita per un comando. +Passa `--account ` a `openclaw matrix verify ...` e `openclaw matrix devices ...` quando vuoi sovrascrivere quella selezione implicita per un singolo comando. ## Homeserver privati/LAN -Per impostazione predefinita, OpenClaw blocca gli homeserver Matrix privati/interni per la protezione SSRF a meno che tu -non scelga esplicitamente l'opt-in per account. +Per impostazione predefinita, OpenClaw blocca gli homeserver Matrix privati/interni per protezione SSRF, a meno che tu +non faccia esplicitamente opt-in per account. -Se il tuo homeserver è in esecuzione su localhost, su un IP LAN/Tailscale o su un hostname interno, abilita +Se il tuo homeserver gira su localhost, un IP LAN/Tailscale o un hostname interno, abilita `allowPrivateNetwork` per quell'account Matrix: ```json5 @@ -934,7 +941,7 @@ Se il tuo homeserver è in esecuzione su localhost, su un IP LAN/Tailscale o su } ``` -Esempio di configurazione CLI: +Esempio di configurazione tramite CLI: ```bash openclaw matrix account add \ @@ -947,9 +954,9 @@ openclaw matrix account add \ Questo opt-in consente solo target privati/interni fidati. Gli homeserver pubblici in chiaro come `http://matrix.example.org:8008` restano bloccati. Preferisci `https://` quando possibile. -## Instradamento del traffico Matrix tramite proxy +## Proxy del traffico Matrix -Se il tuo deployment Matrix richiede un proxy HTTP(S) in uscita esplicito, imposta `channels.matrix.proxy`: +Se il tuo deployment Matrix richiede un proxy HTTP(S) esplicito in uscita, imposta `channels.matrix.proxy`: ```json5 { @@ -963,12 +970,12 @@ Se il tuo deployment Matrix richiede un proxy HTTP(S) in uscita esplicito, impos } ``` -Gli account con nome possono sovrascrivere il valore predefinito di primo livello con `channels.matrix.accounts..proxy`. -OpenClaw usa la stessa impostazione proxy per il traffico Matrix a runtime e per i probe dello stato dell'account. +Gli account con nome possono sovrascrivere il valore predefinito di livello superiore con `channels.matrix.accounts..proxy`. +OpenClaw usa la stessa impostazione proxy per il traffico Matrix runtime e per i probe dello stato dell'account. -## Risoluzione del target +## Risoluzione della destinazione -Matrix accetta queste forme di target ovunque OpenClaw ti chieda un target stanza o utente: +Matrix accetta questi formati di destinazione ovunque OpenClaw ti chieda una stanza o un target utente: - Utenti: `@user:server`, `user:@user:server` o `matrix:user:@user:server` - Stanze: `!room:server`, `room:!room:server` o `matrix:room:!room:server` @@ -977,72 +984,73 @@ Matrix accetta queste forme di target ovunque OpenClaw ti chieda un target stanz La ricerca live nella directory usa l'account Matrix autenticato: - Le ricerche utente interrogano la directory utenti Matrix su quell'homeserver. -- Le ricerche stanza accettano direttamente ID stanza e alias espliciti, poi ripiegano sulla ricerca dei nomi delle stanze a cui quell'account ha aderito. -- La ricerca per nome nelle stanze aderite è best-effort. Se un nome stanza non può essere risolto in un ID o alias, viene ignorato dalla risoluzione della allowlist a runtime. +- Le ricerche stanza accettano direttamente ID stanza e alias espliciti, poi ripiegano sulla ricerca dei nomi delle stanze unite per quell'account. +- La ricerca dei nomi delle stanze unite è best-effort. Se un nome stanza non può essere risolto in un ID o alias, viene ignorato dalla risoluzione runtime della allowlist. -## Riferimento della configurazione +## Riferimento configurazione - `enabled`: abilita o disabilita il canale. - `name`: etichetta facoltativa per l'account. - `defaultAccount`: ID account preferito quando sono configurati più account Matrix. -- `homeserver`: URL dell'homeserver, per esempio `https://matrix.example.org`. -- `allowPrivateNetwork`: consente a questo account Matrix di connettersi a homeserver privati/interni. Abilitalo quando l'homeserver viene risolto in `localhost`, un IP LAN/Tailscale o un host interno come `matrix-synapse`. -- `proxy`: URL facoltativo del proxy HTTP(S) per il traffico Matrix. Gli account con nome possono sovrascrivere il valore predefinito di primo livello con il proprio `proxy`. -- `userId`: ID utente Matrix completo, per esempio `@bot:example.org`. -- `accessToken`: access token per autenticazione basata su token. Sono supportati valori in chiaro e valori SecretRef per `channels.matrix.accessToken` e `channels.matrix.accounts..accessToken` tramite provider env/file/exec. Vedi [Secrets Management](/it/gateway/secrets). +- `homeserver`: URL dell'homeserver, ad esempio `https://matrix.example.org`. +- `allowPrivateNetwork`: consente a questo account Matrix di connettersi a homeserver privati/interni. Abilitalo quando l'homeserver si risolve in `localhost`, un IP LAN/Tailscale o un host interno come `matrix-synapse`. +- `proxy`: URL facoltativo del proxy HTTP(S) per il traffico Matrix. Gli account con nome possono sovrascrivere il valore predefinito di livello superiore con il proprio `proxy`. +- `userId`: ID utente Matrix completo, ad esempio `@bot:example.org`. +- `accessToken`: token di accesso per l'autenticazione basata su token. Sono supportati valori in chiaro e valori SecretRef per `channels.matrix.accessToken` e `channels.matrix.accounts..accessToken` tramite provider env/file/exec. Vedi [Secrets Management](/it/gateway/secrets). - `password`: password per il login basato su password. Sono supportati valori in chiaro e valori SecretRef. - `deviceId`: ID dispositivo Matrix esplicito. - `deviceName`: nome visualizzato del dispositivo per il login con password. -- `avatarUrl`: URL dell'avatar del profilo memorizzato per la sincronizzazione del profilo e gli aggiornamenti `set-profile`. -- `initialSyncLimit`: limite degli eventi di sincronizzazione all'avvio. +- `avatarUrl`: URL avatar personale memorizzato per la sincronizzazione del profilo e gli aggiornamenti `set-profile`. +- `initialSyncLimit`: limite eventi della sincronizzazione all'avvio. - `encryption`: abilita E2EE. -- `allowlistOnly`: forza comportamento solo allowlist per DM e stanze. +- `allowlistOnly`: forza un comportamento solo allowlist per DM e stanze. - `allowBots`: consente messaggi da altri account Matrix OpenClaw configurati (`true` o `"mentions"`). - `groupPolicy`: `open`, `allowlist` o `disabled`. - `contextVisibility`: modalità di visibilità del contesto supplementare della stanza (`all`, `allowlist`, `allowlist_quote`). - `groupAllowFrom`: allowlist di ID utente per il traffico delle stanze. -- Le voci `groupAllowFrom` devono essere ID utente Matrix completi. I nomi non risolti vengono ignorati a runtime. -- `historyLimit`: numero massimo di messaggi della stanza da includere come contesto della cronologia di gruppo. Come fallback usa `messages.groupChat.historyLimit`. Imposta `0` per disabilitare. +- Le voci di `groupAllowFrom` dovrebbero essere ID utente Matrix completi. I nomi non risolti vengono ignorati in fase runtime. +- `historyLimit`: numero massimo di messaggi della stanza da includere come contesto della cronologia del gruppo. Usa come fallback `messages.groupChat.historyLimit`; se entrambi non sono impostati, il valore predefinito effettivo è `0`. Imposta `0` per disabilitare. - `replyToMode`: `off`, `first` o `all`. -- `markdown`: configurazione facoltativa del rendering Markdown per il testo Matrix in uscita. -- `streaming`: `off` (predefinito), `partial`, `quiet`, `true` o `false`. `partial` e `true` abilitano aggiornamenti di bozza con anteprima iniziale usando normali messaggi di testo Matrix. `quiet` usa avvisi di anteprima senza notifica per configurazioni push-rule self-hosted. -- `blockStreaming`: `true` abilita messaggi di avanzamento separati per i blocchi completati dell'assistente mentre è attivo lo streaming della bozza di anteprima. +- `markdown`: configurazione facoltativa di rendering Markdown per il testo Matrix in uscita. +- `streaming`: `off` (predefinito), `partial`, `quiet`, `true` o `false`. `partial` e `true` abilitano aggiornamenti della bozza con anteprima iniziale usando normali messaggi di testo Matrix. `quiet` usa avvisi di anteprima senza notifica per configurazioni self-hosted con regole push. +- `blockStreaming`: `true` abilita messaggi di avanzamento separati per i blocchi dell'assistente completati mentre l'anteprima in streaming della bozza è attiva. - `threadReplies`: `off`, `inbound` o `always`. -- `threadBindings`: override per canale per instradamento e ciclo di vita delle sessioni associate ai thread. -- `startupVerification`: modalità automatica di richiesta di autoverifica all'avvio (`if-unverified`, `off`). +- `threadBindings`: sovrascritture per canale per il routing e il ciclo di vita delle sessioni associate ai thread. +- `startupVerification`: modalità automatica della richiesta di autoverifica all'avvio (`if-unverified`, `off`). - `startupVerificationCooldownHours`: cooldown prima di ritentare richieste automatiche di verifica all'avvio. - `textChunkLimit`: dimensione dei chunk dei messaggi in uscita. - `chunkMode`: `length` o `newline`. -- `responsePrefix`: prefisso facoltativo del messaggio per le risposte in uscita. -- `ackReaction`: override facoltativo della reazione di ack per questo canale/account. -- `ackReactionScope`: override facoltativo dell'ambito della reazione di ack (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`). -- `reactionNotifications`: modalità di notifica delle reazioni in ingresso (`own`, `off`). +- `responsePrefix`: prefisso di messaggio facoltativo per le risposte in uscita. +- `ackReaction`: sovrascrittura facoltativa della reazione ack per questo canale/account. +- `ackReactionScope`: sovrascrittura facoltativa dell'ambito della reazione ack (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`). +- `reactionNotifications`: modalità delle notifiche di reazione in ingresso (`own`, `off`). - `mediaMaxMb`: limite di dimensione dei contenuti multimediali in MB per la gestione Matrix. Si applica agli invii in uscita e all'elaborazione dei contenuti multimediali in ingresso. -- `autoJoin`: policy di auto-join agli inviti (`always`, `allowlist`, `off`). Predefinito: `off`. -- `autoJoinAllowlist`: stanze/alias consentiti quando `autoJoin` è `allowlist`. Le voci alias vengono risolte in ID stanza durante la gestione dell'invito; OpenClaw non si fida dello stato alias dichiarato dalla stanza invitante. -- `dm`: blocco di policy DM (`enabled`, `policy`, `allowFrom`, `sessionScope`, `threadReplies`). -- Le voci `dm.allowFrom` devono essere ID utente Matrix completi a meno che tu non le abbia già risolte tramite ricerca live nella directory. +- `autoJoin`: policy di auto-join degli inviti (`always`, `allowlist`, `off`). Predefinito: `off`. Si applica agli inviti Matrix in generale, inclusi gli inviti in stile DM, non solo agli inviti di stanze/gruppi. OpenClaw prende questa decisione al momento dell'invito, prima di poter classificare in modo affidabile la stanza unita come DM o gruppo. +- `autoJoinAllowlist`: stanze/alias consentiti quando `autoJoin` è `allowlist`. Le voci alias vengono risolte in ID stanza durante la gestione dell'invito; OpenClaw non si fida dello stato alias dichiarato dalla stanza invitata. +- `dm`: blocco della policy DM (`enabled`, `policy`, `allowFrom`, `sessionScope`, `threadReplies`). +- `dm.policy`: controlla l'accesso DM dopo che OpenClaw è entrato nella stanza e l'ha classificata come DM. Non modifica se un invito venga accettato automaticamente. +- Le voci di `dm.allowFrom` dovrebbero essere ID utente Matrix completi a meno che tu non le abbia già risolte tramite ricerca live nella directory. - `dm.sessionScope`: `per-user` (predefinito) o `per-room`. Usa `per-room` quando vuoi che ogni stanza DM Matrix mantenga un contesto separato anche se il peer è lo stesso. -- `dm.threadReplies`: override della policy dei thread solo per DM (`off`, `inbound`, `always`). Sovrascrive l'impostazione `threadReplies` di primo livello sia per il posizionamento delle risposte sia per l'isolamento delle sessioni nei DM. -- `execApprovals`: consegna nativa delle approvazioni exec Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`). +- `dm.threadReplies`: sovrascrittura della policy thread solo per i DM (`off`, `inbound`, `always`). Sovrascrive l'impostazione `threadReplies` di livello superiore sia per il posizionamento delle risposte sia per l'isolamento della sessione nei DM. +- `execApprovals`: consegna di approvazione exec nativa Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`). - `execApprovals.approvers`: ID utente Matrix autorizzati ad approvare richieste exec. Facoltativo quando `dm.allowFrom` identifica già gli approvatori. - `execApprovals.target`: `dm | channel | both` (predefinito: `dm`). -- `accounts`: override con nome per account. I valori di primo livello `channels.matrix` agiscono come predefiniti per queste voci. -- `groups`: mappa di policy per stanza. Preferisci ID stanza o alias; i nomi stanza non risolti vengono ignorati a runtime. L'identità di sessione/gruppo usa l'ID stanza stabile dopo la risoluzione, mentre le etichette leggibili restano basate sui nomi stanza. +- `accounts`: sovrascritture nominate per account. I valori di livello superiore in `channels.matrix` fungono da predefiniti per queste voci. +- `groups`: mappa delle policy per stanza. Preferisci ID stanza o alias; i nomi stanza non risolti vengono ignorati in fase runtime. L'identità di sessione/gruppo usa l'ID stanza stabile dopo la risoluzione, mentre le etichette leggibili restano derivate dai nomi delle stanze. - `groups..account`: limita una voce stanza ereditata a uno specifico account Matrix nelle configurazioni multi-account. -- `groups..allowBots`: override a livello stanza per mittenti bot configurati (`true` o `"mentions"`). +- `groups..allowBots`: sovrascrittura a livello stanza per mittenti bot configurati (`true` o `"mentions"`). - `groups..users`: allowlist dei mittenti per stanza. -- `groups..tools`: override per stanza di consenti/nega per gli strumenti. -- `groups..autoReply`: override a livello stanza del gating delle menzioni. `true` disabilita i requisiti di menzione per quella stanza; `false` li forza nuovamente. +- `groups..tools`: sovrascritture per stanza di allow/deny dei tool. +- `groups..autoReply`: sovrascrittura a livello stanza della menzione obbligatoria. `true` disabilita i requisiti di menzione per quella stanza; `false` li forza di nuovo. - `groups..skills`: filtro facoltativo delle Skills a livello stanza. -- `groups..systemPrompt`: snippet facoltativo di system prompt a livello stanza. -- `rooms`: alias legacy per `groups`. -- `actions`: gating per strumento per azione (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`). +- `groups..systemPrompt`: frammento facoltativo di system prompt a livello stanza. +- `rooms`: alias legacy di `groups`. +- `actions`: controllo per azione dei tool (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`). ## Correlati - [Channels Overview](/it/channels) — tutti i canali supportati - [Pairing](/it/channels/pairing) — autenticazione DM e flusso di pairing -- [Groups](/it/channels/groups) — comportamento della chat di gruppo e gating delle menzioni -- [Channel Routing](/it/channels/channel-routing) — instradamento della sessione per i messaggi +- [Groups](/it/channels/groups) — comportamento delle chat di gruppo e menzione obbligatoria +- [Channel Routing](/it/channels/channel-routing) — routing di sessione per i messaggi - [Security](/it/gateway/security) — modello di accesso e hardening diff --git a/docs/it/channels/slack.md b/docs/it/channels/slack.md index 3af5991b2..0daebaed2 100644 --- a/docs/it/channels/slack.md +++ b/docs/it/channels/slack.md @@ -1,30 +1,30 @@ --- read_when: - Configurazione di Slack o debug della modalità socket/HTTP di Slack -summary: Configurazione di Slack e comportamento di runtime (Socket Mode + HTTP Events API) +summary: Configurazione di Slack e comportamento di runtime (Socket Mode + URL di richiesta HTTP) title: Slack x-i18n: - generated_at: "2026-04-06T03:07:03Z" + generated_at: "2026-04-06T08:16:06Z" model: gpt-5.4 provider: openai - source_hash: 7e4ff2ce7d92276d62f4f3d3693ddb56ca163d5fdc2f1082ff7ba3421fada69c + source_hash: 897001c13d400cc8387a27000b82dd4c0512b2b88e2fe47785634aed8b7ab7af source_path: channels/slack.md workflow: 15 --- # Slack -Stato: pronto per la produzione per DM + canali tramite integrazioni dell'app Slack. La modalità predefinita è Socket Mode; è supportata anche la modalità HTTP Events API. +Stato: pronto per la produzione per DM + canali tramite integrazioni dell'app Slack. La modalità predefinita è Socket Mode; sono supportati anche gli URL di richiesta HTTP. I DM di Slack usano per impostazione predefinita la modalità di abbinamento. - Comportamento dei comandi nativo e catalogo dei comandi. + Comportamento nativo dei comandi e catalogo dei comandi. - Diagnostica cross-channel e playbook di ripristino. + Diagnostica tra canali e procedure di riparazione. @@ -33,7 +33,7 @@ Stato: pronto per la produzione per DM + canali tramite integrazioni dell'app Sl - + Nelle impostazioni dell'app Slack: - abilita **Socket Mode** @@ -75,7 +75,7 @@ SLACK_BOT_TOKEN=xoxb-... - `channel_rename` - `pin_added`, `pin_removed` - Abilita anche App Home **Messages Tab** per i DM. + Abilita anche la **Messages Tab** di App Home per i DM. @@ -89,13 +89,13 @@ openclaw gateway - + - imposta la modalità su HTTP (`channels.slack.mode="http"`) - copia il **Signing Secret** di Slack - - imposta Event Subscriptions + Interactivity + l'URL di richiesta del comando Slash sullo stesso percorso webhook (predefinito `/slack/events`) + - imposta l'URL di richiesta di Event Subscriptions + Interactivity + Slash command sullo stesso percorso webhook (predefinito `/slack/events`) @@ -120,7 +120,7 @@ openclaw gateway La modalità HTTP per account è supportata. - Assegna a ogni account un `webhookPath` distinto in modo che le registrazioni non vadano in conflitto. + Assegna a ogni account un `webhookPath` distinto in modo che le registrazioni non entrino in conflitto. @@ -129,8 +129,8 @@ openclaw gateway ## Checklist di manifest e scope - - + + ```json { @@ -205,8 +205,98 @@ openclaw gateway } ``` - + + + +```json +{ + "display_information": { + "name": "OpenClaw", + "description": "Slack connector for OpenClaw" + }, + "features": { + "bot_user": { + "display_name": "OpenClaw", + "always_online": true + }, + "app_home": { + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + }, + "slash_commands": [ + { + "command": "/openclaw", + "description": "Send a message to OpenClaw", + "should_escape": false, + "url": "https://gateway-host.example.com/slack/events" + } + ] + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "emoji:read", + "files:read", + "files:write", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "mpim:history", + "mpim:read", + "mpim:write", + "pins:read", + "pins:write", + "reactions:read", + "reactions:write", + "users:read" + ] + } + }, + "settings": { + "event_subscriptions": { + "request_url": "https://gateway-host.example.com/slack/events", + "bot_events": [ + "app_mention", + "channel_rename", + "member_joined_channel", + "member_left_channel", + "message.channels", + "message.groups", + "message.im", + "message.mpim", + "pin_added", + "pin_removed", + "reaction_added", + "reaction_removed" + ] + }, + "interactivity": { + "is_enabled": true, + "request_url": "https://gateway-host.example.com/slack/events", + "message_menu_options_url": "https://gateway-host.example.com/slack/events" + } + } +} +``` + + + + + + + Aggiungi lo scope bot `chat:write.customize` se vuoi che i messaggi in uscita usino l'identità dell'agente attivo (nome utente e icona personalizzati) invece dell'identità predefinita dell'app Slack. + + Se usi un'icona emoji, Slack si aspetta la sintassi `:emoji_name:`. + Se configuri `channels.slack.userToken`, gli scope di lettura tipici sono: @@ -216,7 +306,7 @@ openclaw gateway - `reactions:read` - `pins:read` - `emoji:read` - - `search:read` (se dipendi dalle letture della ricerca di Slack) + - `search:read` (se dipendi dalle letture di ricerca di Slack) @@ -227,27 +317,26 @@ openclaw gateway - La modalità HTTP richiede `botToken` + `signingSecret`. - `botToken`, `appToken`, `signingSecret` e `userToken` accettano stringhe in chiaro o oggetti SecretRef. -- I token nella configurazione sovrascrivono il fallback env. +- I token di configurazione hanno la precedenza sul fallback env. - Il fallback env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` si applica solo all'account predefinito. -- `userToken` (`xoxp-...`) è solo di configurazione (nessun fallback env) e usa per impostazione predefinita un comportamento di sola lettura (`userTokenReadOnly: true`). -- Facoltativo: aggiungi `chat:write.customize` se vuoi che i messaggi in uscita usino l'identità dell'agente attivo (con `username` e icona personalizzati). `icon_emoji` usa la sintassi `:emoji_name:`. +- `userToken` (`xoxp-...`) è solo di configurazione (nessun fallback env) e per impostazione predefinita usa un comportamento di sola lettura (`userTokenReadOnly: true`). -Comportamento della panoramica di stato: +Comportamento dell'istantanea di stato: -- L'ispezione dell'account Slack traccia i campi `*Source` e `*Status` - per credenziale (`botToken`, `appToken`, `signingSecret`, `userToken`). +- L'ispezione dell'account Slack tiene traccia dei campi `*Source` e `*Status` + per ogni credenziale (`botToken`, `appToken`, `signingSecret`, `userToken`). - Lo stato è `available`, `configured_unavailable` o `missing`. - `configured_unavailable` significa che l'account è configurato tramite SecretRef - o un'altra sorgente di segreti non inline, ma il percorso comando/runtime - corrente non è riuscito a risolvere il valore effettivo. + o un'altra sorgente segreta non inline, ma il percorso comando/runtime corrente + non è riuscito a risolvere il valore effettivo. - In modalità HTTP, è incluso `signingSecretStatus`; in Socket Mode, la coppia richiesta è `botTokenStatus` + `appTokenStatus`. -Per le azioni/letture della directory, quando configurato può essere preferito il token utente. Per le scritture, il token bot resta preferito; le scritture con token utente sono consentite solo quando `userTokenReadOnly: false` e il token bot non è disponibile. +Per azioni/letture di directory, il token utente può essere preferito quando configurato. Per le scritture, il token bot resta preferito; le scritture con token utente sono consentite solo quando `userTokenReadOnly: false` e il token bot non è disponibile. -## Azioni e gate +## Azioni e controlli Le azioni Slack sono controllate da `channels.slack.actions.*`. @@ -255,18 +344,18 @@ Gruppi di azioni disponibili negli strumenti Slack attuali: | Gruppo | Predefinito | | ---------- | ----------- | -| messages | abilitato | -| reactions | abilitato | -| pins | abilitato | -| memberInfo | abilitato | -| emojiList | abilitato | +| messages | enabled | +| reactions | enabled | +| pins | enabled | +| memberInfo | enabled | +| emojiList | enabled | -Le azioni correnti dei messaggi Slack includono `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` ed `emoji-list`. +Le azioni correnti per i messaggi Slack includono `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` ed `emoji-list`. -## Controllo degli accessi e instradamento +## Controllo accessi e instradamento - + `channels.slack.dmPolicy` controlla l'accesso ai DM (legacy: `channels.slack.dm.policy`): - `pairing` (predefinito) @@ -279,21 +368,21 @@ Le azioni correnti dei messaggi Slack includono `send`, `upload-file`, `download - `dm.enabled` (predefinito true) - `channels.slack.allowFrom` (preferito) - `dm.allowFrom` (legacy) - - `dm.groupEnabled` (i DM di gruppo sono false per impostazione predefinita) - - `dm.groupChannels` (allowlist MPIM facoltativa) + - `dm.groupEnabled` (DM di gruppo predefiniti su false) + - `dm.groupChannels` (allowlist MPIM opzionale) Precedenza multi-account: - `channels.slack.accounts.default.allowFrom` si applica solo all'account `default`. - - Gli account nominati ereditano `channels.slack.allowFrom` quando il loro `allowFrom` non è impostato. - - Gli account nominati non ereditano `channels.slack.accounts.default.allowFrom`. + - Gli account con nome ereditano `channels.slack.allowFrom` quando il proprio `allowFrom` non è impostato. + - Gli account con nome non ereditano `channels.slack.accounts.default.allowFrom`. L'abbinamento nei DM usa `openclaw pairing approve slack `. - - `channels.slack.groupPolicy` controlla la gestione dei canali: + + `channels.slack.groupPolicy` controlla la gestione del canale: - `open` - `allowlist` @@ -306,21 +395,21 @@ Le azioni correnti dei messaggi Slack includono `send`, `upload-file`, `download Risoluzione nome/ID: - le voci dell'allowlist dei canali e dell'allowlist DM vengono risolte all'avvio quando l'accesso del token lo consente - - le voci irrisolte con nome canale vengono mantenute come configurate ma ignorate per l'instradamento per impostazione predefinita - - l'autorizzazione in ingresso e l'instradamento del canale usano per impostazione predefinita prima l'ID; la corrispondenza diretta di username/slug richiede `channels.slack.dangerouslyAllowNameMatching: true` + - le voci irrisolte del nome canale vengono mantenute come configurate ma ignorate per impostazione predefinita dall'instradamento + - l'autorizzazione in ingresso e l'instradamento dei canali sono incentrati sugli ID per impostazione predefinita; la corrispondenza diretta di username/slug richiede `channels.slack.dangerouslyAllowNameMatching: true` - I messaggi del canale sono soggetti a gate per menzione per impostazione predefinita. + I messaggi del canale sono vincolati alle menzioni per impostazione predefinita. - Sorgenti di menzione: + Fonti di menzione: - menzione esplicita dell'app (`<@botId>`) - pattern regex di menzione (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`) - - comportamento implicito del thread di risposta al bot + - comportamento implicito di risposta nel thread al bot - Controlli per canale (`channels.slack.channels.`; i nomi solo tramite risoluzione all'avvio o `dangerouslyAllowNameMatching`): + Controlli per canale (`channels.slack.channels.`; nomi solo tramite risoluzione all'avvio o `dangerouslyAllowNameMatching`): - `requireMention` - `users` (allowlist) @@ -328,26 +417,26 @@ Le azioni correnti dei messaggi Slack includono `send`, `upload-file`, `download - `skills` - `systemPrompt` - `tools`, `toolsBySender` - - formato della chiave `toolsBySender`: `id:`, `e164:`, `username:`, `name:` o wildcard `"*"` + - formato della chiave `toolsBySender`: `id:`, `e164:`, `username:`, `name:` oppure wildcard `"*"` (le chiavi legacy senza prefisso continuano a essere mappate solo a `id:`) -## Thread, sessioni e tag di risposta +## Threading, sessioni e tag di risposta -- I DM vengono instradati come `direct`; i canali come `channel`; gli MPIM come `group`. -- Con il valore predefinito `session.dmScope=main`, i DM di Slack confluiscono nella sessione principale dell'agente. -- Sessioni dei canali: `agent::slack:channel:`. -- Le risposte nei thread possono creare suffissi di sessione thread (`:thread:`) quando applicabile. -- `channels.slack.thread.historyScope` è `thread` per impostazione predefinita; `thread.inheritParent` è `false` per impostazione predefinita. -- `channels.slack.thread.initialHistoryLimit` controlla quanti messaggi esistenti del thread vengono recuperati all'avvio di una nuova sessione thread (predefinito `20`; imposta `0` per disabilitare). +- I DM sono instradati come `direct`; i canali come `channel`; gli MPIM come `group`. +- Con `session.dmScope=main` predefinito, i DM di Slack confluiscono nella sessione principale dell'agente. +- Sessioni canale: `agent::slack:channel:`. +- Le risposte nei thread possono creare suffissi di sessione del thread (`:thread:`) quando applicabile. +- Il valore predefinito di `channels.slack.thread.historyScope` è `thread`; il valore predefinito di `thread.inheritParent` è `false`. +- `channels.slack.thread.initialHistoryLimit` controlla quanti messaggi esistenti del thread vengono recuperati quando inizia una nuova sessione thread (predefinito `20`; imposta `0` per disabilitare). -Controlli del threading delle risposte: +Controlli di threading delle risposte: - `channels.slack.replyToMode`: `off|first|all|batched` (predefinito `off`) - `channels.slack.replyToModeByChatType`: per `direct|group|channel` -- fallback legacy per le chat dirette: `channels.slack.dm.replyToMode` +- fallback legacy per chat dirette: `channels.slack.dm.replyToMode` Sono supportati tag di risposta manuali: @@ -356,9 +445,9 @@ Sono supportati tag di risposta manuali: Nota: `replyToMode="off"` disabilita **tutto** il threading delle risposte in Slack, inclusi i tag espliciti `[[reply_to_*]]`. Questo differisce da Telegram, dove i tag espliciti vengono comunque rispettati in modalità `"off"`. La differenza riflette i modelli di threading delle piattaforme: i thread di Slack nascondono i messaggi dal canale, mentre le risposte di Telegram restano visibili nel flusso principale della chat. -## Reazioni di ack +## Reazioni di conferma -`ackReaction` invia un'emoji di conferma mentre OpenClaw elabora un messaggio in ingresso. +`ackReaction` invia un'emoji di conferma mentre OpenClaw sta elaborando un messaggio in ingresso. Ordine di risoluzione: @@ -374,20 +463,20 @@ Note: ## Streaming del testo -`channels.slack.streaming` controlla il comportamento dell'anteprima live: +`channels.slack.streaming` controlla il comportamento di anteprima in tempo reale: -- `off`: disabilita lo streaming dell'anteprima live. +- `off`: disabilita lo streaming di anteprima in tempo reale. - `partial` (predefinito): sostituisce il testo di anteprima con l'ultimo output parziale. -- `block`: aggiunge aggiornamenti di anteprima in blocchi. -- `progress`: mostra il testo di stato dell'avanzamento durante la generazione, quindi invia il testo finale. +- `block`: aggiunge aggiornamenti di anteprima a blocchi. +- `progress`: mostra testo di stato dell'avanzamento durante la generazione, poi invia il testo finale. -`channels.slack.nativeStreaming` controlla lo streaming di testo nativo di Slack quando `streaming` è `partial` (predefinito: `true`). +`channels.slack.nativeStreaming` controlla lo streaming nativo del testo Slack quando `streaming` è `partial` (predefinito: `true`). -- Per visualizzare lo streaming di testo nativo deve essere disponibile un thread di risposta. La selezione del thread continua comunque a seguire `replyToMode`. Senza di esso, viene usata la normale anteprima bozza. -- I contenuti multimediali e i payload non testuali usano come fallback la consegna normale. -- Se lo streaming fallisce a metà risposta, OpenClaw usa come fallback la consegna normale per i payload rimanenti. +- Deve essere disponibile un thread di risposta perché lo streaming nativo del testo venga visualizzato. La selezione del thread continua comunque a seguire `replyToMode`. Senza thread, viene usata la normale anteprima bozza. +- I contenuti multimediali e i payload non testuali tornano alla consegna normale. +- Se lo streaming fallisce a metà risposta, OpenClaw torna alla consegna normale per i payload rimanenti. -Usa l'anteprima bozza invece dello streaming di testo nativo di Slack: +Usa l'anteprima bozza invece dello streaming nativo del testo Slack: ```json5 { @@ -402,12 +491,12 @@ Usa l'anteprima bozza invece dello streaming di testo nativo di Slack: Chiavi legacy: -- `channels.slack.streamMode` (`replace | status_final | append`) viene migrato automaticamente a `channels.slack.streaming`. -- il booleano `channels.slack.streaming` viene migrato automaticamente a `channels.slack.nativeStreaming`. +- `channels.slack.streamMode` (`replace | status_final | append`) viene migrato automaticamente in `channels.slack.streaming`. +- il booleano `channels.slack.streaming` viene migrato automaticamente in `channels.slack.nativeStreaming`. ## Fallback della reazione di digitazione -`typingReaction` aggiunge una reazione temporanea al messaggio Slack in ingresso mentre OpenClaw elabora una risposta, quindi la rimuove quando l'esecuzione termina. Questo è particolarmente utile al di fuori delle risposte nei thread, che usano un indicatore di stato predefinito "is typing...". +`typingReaction` aggiunge una reazione temporanea al messaggio Slack in ingresso mentre OpenClaw elabora una risposta, poi la rimuove al termine dell'esecuzione. È particolarmente utile al di fuori delle risposte nei thread, che usano un indicatore di stato predefinito "sta scrivendo...". Ordine di risoluzione: @@ -419,20 +508,19 @@ Note: - Slack si aspetta shortcode (ad esempio `"hourglass_flowing_sand"`). - La reazione è best-effort e la pulizia viene tentata automaticamente dopo il completamento della risposta o del percorso di errore. -## Media, suddivisione e consegna +## Media, suddivisione in blocchi e consegna - Gli allegati di file Slack vengono scaricati da URL private ospitate da Slack (flusso di richiesta autenticato tramite token) e scritti nello store multimediale quando il recupero riesce e i limiti di dimensione lo consentono. - - Il limite dimensionale di runtime per l'ingresso è per impostazione predefinita `20MB`, salvo override con `channels.slack.mediaMaxMb`. + Gli allegati file di Slack vengono scaricati da URL privati ospitati da Slack (flusso di richiesta autenticato tramite token) e scritti nel media store quando il recupero riesce e i limiti di dimensione lo consentono. + Il limite dimensionale di runtime in ingresso è predefinito su `20MB`, salvo override tramite `channels.slack.mediaMaxMb`. - i blocchi di testo usano `channels.slack.textChunkLimit` (predefinito 4000) - - `channels.slack.chunkMode="newline"` abilita la suddivisione con priorità ai paragrafi - - gli invii di file usano le API di upload di Slack e possono includere risposte nei thread (`thread_ts`) + - `channels.slack.chunkMode="newline"` abilita la suddivisione prima per paragrafo + - gli invii di file usano le API di caricamento Slack e possono includere risposte nei thread (`thread_ts`) - il limite dei media in uscita segue `channels.slack.mediaMaxMb` quando configurato; altrimenti gli invii del canale usano i valori predefiniti per tipo MIME dalla pipeline media @@ -442,24 +530,23 @@ Note: - `user:` per i DM - `channel:` per i canali - I DM di Slack vengono aperti tramite le API di conversazione di Slack quando si invia a target utente. - + I DM di Slack vengono aperti tramite le API di conversazione di Slack quando si invia verso target utente. ## Comandi e comportamento slash -- La modalità automatica dei comandi nativi è **off** per Slack (`commands.native: "auto"` non abilita i comandi nativi di Slack). -- Abilita gli handler dei comandi nativi di Slack con `channels.slack.commands.native: true` (o globale `commands.native: true`). -- Quando i comandi nativi sono abilitati, registra in Slack i comandi slash corrispondenti (nomi `/`), con un'eccezione: +- La modalità automatica dei comandi nativi è **disattivata** per Slack (`commands.native: "auto"` non abilita i comandi nativi di Slack). +- Abilita i gestori dei comandi nativi di Slack con `channels.slack.commands.native: true` (o con `commands.native: true` globale). +- Quando i comandi nativi sono abilitati, registra in Slack i corrispondenti slash command (nomi `/`), con un'eccezione: - registra `/agentstatus` per il comando status (Slack riserva `/status`) -- Se i comandi nativi non sono abilitati, puoi eseguire un singolo comando slash configurato tramite `channels.slack.slashCommand`. -- I menu nativi degli argomenti ora adattano la loro strategia di rendering: - - fino a 5 opzioni: blocchi pulsante +- Se i comandi nativi non sono abilitati, puoi eseguire un singolo slash command configurato tramite `channels.slack.slashCommand`. +- I menu argomenti nativi ora adattano la loro strategia di rendering: + - fino a 5 opzioni: blocchi con pulsanti - 6-100 opzioni: menu di selezione statico - - più di 100 opzioni: selezione esterna con filtraggio asincrono delle opzioni quando sono disponibili gli handler delle opzioni di interattività - - se i valori delle opzioni codificati superano i limiti di Slack, il flusso usa come fallback i pulsanti -- Per payload di opzioni lunghi, i menu degli argomenti dei comandi slash usano una finestra di conferma prima di inviare un valore selezionato. + - più di 100 opzioni: selezione esterna con filtro asincrono delle opzioni quando sono disponibili i gestori delle opzioni di interattività + - se i valori delle opzioni codificati superano i limiti di Slack, il flusso torna ai pulsanti +- Per payload di opzioni lunghi, i menu degli argomenti dei comandi slash usano una finestra di conferma prima di inviare il valore selezionato. Impostazioni predefinite del comando slash: @@ -472,11 +559,11 @@ Le sessioni slash usano chiavi isolate: - `agent::slack:slash:` -e continuano comunque a instradare l'esecuzione del comando rispetto alla sessione della conversazione di destinazione (`CommandTargetSessionKey`). +e continuano comunque a instradare l'esecuzione del comando verso la sessione della conversazione di destinazione (`CommandTargetSessionKey`). ## Risposte interattive -Slack può renderizzare controlli di risposta interattivi creati dall'agente, ma questa funzionalità è disabilitata per impostazione predefinita. +Slack può visualizzare controlli di risposta interattivi creati dall'agente, ma questa funzionalità è disabilitata per impostazione predefinita. Abilitala globalmente: @@ -519,27 +606,27 @@ Queste direttive vengono compilate in Slack Block Kit e instradano clic o selezi Note: -- Si tratta di UI specifica di Slack. Gli altri canali non traducono le direttive Slack Block Kit nei propri sistemi di pulsanti. -- I valori dei callback interattivi sono token opachi generati da OpenClaw, non valori grezzi creati dall'agente. -- Se i blocchi interattivi generati superano i limiti di Slack Block Kit, OpenClaw usa come fallback la risposta di testo originale invece di inviare un payload blocks non valido. +- Questa è un'interfaccia specifica di Slack. Gli altri canali non traducono le direttive Slack Block Kit nei propri sistemi di pulsanti. +- I valori di callback interattivi sono token opachi generati da OpenClaw, non valori grezzi creati dall'agente. +- Se i blocchi interattivi generati superano i limiti di Slack Block Kit, OpenClaw torna alla risposta testuale originale invece di inviare un payload blocks non valido. ## Approvazioni exec in Slack -Slack può fungere da client di approvazione nativo con pulsanti interattivi e interazioni, invece di usare come fallback la Web UI o il terminale. +Slack può agire come client di approvazione nativo con pulsanti e interazioni interattive, invece di usare come fallback la Web UI o il terminale. -- Le approvazioni exec usano `channels.slack.execApprovals.*` per l'instradamento nativo di DM/canale. -- Le approvazioni dei plugin possono comunque risolversi attraverso la stessa superficie nativa di pulsanti Slack quando la richiesta arriva già in Slack e il tipo di id approvazione è `plugin:`. -- L'autorizzazione dell'approvatore continua a essere applicata: solo gli utenti identificati come approvatori possono approvare o negare richieste tramite Slack. +- Le approvazioni exec usano `channels.slack.execApprovals.*` per l'instradamento nativo di DM/canali. +- Le approvazioni dei plugin possono comunque risolversi attraverso la stessa interfaccia nativa a pulsanti di Slack quando la richiesta arriva già in Slack e il tipo di id approvazione è `plugin:`. +- L'autorizzazione degli approvatori continua a essere applicata: solo gli utenti identificati come approvatori possono approvare o negare richieste tramite Slack. -Questo usa la stessa superficie condivisa dei pulsanti di approvazione degli altri canali. Quando `interactivity` è abilitato nelle impostazioni della tua app Slack, i prompt di approvazione vengono renderizzati come pulsanti Block Kit direttamente nella conversazione. -Quando questi pulsanti sono presenti, rappresentano l'UX di approvazione primaria; OpenClaw +Questo usa la stessa interfaccia condivisa a pulsanti di approvazione degli altri canali. Quando `interactivity` è abilitato nelle impostazioni della tua app Slack, i prompt di approvazione vengono visualizzati come pulsanti Block Kit direttamente nella conversazione. +Quando questi pulsanti sono presenti, rappresentano l'esperienza utente primaria per l'approvazione; OpenClaw dovrebbe includere un comando manuale `/approve` solo quando il risultato dello strumento indica che le approvazioni in chat non sono disponibili o che l'approvazione manuale è l'unico percorso. Percorso di configurazione: - `channels.slack.execApprovals.enabled` -- `channels.slack.execApprovals.approvers` (facoltativo; usa come fallback `commands.ownerAllowFrom` quando possibile) +- `channels.slack.execApprovals.approvers` (opzionale; usa come fallback `commands.ownerAllowFrom` quando possibile) - `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, predefinito: `dm`) - `agentFilter`, `sessionFilter` @@ -547,7 +634,7 @@ Slack abilita automaticamente le approvazioni exec native quando `enabled` non approvatore. Imposta `enabled: false` per disabilitare esplicitamente Slack come client di approvazione nativo. Imposta `enabled: true` per forzare l'attivazione delle approvazioni native quando gli approvatori vengono risolti. -Comportamento predefinito senza una configurazione esplicita delle approvazioni exec Slack: +Comportamento predefinito senza configurazione esplicita delle approvazioni exec Slack: ```json5 { @@ -557,8 +644,8 @@ Comportamento predefinito senza una configurazione esplicita delle approvazioni } ``` -La configurazione nativa esplicita di Slack è necessaria solo quando vuoi sovrascrivere gli approvatori, aggiungere filtri o -attivare la consegna nella chat di origine: +La configurazione esplicita nativa Slack è necessaria solo quando vuoi sovrascrivere gli approvatori, aggiungere filtri o +scegliere la consegna nella chat di origine: ```json5 { @@ -574,36 +661,36 @@ attivare la consegna nella chat di origine: } ``` -L'inoltro condiviso `approvals.exec` è separato. Usalo solo quando i prompt di approvazione exec devono anche -essere instradati verso altre chat o target espliciti fuori banda. Anche l'inoltro condiviso `approvals.plugin` è +L'inoltro condiviso `approvals.exec` è separato. Usalo solo quando i prompt di approvazione exec devono essere instradati anche +ad altre chat o a target espliciti fuori banda. Anche l'inoltro condiviso `approvals.plugin` è separato; i pulsanti nativi di Slack possono comunque risolvere le approvazioni dei plugin quando tali richieste arrivano già in Slack. -Anche `/approve` nella stessa chat funziona nei canali e DM Slack che già supportano i comandi. Vedi [Approvazioni exec](/it/tools/exec-approvals) per il modello completo di inoltro delle approvazioni. +Anche `/approve` nella stessa chat funziona nei canali e nei DM di Slack che supportano già i comandi. Vedi [Approvazioni exec](/it/tools/exec-approvals) per il modello completo di inoltro delle approvazioni. ## Eventi e comportamento operativo -- Le modifiche/eliminazioni dei messaggi e le trasmissioni del thread vengono mappate in eventi di sistema. -- Gli eventi di aggiunta/rimozione di reazioni vengono mappati in eventi di sistema. -- Gli eventi di ingresso/uscita membro, canale creato/rinominato e aggiunta/rimozione pin vengono mappati in eventi di sistema. +- Le modifiche/eliminazioni dei messaggi e le trasmissioni dei thread vengono mappate in eventi di sistema. +- Gli eventi di aggiunta/rimozione di reazione vengono mappati in eventi di sistema. +- Gli eventi di ingresso/uscita dei membri, creazione/rinomina del canale e aggiunta/rimozione dei pin vengono mappati in eventi di sistema. - `channel_id_changed` può migrare le chiavi di configurazione del canale quando `configWrites` è abilitato. -- I metadati topic/purpose del canale sono trattati come contesto non attendibile e possono essere iniettati nel contesto di instradamento. -- Il messaggio iniziale del thread e il seeding iniziale del contesto della cronologia del thread vengono filtrati dalle allowlist mittente configurate quando applicabile. -- Le azioni block e le interazioni modal emettono eventi di sistema strutturati `Slack interaction: ...` con campi payload dettagliati: - - azioni block: valori selezionati, etichette, valori picker e metadati `workflow_*` - - eventi modal `view_submission` e `view_closed` con metadati del canale instradato e input del modulo +- I metadati di topic/purpose del canale sono trattati come contesto non attendibile e possono essere inseriti nel contesto di instradamento. +- Il messaggio iniziale del thread e il seeding iniziale del contesto della cronologia del thread vengono filtrati dalle allowlist configurate dei mittenti quando applicabile. +- Le azioni sui blocchi e le interazioni modali emettono eventi di sistema strutturati `Slack interaction: ...` con campi payload completi: + - azioni sui blocchi: valori selezionati, etichette, valori picker e metadati `workflow_*` + - eventi modali `view_submission` e `view_closed` con metadati del canale instradati e input del modulo -## Puntatori al riferimento di configurazione +## Riferimenti alla configurazione Riferimento principale: - [Riferimento di configurazione - Slack](/it/gateway/configuration-reference#slack) - Campi Slack ad alto segnale: + Campi Slack ad alto valore informativo: - modalità/autenticazione: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` - accesso DM: `dm.enabled`, `dmPolicy`, `allowFrom` (legacy: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels` - - interruttore di compatibilità: `dangerouslyAllowNameMatching` (break-glass; tienilo disattivato salvo necessità) - - accesso canale: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` + - interruttore di compatibilità: `dangerouslyAllowNameMatching` (di emergenza; lascialo disattivato salvo necessità) + - accesso ai canali: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` - threading/cronologia: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` - consegna: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `nativeStreaming` - operazioni/funzionalità: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly` @@ -615,7 +702,7 @@ Riferimento principale: Controlla, in ordine: - `groupPolicy` - - allowlist canali (`channels.slack.channels`) + - allowlist dei canali (`channels.slack.channels`) - `requireMention` - allowlist `users` per canale @@ -642,8 +729,8 @@ openclaw pairing list slack - - Convalida bot + app token e l'abilitazione di Socket Mode nelle impostazioni dell'app Slack. + + Convalida i token bot + app e l'abilitazione di Socket Mode nelle impostazioni dell'app Slack. Se `openclaw channels status --probe --json` mostra `botTokenStatus` o `appTokenStatus: "configured_unavailable"`, l'account Slack è @@ -657,22 +744,22 @@ openclaw pairing list slack - signing secret - percorso webhook - - URL di richiesta Slack (Events + Interactivity + Slash Commands) + - URL di richiesta Slack (Eventi + Interattività + Slash Commands) - `webhookPath` univoco per account HTTP - Se `signingSecretStatus: "configured_unavailable"` appare nelle - panoramiche dell'account, l'account HTTP è configurato ma il runtime corrente non è riuscito - a risolvere il signing secret supportato da SecretRef. + Se `signingSecretStatus: "configured_unavailable"` appare nelle istantanee + dell'account, l'account HTTP è configurato ma il runtime corrente non è riuscito a + risolvere il signing secret supportato da SecretRef. - Verifica se intendevi usare: + Verifica se intendevi: - - modalità comandi nativi (`channels.slack.commands.native: true`) con comandi slash corrispondenti registrati in Slack - - oppure modalità comando slash singolo (`channels.slack.slashCommand.enabled: true`) + - modalità comando nativa (`channels.slack.commands.native: true`) con i corrispondenti slash command registrati in Slack + - oppure modalità singolo slash command (`channels.slack.slashCommand.enabled: true`) - Controlla anche `commands.useAccessGroups` e le allowlist di canale/utente. + Controlla anche `commands.useAccessGroups` e le allowlist di canali/utenti. @@ -682,7 +769,7 @@ openclaw pairing list slack - [Abbinamento](/it/channels/pairing) - [Gruppi](/it/channels/groups) - [Sicurezza](/it/gateway/security) -- [Instradamento del canale](/it/channels/channel-routing) +- [Instradamento dei canali](/it/channels/channel-routing) - [Risoluzione dei problemi](/it/channels/troubleshooting) - [Configurazione](/it/gateway/configuration) - [Comandi slash](/it/tools/slash-commands) diff --git a/docs/it/concepts/dreaming.md b/docs/it/concepts/dreaming.md index 913ea5776..f6a8e8e4a 100644 --- a/docs/it/concepts/dreaming.md +++ b/docs/it/concepts/dreaming.md @@ -1,116 +1,116 @@ --- read_when: - Vuoi che la promozione della memoria venga eseguita automaticamente - - Vuoi capire cosa fa ogni fase del dreaming - - Vuoi ottimizzare il consolidamento senza inquinare `MEMORY.md` -summary: Consolidamento della memoria in background con fasi light, deep e REM più un Dream Diary -title: Dreaming (sperimentale) + - Vuoi capire cosa fa ogni fase del sogno + - Vuoi regolare il consolidamento senza inquinare `MEMORY.md` +summary: Consolidamento della memoria in background con fasi leggere, profonde e REM, più un Diario dei sogni +title: Sognare (sperimentale) x-i18n: - generated_at: "2026-04-06T03:06:15Z" + generated_at: "2026-04-06T08:15:04Z" model: gpt-5.4 provider: openai - source_hash: f27da718176bebf59fe8a80fddd4fb5b6d814ac5647f6c1e8344bcfb328db9de + source_hash: 36c4b1e70801d662090dc8ce20608c2f141c23cd7ce53c54e3dcf332c801fd4e source_path: concepts/dreaming.md workflow: 15 --- -# Dreaming (sperimentale) +# Sognare (sperimentale) -Dreaming è il sistema di consolidamento della memoria in background in `memory-core`. -Aiuta OpenClaw a spostare segnali forti a breve termine nella memoria durevole, mantenendo +Il sogno è il sistema di consolidamento della memoria in background in `memory-core`. +Aiuta OpenClaw a spostare segnali forti a breve termine nella memoria duratura, mantenendo il processo spiegabile e verificabile. -Dreaming è **opt-in** ed è disabilitato per impostazione predefinita. +Il sogno è **facoltativo** ed è disabilitato per impostazione predefinita. -## Cosa scrive dreaming +## Cosa scrive il sogno -Dreaming mantiene due tipi di output: +Il sogno mantiene due tipi di output: -- **Stato macchina** in `memory/.dreams/` (recall store, segnali di fase, checkpoint di ingestione, lock). -- **Output leggibile dall'uomo** in `DREAMS.md` (o nell'esistente `dreams.md`) e file di report di fase facoltativi in `memory/dreaming//YYYY-MM-DD.md`. +- **Stato macchina** in `memory/.dreams/` (archivio di richiamo, segnali di fase, checkpoint di ingestione, lock). +- **Output leggibile dagli esseri umani** in `DREAMS.md` (o `dreams.md` esistente) e file di report di fase facoltativi in `memory/dreaming//YYYY-MM-DD.md`. La promozione a lungo termine continua a scrivere solo in `MEMORY.md`. -## Modello a fasi +## Modello di fase -Dreaming usa tre fasi cooperative: +Il sogno usa tre fasi cooperative: -| Fase | Scopo | Scrittura persistente | -| ----- | ----------------------------------------- | --------------------- | -| Light | Ordina e prepara il materiale recente a breve termine | No | -| Deep | Valuta e promuove i candidati durevoli | Sì (`MEMORY.md`) | -| REM | Riflette su temi e idee ricorrenti | No | +| Fase | Scopo | Scrittura duratura | +| ----- | ----------------------------------------- | ------------------ | +| Leggera | Ordinare e preparare il materiale recente a breve termine | No | +| Profonda | Valutare e promuovere i candidati duraturi | Sì (`MEMORY.md`) | +| REM | Riflettere su temi e idee ricorrenti | No | Queste fasi sono dettagli interni di implementazione, non "modalità" -separate configurate dall'utente. +separate configurabili dall'utente. -### Fase light +### Fase leggera -La fase light acquisisce segnali recenti di memoria giornaliera e tracce di recall, li deduplica -e prepara le righe candidate. +La fase leggera acquisisce segnali recenti della memoria giornaliera e tracce di richiamo, li deduplica +e prepara righe candidate. -- Legge dallo stato di recall a breve termine e dai file recenti della memoria giornaliera. -- Scrive un blocco gestito `## Light Sleep` quando l'archiviazione include output inline. -- Registra segnali di rinforzo per il successivo ranking deep. +- Legge dallo stato di richiamo a breve termine e dai file recenti della memoria giornaliera. +- Scrive un blocco gestito `## Sonno leggero` quando l'archiviazione include output inline. +- Registra segnali di rinforzo per la successiva classificazione profonda. - Non scrive mai in `MEMORY.md`. -### Fase deep +### Fase profonda -La fase deep decide cosa diventa memoria a lungo termine. +La fase profonda decide cosa diventa memoria a lungo termine. -- Classifica i candidati usando punteggio ponderato e soglie di accesso. +- Classifica i candidati usando punteggi ponderati e soglie di filtro. - Richiede il superamento di `minScore`, `minRecallCount` e `minUniqueQueries`. -- Reidrata gli snippet dai file giornalieri live prima della scrittura, quindi gli snippet obsoleti/eliminati vengono saltati. +- Reidrata gli snippet dai file giornalieri attivi prima di scrivere, quindi gli snippet obsoleti o eliminati vengono saltati. - Aggiunge le voci promosse a `MEMORY.md`. -- Scrive un riepilogo `## Deep Sleep` in `DREAMS.md` e facoltativamente scrive `memory/dreaming/deep/YYYY-MM-DD.md`. +- Scrive un riepilogo `## Sonno profondo` in `DREAMS.md` e facoltativamente scrive `memory/dreaming/deep/YYYY-MM-DD.md`. ### Fase REM -La fase REM estrae pattern e segnali riflessivi. +La fase REM estrae schemi e segnali riflessivi. -- Costruisce riepiloghi di temi e riflessioni a partire da tracce recenti a breve termine. -- Scrive un blocco gestito `## REM Sleep` quando l'archiviazione include output inline. -- Registra segnali di rinforzo REM usati dal ranking deep. +- Costruisce riepiloghi di temi e riflessioni dalle recenti tracce a breve termine. +- Scrive un blocco gestito `## Sonno REM` quando l'archiviazione include output inline. +- Registra segnali di rinforzo REM usati dalla classificazione profonda. - Non scrive mai in `MEMORY.md`. -## Dream Diary +## Diario dei sogni -Dreaming mantiene anche un **Dream Diary** narrativo in `DREAMS.md`. +Il sogno mantiene anche un **Diario dei sogni** narrativo in `DREAMS.md`. Dopo che ogni fase ha accumulato materiale sufficiente, `memory-core` esegue un turno -di subagent in background best-effort (usando il modello runtime predefinito) e aggiunge una breve voce del diario. +in background best-effort del sottoagente (usando il modello runtime predefinito) e aggiunge una breve voce di diario. -Questo diario è destinato alla lettura umana nell'interfaccia Dreams, non è una fonte di promozione. +Questo diario è pensato per la lettura umana nell'interfaccia Dreams, non è una fonte di promozione. -## Segnali di ranking deep +## Segnali di classificazione profonda -Il ranking deep usa sei segnali base ponderati più il rinforzo di fase: +La classificazione profonda usa sei segnali di base ponderati più il rinforzo di fase: -| Segnale | Peso | Descrizione | -| ------------------- | ---- | ------------------------------------------------- | -| Frequenza | 0.24 | Quanti segnali a breve termine ha accumulato la voce | -| Rilevanza | 0.30 | Qualità media di recupero per la voce | -| Diversità delle query | 0.15 | Contesti distinti query/giorno che l'hanno fatta emergere | -| Recenza | 0.15 | Punteggio di freschezza con decadimento temporale | -| Consolidamento | 0.10 | Forza di ricorrenza su più giorni | -| Ricchezza concettuale | 0.06 | Densità di tag concettuali da snippet/percorso | +| Segnale | Peso | Descrizione | +| ------------------- | ------ | ------------------------------------------------- | +| Frequenza | 0.24 | Quanti segnali a breve termine ha accumulato la voce | +| Rilevanza | 0.30 | Qualità media di recupero per la voce | +| Diversità delle query | 0.15 | Contesti distinti di query/giorno in cui è emersa | +| Recenza | 0.15 | Punteggio di freschezza con decadimento temporale | +| Consolidamento | 0.10 | Forza di ricorrenza su più giorni | +| Ricchezza concettuale | 0.06 | Densità dei tag concettuali da snippet/percorso | -I riscontri delle fasi light e REM aggiungono un piccolo incremento con decadimento della recenza da +I riscontri delle fasi leggera e REM aggiungono un piccolo incremento con decadimento di recenza da `memory/.dreams/phase-signals.json`. ## Pianificazione -Quando è abilitato, `memory-core` gestisce automaticamente un job cron per una -scansione completa del dreaming. Ogni scansione esegue le fasi in ordine: light -> REM -> deep. +Quando è abilitato, `memory-core` gestisce automaticamente un job cron per un ciclo +completo di sogno. Ogni ciclo esegue le fasi in ordine: leggera -> REM -> profonda. -Comportamento predefinito della cadenza: +Comportamento predefinito della frequenza: -| Impostazione | Predefinito | +| Impostazione | Predefinito | | -------------------- | ----------- | | `dreaming.frequency` | `0 3 * * *` | ## Avvio rapido -Abilitare dreaming: +Abilita il sogno: ```json { @@ -128,7 +128,7 @@ Abilitare dreaming: } ``` -Abilitare dreaming con una cadenza di scansione personalizzata: +Abilita il sogno con una frequenza di ciclo personalizzata: ```json { @@ -157,7 +157,7 @@ Abilitare dreaming con una cadenza di scansione personalizzata: /dreaming help ``` -## Workflow CLI +## Flusso di lavoro CLI Usa la promozione CLI per l'anteprima o l'applicazione manuale: @@ -168,20 +168,35 @@ openclaw memory promote --limit 5 openclaw memory status --deep ``` -`memory promote` manuale usa per impostazione predefinita le soglie della fase deep, salvo override -tramite flag CLI. +Il comando manuale `memory promote` usa per impostazione predefinita le soglie della fase profonda, salvo override +tramite flag della CLI. + +Spiega perché un candidato specifico verrebbe o non verrebbe promosso: + +```bash +openclaw memory promote-explain "router vlan" +openclaw memory promote-explain "router vlan" --json +``` + +Visualizza in anteprima riflessioni REM, verità candidate e output della promozione profonda senza +scrivere nulla: + +```bash +openclaw memory rem-harness +openclaw memory rem-harness --json +``` ## Valori predefiniti principali Tutte le impostazioni si trovano in `plugins.entries.memory-core.config.dreaming`. -| Chiave | Predefinito | +| Chiave | Predefinito | | ----------- | ----------- | | `enabled` | `false` | | `frequency` | `0 3 * * *` | -La policy delle fasi, le soglie e il comportamento di archiviazione sono dettagli interni di implementazione -(non configurazione esposta all'utente). +La policy di fase, le soglie e il comportamento di archiviazione sono dettagli interni di implementazione +(non configurazione visibile all'utente). Vedi [Riferimento della configurazione della memoria](/it/reference/memory-config#dreaming-experimental) per l'elenco completo delle chiavi. @@ -190,15 +205,15 @@ per l'elenco completo delle chiavi. Quando è abilitata, la scheda **Dreams** del Gateway mostra: -- stato corrente di abilitazione di dreaming -- stato a livello di fase e presenza della scansione gestita +- stato attuale di abilitazione del sogno +- stato a livello di fase e presenza del ciclo gestito - conteggi di breve termine, lungo termine e promossi oggi - orario della prossima esecuzione pianificata -- un lettore Dream Diary espandibile basato su `doctor.memory.dreamDiary` +- un lettore espandibile del Diario dei sogni basato su `doctor.memory.dreamDiary` ## Correlati -- [Memory](/it/concepts/memory) -- [Memory Search](/it/concepts/memory-search) -- [memory CLI](/cli/memory) +- [Memoria](/it/concepts/memory) +- [Ricerca nella memoria](/it/concepts/memory-search) +- [CLI memory](/cli/memory) - [Riferimento della configurazione della memoria](/it/reference/memory-config) diff --git a/docs/it/gateway/configuration-reference.md b/docs/it/gateway/configuration-reference.md index fe055c583..c39c09107 100644 --- a/docs/it/gateway/configuration-reference.md +++ b/docs/it/gateway/configuration-reference.md @@ -1,23 +1,23 @@ --- read_when: - - Ti servono la semantica esatta o i valori predefiniti a livello di campo della configurazione + - Ti servono la semantica esatta o i valori predefiniti dei campi a livello di singolo campo - Stai convalidando blocchi di configurazione di canali, modelli, gateway o strumenti -summary: Riferimento completo per ogni chiave di configurazione OpenClaw, i valori predefiniti e le impostazioni dei canali -title: Riferimento della configurazione +summary: Riferimento completo per ogni chiave di configurazione di OpenClaw, valori predefiniti e impostazioni dei canali +title: Riferimento configurazione x-i18n: - generated_at: "2026-04-06T03:12:23Z" + generated_at: "2026-04-06T08:21:31Z" model: gpt-5.4 provider: openai - source_hash: 6aa6b24b593f6f07118817afabea4cc7842aca6b7c5602b45f479b40c1685230 + source_hash: 6ae6c19666f65433361e1c8b100ae710448c8aa055a60c140241a8aea09b98a5 source_path: gateway/configuration-reference.md workflow: 15 --- -# Riferimento della configurazione +# Riferimento configurazione Ogni campo disponibile in `~/.openclaw/openclaw.json`. Per una panoramica orientata alle attività, vedi [Configurazione](/it/gateway/configuration). -Il formato di configurazione è **JSON5** (commenti + virgole finali consentiti). Tutti i campi sono facoltativi — OpenClaw usa valori predefiniti sicuri quando vengono omessi. +Il formato della configurazione è **JSON5** (commenti + virgole finali consentiti). Tutti i campi sono facoltativi — OpenClaw usa valori predefiniti sicuri quando vengono omessi. --- @@ -27,30 +27,30 @@ Ogni canale si avvia automaticamente quando esiste la sua sezione di configurazi ### Accesso DM e gruppi -Tutti i canali supportano criteri DM e criteri di gruppo: +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 pairing monouso; il proprietario deve approvare | -| `allowlist` | Solo i mittenti in `allowFrom` (o nell'archivio di autorizzazione accoppiato) | -| `open` | Consenti tutti i DM in ingresso (richiede `allowFrom: ["*"]`) | -| `disabled` | Ignora tutti i DM in ingresso | +| Criterio DM | Comportamento | +| ------------------- | --------------------------------------------------------------- | +| `pairing` (predefinito) | I mittenti sconosciuti ricevono un codice di associazione monouso; il proprietario deve approvare | +| `allowlist` | Solo i mittenti in `allowFrom` (o nell'archivio consentiti associati) | +| `open` | Consenti tutti i DM in ingresso (richiede `allowFrom: ["*"]`) | +| `disabled` | Ignora tutti i DM in ingresso | -| Criterio di gruppo | Comportamento | -| --------------------- | ----------------------------------------------------- | -| `allowlist` (default) | Solo i gruppi che corrispondono all'allowlist configurata | -| `open` | Ignora le allowlist dei gruppi (il gating per menzione si applica comunque) | -| `disabled` | Blocca tutti i messaggi di gruppo/stanza | +| Criterio gruppo | Comportamento | +| --------------------- | ------------------------------------------------------ | +| `allowlist` (predefinito) | Solo i gruppi che corrispondono alla allowlist configurata | +| `open` | Bypassa le allowlist dei gruppi (il gating per menzione continua ad applicarsi) | +| `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 DM di pairing in sospeso sono limitate a **3 per canale**. +I codici di associazione scadono dopo 1 ora. Le richieste DM di associazione in sospeso sono limitate a **3 per canale**. Se un blocco provider manca del tutto (`channels.` assente), il criterio di gruppo a runtime torna a `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 (ad esempio impostato tramite `/model`). +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`). ```json5 { @@ -73,7 +73,7 @@ Usa `channels.modelByChannel` per fissare ID canale specifici a un modello. I va ### Valori predefiniti dei canali e heartbeat -Usa `channels.defaults` per condividere il comportamento di criterio di gruppo e heartbeat tra i provider: +Usa `channels.defaults` per il comportamento condiviso di group-policy e heartbeat tra i provider: ```json5 { @@ -92,14 +92,14 @@ Usa `channels.defaults` per condividere il comportamento di criterio di gruppo 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` (predefinito, include tutto il contesto citato/thread/storico), `allowlist` (include solo il contesto da mittenti nell'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 sani dei canali nell'output dell'heartbeat. -- `channels.defaults.heartbeat.showAlerts`: include gli stati degradati/di errore nell'output dell'heartbeat. -- `channels.defaults.heartbeat.useIndicator`: renderizza un output heartbeat compatto in stile indicatore. +- `channels.defaults.contextVisibility`: modalità predefinita di visibilità del contesto supplementare per tutti i canali. Valori: `all` (predefinito, 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 sani dei canali nell'output heartbeat. +- `channels.defaults.heartbeat.showAlerts`: include gli stati degradati/di errore nell'output heartbeat. +- `channels.defaults.heartbeat.useIndicator`: rende 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 { @@ -110,7 +110,7 @@ WhatsApp viene eseguito tramite il canale web del gateway (Baileys Web). Si avvi textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // blue ticks (false in self-chat mode) + sendReadReceipts: true, // spunte blu (false in modalità self-chat) groups: { "*": { requireMention: true }, }, @@ -151,8 +151,8 @@ WhatsApp viene eseguito tramite il canale web del gateway (Baileys Web). Si avvi ``` - I comandi in uscita usano per impostazione predefinita l'account `default` se presente; altrimenti il primo ID account configurato (ordinato). -- `channels.whatsapp.defaultAccount` facoltativo sostituisce quella selezione predefinita di fallback quando corrisponde a un ID account configurato. -- La directory di autenticazione Baileys legacy a account singolo viene migrata da `openclaw doctor` in `whatsapp/default`. +- `channels.whatsapp.defaultAccount` facoltativo sovrascrive quella selezione dell'account predefinito di fallback quando corrisponde a un ID account configurato. +- La directory auth Baileys legacy single-account viene migrata da `openclaw doctor` in `whatsapp/default`. - Override per account: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -171,19 +171,19 @@ WhatsApp viene eseguito tramite il canale web del gateway (Baileys Web). Si avvi "*": { requireMention: true }, "-1001234567890": { allowFrom: ["@admin"], - systemPrompt: "Keep answers brief.", + systemPrompt: "Mantieni le risposte brevi.", topics: { "99": { requireMention: false, skills: ["search"], - systemPrompt: "Stay on topic.", + systemPrompt: "Rimani in tema.", }, }, }, }, customCommands: [ - { command: "backup", description: "Git backup" }, - { command: "generate", description: "Create an image" }, + { command: "backup", description: "Backup Git" }, + { command: "generate", description: "Crea un'immagine" }, ], historyLimit: 50, replyToMode: "first", // off | first | all | batched @@ -211,12 +211,12 @@ WhatsApp viene eseguito tramite il canale web del gateway (Baileys Web). Si avvi } ``` -- Token del bot: `channels.telegram.botToken` o `channels.telegram.tokenFile` (solo file regolari; i symlink sono 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 predefinito esplicito (`channels.telegram.defaultAccount` o `channels.telegram.accounts.default`) per evitare il routing di fallback; `openclaw doctor` avvisa quando manca o non è valido. +- Token bot: `channels.telegram.botToken` o `channels.telegram.tokenFile` (solo file regolare; i symlink vengono rifiutati), con `TELEGRAM_BOT_TOKEN` come fallback per l'account predefinito. +- `channels.telegram.defaultAccount` facoltativo sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- Nelle configurazioni multi-account (2+ ID account), imposta un valore predefinito esplicito (`channels.telegram.defaultAccount` 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 ID supergruppo, `/config set|unset`). -- Le voci `bindings[]` di livello superiore con `type: "acp"` configurano binding ACP persistenti per argomenti del forum (usa il 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 di stream di Telegram usano `sendMessage` + `editMessageText` (funziona nelle chat dirette e di gruppo). +- Le voci `bindings[]` di primo livello con `type: "acp"` configurano binding ACP persistenti per topic 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 stream di Telegram usano `sendMessage` + `editMessageText` (funziona in chat dirette e di gruppo). - Criterio di retry: vedi [Criterio di retry](/it/concepts/retry). ### Discord @@ -264,7 +264,7 @@ WhatsApp viene eseguito tramite il canale web del gateway (Baileys Web). Si avvi requireMention: true, users: ["987654321098765432"], skills: ["docs"], - systemPrompt: "Short answers only.", + systemPrompt: "Solo risposte brevi.", }, }, }, @@ -321,34 +321,34 @@ WhatsApp viene eseguito tramite il canale web del gateway (Baileys Web). Si avvi - Token: `channels.discord.token`, con `DISCORD_BOT_TOKEN` come fallback per l'account predefinito. - Le chiamate dirette in uscita che forniscono un `token` Discord esplicito usano quel token per la chiamata; le impostazioni di retry/criterio dell'account provengono comunque dall'account selezionato nello snapshot runtime attivo. -- `channels.discord.defaultAccount` facoltativo sostituisce la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- `channels.discord.defaultAccount` facoltativo sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. - Usa `user:` (DM) o `channel:` (canale guild) per le destinazioni di consegna; gli ID numerici senza prefisso vengono rifiutati. -- Gli slug delle guild sono minuscoli con gli spazi sostituiti da `-`; le chiavi dei canali usano il nome in slug (senza `#`). Preferisci gli ID delle guild. -- I messaggi creati dai bot vengono ignorati per impostazione predefinita. `allowBots: true` li abilita; usa `allowBots: "mentions"` per accettare solo i messaggi dei bot che menzionano il bot (i propri messaggi sono comunque filtrati). -- `channels.discord.guilds..ignoreOtherMentions` (e gli override per canale) scarta i messaggi che menzionano un altro utente o ruolo ma non il bot (escludendo @everyone/@here). -- `maxLinesPerMessage` (predefinito 17) divide i messaggi alti anche quando restano sotto 2000 caratteri. +- Gli slug delle guild sono in minuscolo con gli spazi sostituiti da `-`; le chiavi dei canali usano il nome slugificato (senza `#`). Preferisci gli ID guild. +- I messaggi creati dai bot vengono ignorati per impostazione predefinita. `allowBots: true` li abilita; usa `allowBots: "mentions"` per accettare solo i messaggi dei bot che menzionano il bot (i propri messaggi restano comunque filtrati). +- `channels.discord.guilds..ignoreOtherMentions` (e gli override di canale) scarta i messaggi che menzionano un altro utente o ruolo ma non il bot (escludendo @everyone/@here). +- `maxLinesPerMessage` (predefinito 17) divide i messaggi alti anche quando restano sotto i 2000 caratteri. - `channels.discord.threadBindings` controlla il routing legato ai thread Discord: - - `enabled`: override Discord per le funzionalità di sessione legate ai thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` e consegna/routing vincolati) - - `idleHours`: override Discord per il disfocus automatico da inattività in ore (`0` lo disabilita) - - `maxAgeHours`: override Discord per l'età massima rigida in ore (`0` lo disabilita) - - `spawnSubagentSessions`: interruttore di attivazione per la creazione/binding automatici 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 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 di accento per i contenitori Discord components v2. -- `channels.discord.voice` abilita le conversazioni nei canali vocali Discord e gli eventuali override di auto-join + TTS. -- `channels.discord.voice.daveEncryption` e `channels.discord.voice.decryptionFailureTolerance` vengono passati alle opzioni DAVE di `@discordjs/voice` (`true` e `24` per impostazione predefinita). -- OpenClaw tenta inoltre 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 migrati automaticamente. -- `channels.discord.autoPresence` mappa la disponibilità a runtime alla presenza del bot (healthy => online, degraded => idle, exhausted => dnd) e consente override facoltativi del testo di stato. -- `channels.discord.dangerouslyAllowNameMatching` riabilita la corrispondenza di nome/tag mutabili (modalità compatibilità break-glass). -- `channels.discord.execApprovals`: consegna delle approvazioni exec nativa Discord e autorizzazione degli approvatori. + - `enabled`: override Discord per le funzionalità di sessione vincolate al 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 età massima rigida in ore (`0` disabilita) + - `spawnSubagentSessions`: interruttore opt-in per creazione/associazione automatica thread con `sessions_spawn({ thread: true })` +- Le voci `bindings[]` di primo livello 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 le conversazioni nei canali vocali Discord e gli override opzionali di auto-join + TTS. +- `channels.discord.voice.daveEncryption` e `channels.discord.voice.decryptionFailureTolerance` vengono inoltrati alle opzioni DAVE di `@discordjs/voice` (`true` e `24` per impostazione predefinita). +- 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à stream. La chiave legacy `streamMode` e i valori booleani `streaming` vengono migrati automaticamente. +- `channels.discord.autoPresence` mappa la disponibilità runtime alla presenza del bot (healthy => online, degraded => idle, exhausted => dnd) e consente override opzionali del testo di stato. +- `channels.discord.dangerouslyAllowNameMatching` riabilita la corrispondenza con nome/tag modificabili (modalità compatibilità break-glass). +- `channels.discord.execApprovals`: consegna nativa Discord delle approvazioni exec e autorizzazione degli approvatori. - `enabled`: `true`, `false` o `"auto"` (predefinito). In modalità auto, le approvazioni exec si attivano quando gli approvatori possono essere risolti da `approvers` o `commands.ownerAllowFrom`. - - `approvers`: ID utente Discord autorizzati ad approvare richieste exec. Se omesso, usa come fallback `commands.ownerAllowFrom`. - - `agentFilter`: allowlist facoltativa di ID agente. Omettilo per inoltrare le approvazioni per tutti gli agenti. - - `sessionFilter`: pattern facoltativi di chiavi sessione (sottostringa o regex). - - `target`: dove inviare le richieste 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. + - `approvers`: ID utente Discord autorizzati ad approvare richieste exec. Se omesso, usa `commands.ownerAllowFrom`. + - `agentFilter`: allowlist facoltativa degli ID agente. Ometti per inoltrare approvazioni per tutti gli agenti. + - `sessionFilter`: pattern facoltativi per chiave sessione (sottostringa o regex). + - `target`: dove inviare le richieste di approvazione. `"dm"` (predefinito) le invia ai DM degli approvatori, `"channel"` le invia al canale di origine, `"both"` le invia a entrambi. Quando 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, predefinito), `all` (tutti i messaggi), `allowlist` (da `guilds..users` su tutti i messaggi). +**Modalità di notifica delle reazioni:** `off` (nessuna), `own` (messaggi del bot, predefinita), `all` (tutti i messaggi), `allowlist` (da `guilds..users` su tutti i messaggi). ### Google Chat @@ -379,11 +379,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 l'account di servizio (`serviceAccountRef`). +- JSON service account: inline (`serviceAccount`) o basato su file (`serviceAccountFile`). +- È supportato anche SecretRef per il service account (`serviceAccountRef`). - Fallback env: `GOOGLE_CHAT_SERVICE_ACCOUNT` o `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. - Usa `spaces/` o `users/` per le destinazioni di consegna. -- `channels.googlechat.dangerouslyAllowNameMatching` riabilita la corrispondenza del principal email mutabile (modalità compatibilità break-glass). +- `channels.googlechat.dangerouslyAllowNameMatching` riabilita la corrispondenza con principal email modificabile (modalità compatibilità break-glass). ### Slack @@ -405,7 +405,7 @@ WhatsApp viene eseguito tramite il canale web del gateway (Baileys Web). Si avvi allowBots: false, users: ["U123"], skills: ["docs"], - systemPrompt: "Short answers only.", + systemPrompt: "Solo risposte brevi.", }, }, historyLimit: 50, @@ -448,34 +448,34 @@ WhatsApp viene eseguito tramite il canale web del gateway (Baileys Web). Si avvi } ``` -- **Modalità socket** richiede sia `botToken` sia `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` per il fallback env dell'account predefinito). -- **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-credenziale relativi a origine/stato come +- 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 dell'account Slack espongono campi di 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 + configurato tramite SecretRef ma il percorso runtime/comando 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` è la chiave canonica della modalità stream. I valori legacy `streamMode` e booleani `streaming` vengono migrati automaticamente. +- `channels.slack.defaultAccount` facoltativo sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- `channels.slack.streaming` è la chiave canonica per la modalità stream. La chiave legacy `streamMode` e i valori booleani `streaming` vengono migrati automaticamente. - Usa `user:` (DM) o `channel:` per le destinazioni di consegna. -**Modalità di notifica delle reazioni:** `off`, `own` (predefinito), `all`, `allowlist` (da `reactionAllowlist`). +**Modalità di notifica delle reazioni:** `off`, `own` (predefinita), `all`, `allowlist` (da `reactionAllowlist`). -**Isolamento della sessione thread:** `thread.historyScope` è per-thread (predefinito) o condiviso nel canale. `thread.inheritParent` copia la trascrizione del canale padre nei nuovi thread. +**Isolamento sessione thread:** `thread.historyScope` è per-thread (predefinito) o condiviso nel canale. `thread.inheritParent` copia la trascrizione del canale padre nei nuovi thread. -- `typingReaction` aggiunge una reazione temporanea al messaggio Slack in ingresso mentre è in esecuzione una risposta, quindi la rimuove al completamento. Usa uno shortcode emoji Slack come `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: consegna delle approvazioni exec nativa 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"`). +- `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 nativa Slack delle approvazioni exec e autorizzazione degli approvatori. Stesso schema di Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID utente Slack), `agentFilter`, `sessionFilter` e `target` (`"dm"`, `"channel"` o `"both"`). -| Gruppo di azioni | Predefinito | Note | -| ---------------- | ----------- | ----------------------- | -| reactions | enabled | Reagisci + elenca reazioni | -| messages | enabled | Leggi/invia/modifica/elimina | -| pins | enabled | Fissa/rimuovi/elenca | -| memberInfo | enabled | Informazioni membro | -| emojiList | enabled | Elenco emoji personalizzate | +| Gruppo azioni | Predefinito | Note | +| ------------ | ----------- | ----------------------- | +| reactions | abilitato | Reagire + elencare reazioni | +| messages | abilitato | Leggere/inviare/modificare/eliminare | +| pins | abilitato | Fissare/rimuovere/elencare | +| memberInfo | abilitato | Informazioni membro | +| emojiList | abilitato | Elenco emoji personalizzate | ### Mattermost @@ -509,23 +509,23 @@ Mattermost è distribuito come plugin: `openclaw plugins install @openclaw/matte } ``` -Modalità chat: `oncall` (risponde a @-mention, predefinito), `onmessage` (ogni messaggio), `onchar` (messaggi che iniziano con il prefisso trigger). +Modalità chat: `oncall` (risponde su @-mention, predefinita), `onmessage` (ogni messaggio), `onchar` (messaggi che iniziano con il prefisso trigger). Quando i comandi nativi Mattermost sono abilitati: -- `commands.callbackPath` deve essere un percorso (ad esempio `/api/channels/mattermost/command`), non un URL completo. -- `commands.callbackUrl` deve risolvere l'endpoint gateway OpenClaw ed essere raggiungibile dal server Mattermost. -- Le callback slash native sono autenticate con i token per comando restituiti +- `commands.callbackPath` deve essere un percorso (per esempio `/api/channels/mattermost/command`), non un URL completo. +- `commands.callbackUrl` deve risolvere all'endpoint gateway OpenClaw ed essere raggiungibile dal server Mattermost. +- Le callback slash native sono autenticate con i token per-comando restituiti da Mattermost durante la registrazione del comando slash. Se la registrazione fallisce o nessun comando viene attivato, OpenClaw rifiuta le callback con `Unauthorized: invalid command token.` -- Per host di callback privati/tailnet/interni, Mattermost potrebbe richiedere che - `ServiceSettings.AllowedUntrustedInternalConnections` includa l'host/dominio di callback. +- Per host di callback privati/tailnet/interni, Mattermost potrebbe richiedere + che `ServiceSettings.AllowedUntrustedInternalConnections` includa l'host/dominio della callback. Usa valori host/dominio, non URL completi. - `channels.mattermost.configWrites`: consente o nega le scritture di configurazione avviate da Mattermost. - `channels.mattermost.requireMention`: richiede `@mention` prima di rispondere nei canali. - `channels.mattermost.groups..requireMention`: override per canale del gating per menzione (`"*"` per il predefinito). -- `channels.mattermost.defaultAccount` facoltativo sostituisce la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- `channels.mattermost.defaultAccount` facoltativo sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. ### Signal @@ -546,15 +546,15 @@ Quando i comandi nativi Mattermost sono abilitati: } ``` -**Modalità di notifica delle reazioni:** `off`, `own` (predefinito), `all`, `allowlist` (da `reactionAllowlist`). +**Modalità di notifica delle reazioni:** `off`, `own` (predefinita), `all`, `allowlist` (da `reactionAllowlist`). - `channels.signal.account`: fissa l'avvio del canale a una specifica identità account Signal. - `channels.signal.configWrites`: consente 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.defaultAccount` facoltativo sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. ### BlueBubbles -BlueBubbles è il percorso iMessage consigliato (basato su plugin, configurato in `channels.bluebubbles`). +BlueBubbles è il percorso iMessage consigliato (basato su plugin, configurato sotto `channels.bluebubbles`). ```json5 { @@ -570,13 +570,13 @@ BlueBubbles è il percorso iMessage consigliato (basato su plugin, configurato i ``` - Percorsi chiave core coperti 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 dei campi condivisa: [Agenti ACP](/it/tools/acp-agents#channel-specific-settings). +- `channels.bluebubbles.defaultAccount` facoltativo sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- Le voci `bindings[]` di primo livello con `type: "acp"` possono associare conversazioni BlueBubbles a sessioni ACP persistenti. Usa un handle BlueBubbles o una stringa target (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) in `match.peer.id`. Semantica dei campi condivisa: [ACP Agents](/it/tools/acp-agents#channel-specific-settings). - La configurazione completa del canale BlueBubbles è documentata in [BlueBubbles](/it/channels/bluebubbles). ### iMessage -OpenClaw avvia `imsg rpc` (JSON-RPC su stdio). Non serve alcun daemon né porta. +OpenClaw avvia `imsg rpc` (JSON-RPC su stdio). Nessun demone o porta richiesto. ```json5 { @@ -600,17 +600,17 @@ OpenClaw avvia `imsg rpc` (JSON-RPC su stdio). Non serve alcun daemon né porta. } ``` -- `channels.imessage.defaultAccount` facoltativo sostituisce la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- `channels.imessage.defaultAccount` facoltativo sovrascrive la selezione dell'account predefinito quando corrisponde a un ID account configurato. -- Richiede Full Disk Access al DB Messages. +- Richiede Full Disk Access al database Messaggi. - Preferisci destinazioni `chat_id:`. Usa `imsg chats --limit 20` per elencare le chat. -- `cliPath` può puntare a un wrapper SSH; imposta `remoteHost` (`host` o `user@host`) per il recupero degli allegati via SCP. +- `cliPath` può puntare a un wrapper SSH; imposta `remoteHost` (`host` o `user@host`) per il recupero allegati via SCP. - `attachmentRoots` e `remoteAttachmentRoots` limitano i percorsi degli allegati in ingresso (predefinito: `/Users/*/Library/Messages/Attachments`). -- SCP usa un controllo rigoroso della chiave host, quindi assicurati che la chiave dell'host relay esista già in `~/.ssh/known_hosts`. +- 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 una destinazione chat esplicita (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) in `match.peer.id`. Semantica dei campi condivisa: [Agenti ACP](/it/tools/acp-agents#channel-specific-settings). +- Le voci `bindings[]` di primo livello con `type: "acp"` possono associare conversazioni iMessage a sessioni ACP persistenti. Usa un handle normalizzato o una destinazione chat esplicita (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) in `match.peer.id`. Semantica dei campi condivisa: [ACP Agents](/it/tools/acp-agents#channel-specific-settings). - + ```bash #!/usr/bin/env bash @@ -621,7 +621,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix è supportato da un'estensione ed è configurato in `channels.matrix`. +Matrix è supportato da estensione e configurato sotto `channels.matrix`. ```json5 { @@ -651,24 +651,24 @@ Matrix è supportato da un'estensione ed è configurato in `channels.matrix`. } ``` -- L'autenticazione con token usa `accessToken`; quella con password usa `userId` + `password`. -- `channels.matrix.proxy` instrada il traffico HTTP Matrix tramite un proxy HTTP(S) esplicito. Gli account nominati possono sostituirlo con `channels.matrix.accounts..proxy`. +- L'autenticazione con token usa `accessToken`; l'autenticazione con password usa `userId` + `password`. +- `channels.matrix.proxy` instrada il traffico HTTP Matrix tramite un proxy HTTP(S) esplicito. Gli account nominati possono sovrascriverlo con `channels.matrix.accounts..proxy`. - `channels.matrix.allowPrivateNetwork` consente homeserver privati/interni. `proxy` e `allowPrivateNetwork` sono controlli indipendenti. - `channels.matrix.defaultAccount` seleziona l'account preferito nelle configurazioni multi-account. -- `channels.matrix.execApprovals`: consegna delle approvazioni exec nativa Matrix e autorizzazione degli approvatori. +- `channels.matrix.execApprovals`: consegna nativa Matrix delle approvazioni exec e autorizzazione degli approvatori. - `enabled`: `true`, `false` o `"auto"` (predefinito). In modalità auto, le approvazioni exec si attivano quando gli approvatori possono essere risolti da `approvers` o `commands.ownerAllowFrom`. - - `approvers`: ID utente Matrix (ad es. `@owner:example.org`) autorizzati ad approvare richieste exec. - - `agentFilter`: allowlist facoltativa di ID agente. Omettilo per inoltrare le approvazioni per tutti gli agenti. - - `sessionFilter`: pattern facoltativi di chiavi sessione (sottostringa o regex). + - `approvers`: ID utente Matrix (es. `@owner:example.org`) autorizzati ad approvare richieste exec. + - `agentFilter`: allowlist facoltativa degli ID agente. Ometti per inoltrare approvazioni per tutti gli agenti. + - `sessionFilter`: pattern facoltativi per chiave sessione (sottostringa o regex). - `target`: dove inviare le richieste di approvazione. `"dm"` (predefinito), `"channel"` (stanza di origine) o `"both"`. - Override per account: `channels.matrix.accounts..execApprovals`. - `channels.matrix.dm.sessionScope` controlla come i DM Matrix vengono raggruppati in sessioni: `per-user` (predefinito) condivide per peer instradato, mentre `per-room` isola ogni stanza DM. -- Le sonde di stato Matrix e le ricerche live nella directory usano lo stesso criterio proxy del traffico runtime. +- 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). ### Microsoft Teams -Microsoft Teams è supportato da un'estensione ed è configurato in `channels.msteams`. +Microsoft Teams è supportato da estensione e configurato sotto `channels.msteams`. ```json5 { @@ -684,11 +684,11 @@ Microsoft Teams è supportato da un'estensione ed è configurato in `channels.ms ``` - Percorsi chiave 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). +- La configurazione completa di Teams (credenziali, webhook, criterio DM/gruppi, override per team/per canale) è documentata in [Microsoft Teams](/it/channels/msteams). ### IRC -IRC è supportato da un'estensione ed è configurato in `channels.irc`. +IRC è supportato da estensione e configurato sotto `channels.irc`. ```json5 { @@ -710,12 +710,12 @@ IRC è supportato da un'estensione ed è configurato in `channels.irc`. ``` - Percorsi chiave core coperti 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. +- `channels.irc.defaultAccount` facoltativo sovrascrive 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). ### Multi-account (tutti i canali) -Esegui più account per canale (ciascuno con il proprio `accountId`): +Esegui più account per canale (ognuno con il proprio `accountId`): ```json5 { @@ -723,11 +723,11 @@ Esegui più account per canale (ciascuno con il proprio `accountId`): telegram: { accounts: { default: { - name: "Primary bot", + name: "Bot principale", botToken: "123456:ABC...", }, alerts: { - name: "Alerts bot", + name: "Bot avvisi", botToken: "987654:XYZ...", }, }, @@ -736,27 +736,27 @@ Esegui più account per canale (ciascuno con il proprio `accountId`): } ``` -- `default` viene usato quando `accountId` è omesso (CLI + routing). +- `default` viene usato quando `accountId` viene omesso (CLI + routing). - I token env si applicano solo all'account **default**. -- Le impostazioni del canale base si applicano a tutti gli account, salvo override per account. +- Le impostazioni base del canale si applicano a tutti gli account salvo override per account. - Usa `bindings[].match.accountId` per instradare ogni account a un agente diverso. -- Se aggiungi un account non predefinito tramite `openclaw channels add` (o onboarding del canale) mentre sei ancora su una configurazione di canale top-level a account singolo, OpenClaw promuove prima i valori top-level a account singolo con ambito account nella mappa account del canale, così l'account originale continua a funzionare. La maggior parte dei canali li sposta in `channels..accounts.default`; Matrix può invece preservare una destinazione nominata/predefinita esistente corrispondente. -- I binding esistenti solo-canale (senza `accountId`) continuano a corrispondere all'account predefinito; i binding con ambito account restano facoltativi. -- Anche `openclaw doctor --fix` ripara le forme miste spostando i valori top-level a account singolo con ambito account nell'account promosso scelto per quel canale. La maggior parte dei canali usa `accounts.default`; Matrix può preservare una destinazione nominata/predefinita esistente corrispondente. +- Se aggiungi un account non predefinito tramite `openclaw channels add` (o onboarding del canale) mentre sei ancora su una configurazione di canale top-level single-account, OpenClaw promuove prima i valori top-level single-account con ambito account nella mappa account del canale così l'account originale continua a funzionare. La maggior parte dei canali li sposta in `channels..accounts.default`; Matrix può invece preservare un target nominato/predefinito esistente corrispondente. +- I binding esistenti solo canale (senza `accountId`) continuano a corrispondere all'account predefinito; i binding con ambito account restano facoltativi. +- `openclaw doctor --fix` ripara anche le forme miste spostando i valori top-level single-account con ambito account nell'account promosso scelto per quel canale. La maggior parte dei canali usa `accounts.default`; Matrix può preservare un target nominato/predefinito esistente corrispondente. ### Altri canali di estensione -Molti canali di estensione sono configurati come `channels.` e documentati nelle rispettive pagine dedicate (ad esempio Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat e Twitch). +Molti canali di estensione sono configurati come `channels.` e documentati nelle rispettive pagine dedicate al canale (per 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 -Per impostazione predefinita, i messaggi di gruppo **richiedono una menzione** (menzione nei metadati o pattern regex sicuri). Si applica alle chat di gruppo WhatsApp, Telegram, Discord, Google Chat e iMessage. +I messaggi di gruppo richiedono per impostazione predefinita una **menzione obbligatoria** (menzione metadata o pattern regex sicuri). Si applica alle chat di gruppo WhatsApp, Telegram, Discord, Google Chat e iMessage. **Tipi di menzione:** -- **Menzioni nei metadati**: @-mention native della piattaforma. Ignorate in modalità self-chat WhatsApp. -- **Pattern di testo**: pattern regex sicuri in `agents.list[].groupChat.mentionPatterns`. I pattern non validi e le ripetizioni annidate non sicure vengono ignorati. +- **Menzioni metadata**: @-mention native della piattaforma. Ignorate nella modalità self-chat di WhatsApp. +- **Pattern testuali**: pattern regex sicuri in `agents.list[].groupChat.mentionPatterns`. I pattern non validi e le ripetizioni annidate non sicure vengono ignorati. - Il gating per menzione viene applicato solo quando il rilevamento è possibile (menzioni native o almeno un pattern). ```json5 @@ -770,7 +770,7 @@ Per impostazione predefinita, i messaggi di gruppo **richiedono una menzione** ( } ``` -`messages.groupChat.historyLimit` imposta il valore predefinito 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 sovrascriverlo con `channels..historyLimit` (o per-account). Imposta `0` per disabilitarlo. #### Limiti cronologia DM @@ -789,11 +789,11 @@ Per impostazione predefinita, i messaggi di gruppo **richiedono una menzione** ( Risoluzione: override per-DM → predefinito provider → nessun limite (tutto mantenuto). -Supportati: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. +Supportato: `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 di testo): +Includi il tuo numero in `allowFrom` per abilitare la modalità self-chat (ignora le @-mention native, risponde solo ai pattern testuali): ```json5 { @@ -837,15 +837,15 @@ Includi il tuo numero in `allowFrom` per abilitare la modalità self-chat (ignor -- I comandi testuali devono essere messaggi **standalone** con `/` iniziale. +- I comandi testuali devono essere messaggi **autonomi** con `/` iniziale. - `native: "auto"` attiva i comandi nativi per Discord/Telegram, lascia Slack disattivato. -- Override per canale: `channels.discord.commands.native` (bool o `"auto"`). `false` cancella i comandi registrati in precedenza. -- `channels.telegram.customCommands` aggiunge voci extra al menu bot Telegram. +- Override per canale: `channels.discord.commands.native` (bool o `"auto"`). `false` cancella i comandi precedentemente registrati. +- `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` (letture/scritture di `openclaw.json`). Per i client gateway `chat.send`, le scritture persistenti `/config set|unset` richiedono anche `operator.admin`; il solo `/config show` in lettura resta disponibile ai normali client operatore con ambito scrittura. -- `channels..configWrites` governa le mutazioni di configurazione per canale (predefinito: true). -- Per i canali multi-account, `channels..accounts..configWrites` governa anche le scritture che puntano a quell'account (ad esempio `/allowlist --config --account ` o `/config set channels..accounts....`). -- `allowFrom` è per-provider. Quando è impostato, è l'**unica** fonte di autorizzazione (le allowlist/pairing dei canali e `useAccessGroups` vengono ignorati). +- `config: true` abilita `/config` (legge/scrive `openclaw.json`). Per i client gateway `chat.send`, le scritture persistenti `/config set|unset` richiedono anche `operator.admin`; il solo `/config show` in lettura resta disponibile per i normali client operatore con ambito scrittura. +- `channels..configWrites` controlla le mutazioni di configurazione per canale (predefinito: true). +- Per i canali multi-account, `channels..accounts..configWrites` controlla anche le scritture che puntano a quell'account (per esempio `/allowlist --config --account ` o `/config set channels..accounts....`). +- `allowFrom` è per-provider. Quando impostato, è l'**unica** fonte di autorizzazione (le allowlist/associazioni del canale e `useAccessGroups` vengono ignorati). - `useAccessGroups: false` consente ai comandi di bypassare i criteri dei gruppi di accesso quando `allowFrom` non è impostato. @@ -866,7 +866,7 @@ Predefinito: `~/.openclaw/workspace`. ### `agents.defaults.repoRoot` -Root del repository facoltativa mostrata nella riga Runtime del system prompt. Se non impostata, OpenClaw la rileva automaticamente risalendo dal workspace. +Radice repository facoltativa mostrata nella riga Runtime del system prompt. Se non impostata, OpenClaw la rileva automaticamente risalendo dalla workspace. ```json5 { @@ -876,7 +876,7 @@ Root del repository facoltativa mostrata nella riga Runtime del system prompt. S ### `agents.defaults.skills` -Allowlist predefinita facoltativa di Skills per gli agenti che non impostano +Allowlist predefinita facoltativa delle Skills per gli agenti che non impostano `agents.list[].skills`. ```json5 @@ -892,15 +892,14 @@ Allowlist predefinita facoltativa di Skills per gli agenti che non impostano } ``` -- Ometti `agents.defaults.skills` per avere Skills senza restrizioni per impostazione predefinita. +- Ometti `agents.defaults.skills` per Skills senza restrizioni per impostazione predefinita. - Ometti `agents.list[].skills` per ereditare i valori predefiniti. -- Imposta `agents.list[].skills: []` per non avere Skills. -- Una lista non vuota in `agents.list[].skills` è l'insieme finale per quell'agente; non viene - unita ai valori predefiniti. +- Imposta `agents.list[].skills: []` per nessuna Skills. +- Una lista non vuota in `agents.list[].skills` è l'insieme finale per quell'agente; non viene unita ai valori predefiniti. ### `agents.defaults.skipBootstrap` -Disabilita la creazione automatica dei file bootstrap del workspace (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`). +Disabilita la creazione automatica dei file bootstrap della workspace (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`). ```json5 { @@ -908,9 +907,21 @@ Disabilita la creazione automatica dei file bootstrap del workspace (`AGENTS.md` } ``` +### `agents.defaults.contextInjection` + +Controlla quando i file bootstrap della workspace vengono iniettati nel system prompt. Predefinito: `"always"`. + +- `"continuation-skip"`: i turni di continuazione sicura (dopo una risposta assistente completata) saltano la reiniezione del bootstrap della workspace, riducendo la dimensione del prompt. Le esecuzioni heartbeat e i retry post-compattazione ricostruiscono comunque il contesto. + +```json5 +{ + agents: { defaults: { contextInjection: "continuation-skip" } }, +} +``` + ### `agents.defaults.bootstrapMaxChars` -Numero massimo di caratteri per file bootstrap del workspace prima del troncamento. Predefinito: `20000`. +Numero massimo di caratteri per file bootstrap della workspace prima del troncamento. Predefinito: `20000`. ```json5 { @@ -920,7 +931,7 @@ Numero massimo di caratteri per file bootstrap del workspace prima del troncamen ### `agents.defaults.bootstrapTotalMaxChars` -Numero massimo totale di caratteri iniettati in tutti i file bootstrap del workspace. Predefinito: `150000`. +Numero massimo totale di caratteri iniettati in tutti i file bootstrap della workspace. Predefinito: `150000`. ```json5 { @@ -933,9 +944,9 @@ Numero massimo totale di caratteri iniettati in tutti i file bootstrap del works Controlla il testo di avviso visibile all'agente quando il contesto bootstrap viene troncato. Predefinito: `"once"`. -- `"off"`: non inietta mai testo di avviso nel system prompt. -- `"once"`: inietta l'avviso una volta per ogni firma di troncamento univoca (consigliato). -- `"always"`: inietta l'avviso a ogni esecuzione quando esiste il troncamento. +- `"off"`: non iniettare mai testo di avviso nel system prompt. +- `"once"`: inietta l'avviso una volta per ogni firma univoca di troncamento (consigliato). +- `"always"`: inietta l'avviso a ogni esecuzione quando esiste un troncamento. ```json5 { @@ -945,11 +956,11 @@ Predefinito: `"once"`. ### `agents.defaults.imageMaxDimensionPx` -Dimensione massima in pixel del lato più lungo dell'immagine nei blocchi immagine di transcript/tool prima delle chiamate al provider. +Dimensione massima in pixel del lato più lungo dell'immagine nei blocchi immagine del transcript/strumenti prima delle chiamate 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ù alti preservano più dettaglio visivo. +Valori più bassi in genere riducono l'uso dei token vision e la dimensione del payload della richiesta per esecuzioni ricche di screenshot. +Valori più alti preservano più dettagli visivi. ```json5 { @@ -959,7 +970,7 @@ Valori più alti preservano più dettaglio visivo. ### `agents.defaults.userTimezone` -Fuso orario per il contesto del system prompt (non per i timestamp dei messaggi). Usa come fallback il fuso orario dell'host. +Fuso orario per il contesto del system prompt (non per i timestamp dei messaggi). In fallback usa il fuso orario host. ```json5 { @@ -969,7 +980,7 @@ Fuso orario per il contesto del system prompt (non per i timestamp dei messaggi) ### `agents.defaults.timeFormat` -Formato orario nel system prompt. Predefinito: `auto` (preferenza del sistema operativo). +Formato orario nel system prompt. Predefinito: `auto` (preferenza OS). ```json5 { @@ -1024,65 +1035,65 @@ Formato orario nel system prompt. Predefinito: `auto` (preferenza del sistema op - `model`: accetta una stringa (`"provider/model"`) oppure un oggetto (`{ primary, fallbacks }`). - La forma stringa imposta solo il modello primario. - - La forma oggetto imposta il modello primario più i modelli di failover ordinati. + - La forma oggetto imposta il primario più i modelli di failover ordinati. - `imageModel`: accetta una stringa (`"provider/model"`) oppure un oggetto (`{ primary, fallbacks }`). - Usato dal percorso dello strumento `image` come configurazione del modello vision. - Usato anche come routing di fallback quando il modello selezionato/predefinito non può accettare input immagine. - `imageGenerationModel`: accetta una stringa (`"provider/model"`) oppure 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 la generazione nativa immagini 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 dall'autenticazione. Prova prima il provider predefinito corrente, poi i restanti provider di generazione immagini registrati in ordine di ID provider. + - Usato dalla capacità condivisa di generazione immagini e da qualunque futura superficie tool/plugin che generi immagini. + - Valori tipici: `google/gemini-3.1-flash-image-preview` per la generazione immagini nativa Gemini, `fal/fal-ai/flux/dev` per fal, oppure `openai/gpt-image-1` per OpenAI Images. + - Se selezioni direttamente un provider/modello, configura anche la relativa 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 con auth. Prova prima il provider predefinito corrente, poi i restanti provider registrati per la generazione immagini in ordine di provider-id. - `musicGenerationModel`: accetta una stringa (`"provider/model"`) oppure un oggetto (`{ primary, fallbacks }`). - - Usato dalla capacità condivisa di generazione musicale e dallo strumento integrato `music_generate`. - - Valori tipici: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` o `minimax/music-2.5+`. - - Se omesso, `music_generate` può comunque dedurre un provider predefinito supportato dall'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. + - Usato dalla capacità condivisa di generazione musica e dallo strumento integrato `music_generate`. + - Valori tipici: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview`, oppure `minimax/music-2.5+`. + - Se omesso, `music_generate` può comunque dedurre un provider predefinito con auth. Prova prima il provider predefinito corrente, poi i restanti provider registrati per la generazione musica in ordine di provider-id. + - Se selezioni direttamente un provider/modello, configura anche la relativa auth/API key del provider. - `videoGenerationModel`: accetta una stringa (`"provider/model"`) oppure un oggetto (`{ primary, fallbacks }`). - Usato dalla capacità condivisa di generazione video e dallo strumento integrato `video_generate`. - - Valori tipici: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` o `qwen/wan2.7-r2v`. - - Se omesso, `video_generate` può comunque dedurre un provider predefinito supportato dall'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 integrato Qwen per la generazione video supporta attualmente 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`. + - Valori tipici: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash`, oppure `qwen/wan2.7-r2v`. + - Se omesso, `video_generate` può comunque dedurre un provider predefinito con auth. Prova prima il provider predefinito corrente, poi i restanti provider registrati per la generazione video in ordine di provider-id. + - Se selezioni direttamente un provider/modello, configura anche la relativa auth/API key del provider. + - Il provider di generazione video Qwen integrato supporta attualmente fino a 1 video di output, 1 immagine di input, 4 video di input, durata di 10 secondi 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 usa come fallback `imageModel`, poi il modello di sessione/predefinito risolto. -- `pdfMaxBytesMb`: limite predefinito di dimensione PDF per lo strumento `pdf` quando `maxBytesMb` non viene passato al momento della chiamata. -- `pdfMaxPages`: massimo predefinito di pagine considerate dalla modalità fallback di estrazione nello strumento `pdf`. + - Se omesso, lo strumento PDF usa come fallback `imageModel`, poi il modello risolto della sessione/predefinito. +- `pdfMaxBytesMb`: limite predefinito di dimensione PDF per lo strumento `pdf` quando `maxBytesMb` non viene passato in fase di chiamata. +- `pdfMaxPages`: numero massimo di pagine predefinito considerato dalla modalità di fallback di estrazione nello strumento `pdf`. - `verboseDefault`: livello verbose predefinito per gli agenti. Valori: `"off"`, `"on"`, `"full"`. Predefinito: `"off"`. -- `elevatedDefault`: livello predefinito di output elevato per gli agenti. Valori: `"off"`, `"on"`, `"ask"`, `"full"`. Predefinito: `"on"`. -- `model.primary`: formato `provider/model` (ad es. `openai/gpt-5.4`). Se ometti il provider, OpenClaw prova prima un alias, poi una corrispondenza univoca con provider configurato per quell'esatto ID modello, e solo dopo usa come fallback il provider predefinito configurato (comportamento compatibile deprecato, quindi preferisci `provider/model` esplicito). Se quel provider non espone più il modello predefinito configurato, OpenClaw usa come fallback il primo provider/modello configurato invece di mostrare un predefinito obsoleto di un provider rimosso. -- `models`: catalogo e allowlist dei modelli configurati per `/model`. Ogni voce può includere `alias` (scorciatoia) e `params` (specifici del provider, ad esempio `temperature`, `maxTokens`, `cacheRetention`, `context1m`). -- `params`: parametri globali predefiniti del provider applicati a tutti i modelli. Impostati in `agents.defaults.params` (ad es. `{ cacheRetention: "long" }`). -- Precedenza di unione di `params` (config): `agents.defaults.params` (base globale) viene sovrascritto da `agents.defaults.models["provider/model"].params` (per-modello), 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 (ad esempio `/models set`, `/models set-image` e i comandi di aggiunta/rimozione fallback) salvano la forma canonica a oggetto e preservano le liste fallback esistenti quando possibile. -- `maxConcurrent`: massimo di esecuzioni parallele di agenti tra sessioni (ogni sessione resta comunque serializzata). Predefinito: 4. +- `elevatedDefault`: livello predefinito di output elevated per gli agenti. Valori: `"off"`, `"on"`, `"ask"`, `"full"`. Predefinito: `"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 provider configurato per quello specifico model id, e solo dopo usa come fallback il provider predefinito configurato (comportamento di compatibilità deprecato, quindi preferisci `provider/model` esplicito). Se quel provider non espone più il modello predefinito configurato, OpenClaw usa come fallback il primo provider/modello configurato invece di esporre un valore predefinito obsoleto di un provider rimosso. +- `models`: catalogo e allowlist dei modelli configurati 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. Imposta in `agents.defaults.params` (ad es. `{ cacheRetention: "long" }`). +- Precedenza di unione di `params` (config): `agents.defaults.params` (base globale) viene sovrascritto da `agents.defaults.models["provider/model"].params` (per-modello), poi `agents.list[].params` (per l'id agente corrispondente) sovrascrive per chiave. Vedi [Caching dei prompt](/it/reference/prompt-caching) per i dettagli. +- I writer di configurazione che mutano questi campi (per esempio `/models set`, `/models set-image` e comandi di aggiunta/rimozione fallback) salvano la forma oggetto canonica e preservano le liste fallback esistenti quando possibile. +- `maxConcurrent`: massimo di esecuzioni agente parallele tra sessioni (ogni sessione resta comunque serializzata). Predefinito: 4. -**Alias shorthand integrati** (si applicano solo quando il modello è in `agents.defaults.models`): +**Scorciatoie alias integrate** (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 priorità su quelli predefiniti. +I tuoi alias configurati hanno sempre la precedenza su quelli predefiniti. I modelli Z.AI GLM-4.x abilitano automaticamente la modalità thinking a meno che tu non imposti `--thinking off` o definisca tu stesso `agents.defaults.models["zai/"].params.thinking`. -I modelli Z.AI abilitano `tool_stream` per impostazione predefinita per lo streaming delle chiamate tool. Imposta `agents.defaults.models["zai/"].params.tool_stream` su `false` per disabilitarlo. -I modelli Anthropic Claude 4.6 usano `adaptive` thinking per impostazione predefinita quando non è impostato alcun livello thinking esplicito. +I modelli Z.AI abilitano `tool_stream` per impostazione predefinita 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 `adaptive` thinking per impostazione predefinita quando non è impostato un livello di thinking esplicito. - Sessioni supportate quando `sessionArg` è impostato. - Pass-through delle immagini supportato quando `imageArg` accetta percorsi file. ### `agents.defaults.heartbeat` -Esecuzioni periodiche di heartbeat. +Esecuzioni heartbeat periodiche. ```json5 { @@ -1098,7 +1109,7 @@ Esecuzioni periodiche di heartbeat. to: "+15555550123", directPolicy: "allow", // allow (default) | block target: "none", // default: none | options: last | whatsapp | telegram | discord | ... - prompt: "Read HEARTBEAT.md if it exists...", + prompt: "Leggi HEARTBEAT.md se esiste...", ackMaxChars: 300, suppressToolErrorWarnings: false, }, @@ -1107,12 +1118,12 @@ Esecuzioni periodiche di heartbeat. } ``` -- `every`: stringa durata (ms/s/m/h). Predefinito: `30m` (autenticazione con chiave API) o `1h` (autenticazione OAuth). Imposta `0m` per disabilitare. -- `suppressToolErrorWarnings`: quando true, sopprime i payload di avviso degli errori tool durante le esecuzioni heartbeat. -- `directPolicy`: criterio di consegna diretta/DM. `allow` (predefinito) consente la consegna diretta alla destinazione. `block` sopprime la consegna diretta alla destinazione ed emette `reason=dm-blocked`. -- `lightContext`: quando true, le esecuzioni heartbeat usano un contesto bootstrap leggero e mantengono solo `HEARTBEAT.md` dai file bootstrap del workspace. -- `isolatedSession`: quando true, ogni esecuzione heartbeat avviene in una sessione nuova senza cronologia della conversazione precedente. Stesso schema di isolamento del cron `sessionTarget: "isolated"`. Riduce il costo in token per heartbeat da ~100K a ~2-5K token. -- Per agente: imposta `agents.list[].heartbeat`. Quando un qualunque agente definisce `heartbeat`, **solo quegli agenti** eseguono heartbeat. +- `every`: stringa durata (ms/s/m/h). Predefinito: `30m` (auth API-key) o `1h` (auth OAuth). Imposta `0m` per disabilitare. +- `suppressToolErrorWarnings`: quando true, sopprime i payload di avviso per errori tool durante le esecuzioni heartbeat. +- `directPolicy`: criterio di consegna diretta/DM. `allow` (predefinito) consente la consegna con target diretto. `block` sopprime la consegna con target diretto 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 esecuzione heartbeat avviene in una sessione nuova senza cronologia conversazioni precedente. Stesso schema di isolamento del cron `sessionTarget: "isolated"`. Riduce il costo per-heartbeat da ~100K a ~2-5K token. +- Per-agente: imposta `agents.list[].heartbeat`. Quando qualunque agente definisce `heartbeat`, **solo quegli agenti** eseguono heartbeat. - Gli heartbeat eseguono turni completi dell'agente — intervalli più brevi consumano più token. ### `agents.defaults.compaction` @@ -1126,15 +1137,15 @@ Esecuzioni periodiche di heartbeat. timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom - postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection + identifierInstructions: "Preserva esattamente gli ID di deployment, gli ID ticket e le coppie host:port.", // used when identifierPolicy=custom + postCompactionSections: ["Avvio sessione", "Linee rosse"], // [] disables reinjection model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override notifyUser: true, // send a brief notice when compaction starts (default: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, - systemPrompt: "Session nearing compaction. Store durable memories now.", - prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.", + systemPrompt: "La sessione si avvicina alla compattazione. 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.", }, }, }, @@ -1142,18 +1153,18 @@ Esecuzioni periodiche di heartbeat. } ``` -- `mode`: `default` o `safeguard` (riepilogo a blocchi per cronologie lunghe). Vedi [Compattazione](/it/concepts/compaction). -- `timeoutSeconds`: massimo di secondi consentiti per una singola operazione di compattazione prima che OpenClaw la interrompa. Predefinito: `900`. -- `identifierPolicy`: `strict` (predefinito), `off` o `custom`. `strict` antepone una guida integrata per la conservazione di identificatori opachi durante il riepilogo della compattazione. -- `identifierInstructions`: testo facoltativo personalizzato per la conservazione degli identificatori usato quando `identifierPolicy=custom`. -- `postCompactionSections`: nomi facoltativi di sezioni H2/H3 di AGENTS.md da reiniettare dopo la compattazione. Predefinito `["Session Startup", "Red Lines"]`; imposta `[]` per disabilitare la reiniezione. Quando è non impostato o impostato esplicitamente a quella coppia predefinita, vengono accettati anche i vecchi titoli `Every Session`/`Safety` come fallback legacy. -- `model`: override facoltativo `provider/model-id` solo per il riepilogo di compattazione. Usalo quando la sessione principale deve mantenere un modello ma i riepiloghi di compattazione devono usare un altro; se non impostato, la compattazione usa il modello primario della sessione. -- `notifyUser`: quando `true`, invia una breve notifica all'utente quando la compattazione inizia (ad esempio "Compacting context..."). Disabilitato per impostazione predefinita per mantenere silenziosa la compattazione. -- `memoryFlush`: turno agentico silenzioso prima della compattazione automatica per memorizzare memorie durevoli. Saltato quando il workspace è in sola lettura. +- `mode`: `default` o `safeguard` (riassunto a blocchi per cronologie lunghe). Vedi [Compattazione](/it/concepts/compaction). +- `timeoutSeconds`: massimo numero di secondi consentiti per una singola operazione di compattazione prima che OpenClaw la interrompa. Predefinito: `900`. +- `identifierPolicy`: `strict` (predefinito), `off` o `custom`. `strict` antepone istruzioni integrate per la conservazione di identificatori opachi durante il riassunto di compattazione. +- `identifierInstructions`: testo facoltativo personalizzato di conservazione identificatori usato quando `identifierPolicy=custom`. +- `postCompactionSections`: nomi facoltativi delle sezioni H2/H3 di AGENTS.md da reiniettare dopo la compattazione. Predefinito `["Session Startup", "Red Lines"]`; imposta `[]` per disabilitare la reiniezione. Quando non impostato o impostato esplicitamente a quella coppia predefinita, sono accettati anche i vecchi heading `Every Session`/`Safety` come fallback legacy. +- `model`: override facoltativo `provider/model-id` solo per il riassunto di compattazione. Usalo quando la sessione principale deve mantenere un modello ma i riassunti di compattazione devono usarne un altro; se non impostato, la compattazione usa il modello primario della sessione. +- `notifyUser`: quando `true`, invia all'utente un breve avviso quando inizia la compattazione (per esempio, "Compacting context..."). Disabilitato per impostazione predefinita per mantenere silenziosa la compattazione. +- `memoryFlush`: turno agentico silenzioso prima della compattazione automatica per memorizzare memorie durevoli. 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. +Esegue la potatura dei **vecchi risultati tool** dal contesto in memoria prima dell'invio all'LLM. **Non** modifica la cronologia sessione su disco. ```json5 { @@ -1167,7 +1178,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: "[Old tool result content cleared]" }, + hardClear: { enabled: true, placeholder: "[Contenuto del vecchio risultato tool cancellato]" }, tools: { deny: ["browser", "canvas"] }, }, }, @@ -1178,22 +1189,22 @@ Pota i **vecchi risultati dei tool** dal contesto in memoria prima di inviarlo a - `mode: "cache-ttl"` abilita i passaggi di potatura. -- `ttl` controlla con quale frequenza la potatura può essere eseguita di nuovo (dopo l'ultimo touch della cache). -- La potatura prima accorcia in modo soft i risultati tool sovradimensionati, poi svuota completamente i risultati tool più vecchi se necessario. +- `ttl` controlla ogni quanto la potatura può essere rieseguita (dopo l'ultimo tocco della cache). +- La potatura accorcia in modo soft prima i risultati tool sovradimensionati, poi svuota in modo hard i risultati tool più vecchi se necessario. -**Soft-trim** mantiene l'inizio + la fine e inserisce `...` nel mezzo. +**Soft-trim** mantiene inizio + fine e inserisce `...` nel mezzo. **Hard-clear** sostituisce l'intero risultato tool con il placeholder. Note: -- I blocchi immagine non vengono mai accorciati/svuotati. -- I rapporti sono basati sui caratteri (approssimativi), non su conteggi esatti di token. +- I blocchi immagine non vengono mai tagliati/svuotati. +- I rapporti si basano sui caratteri (approssimativi), non su conteggi esatti di token. - Se esistono meno di `keepLastAssistants` messaggi assistant, la potatura viene saltata. -Vedi [Potatura della sessione](/it/concepts/session-pruning) per i dettagli del comportamento. +Vedi [Potatura sessione](/it/concepts/session-pruning) per i dettagli sul comportamento. ### Block streaming @@ -1211,11 +1222,11 @@ Vedi [Potatura della sessione](/it/concepts/session-pruning) per i dettagli del } ``` -- I canali non Telegram richiedono `*.blockStreaming: true` esplicito per abilitare le risposte a blocchi. -- Override canale: `channels..blockStreamingCoalesce` (e varianti per account). Signal/Slack/Discord/Google Chat usano come predefinito `minChars: 1500`. -- `humanDelay`: pausa casuale tra le risposte a blocchi. `natural` = 800–2500ms. Override per agente: `agents.list[].humanDelay`. +- I canali diversi da Telegram richiedono `*.blockStreaming: true` esplicito per abilitare le risposte a blocchi. +- Override canale: `channels..blockStreamingCoalesce` (e varianti per-account). Signal/Slack/Discord/Google Chat usano come predefinito `minChars: 1500`. +- `humanDelay`: pausa casuale tra le risposte a blocchi. `natural` = 800–2500ms. Override per-agente: `agents.list[].humanDelay`. -Vedi [Streaming](/it/concepts/streaming) per dettagli su comportamento + chunking. +Vedi [Streaming](/it/concepts/streaming) per comportamento + dettagli sul chunking. ### Indicatori di digitazione @@ -1231,7 +1242,7 @@ Vedi [Streaming](/it/concepts/streaming) per dettagli su comportamento + chunkin ``` - Predefiniti: `instant` per chat dirette/menzioni, `message` per chat di gruppo senza menzione. -- Override per sessione: `session.typingMode`, `session.typingIntervalSeconds`. +- Override per-sessione: `session.typingMode`, `session.typingIntervalSeconds`. Vedi [Indicatori di digitazione](/it/concepts/typing-indicators). @@ -1334,7 +1345,7 @@ Sandboxing facoltativo per l'agente incorporato. Vedi [Sandboxing](/it/gateway/s } ``` - + **Backend:** @@ -1342,46 +1353,46 @@ Sandboxing facoltativo per l'agente incorporato. Vedi [Sandboxing](/it/gateway/s - `ssh`: runtime remoto generico basato su SSH - `openshell`: runtime OpenShell -Quando è selezionato `backend: "openshell"`, le impostazioni specifiche del runtime si spostano in +Quando è selezionato `backend: "openshell"`, le impostazioni specifiche del runtime passano a `plugins.entries.openshell.config`. -**Configurazione backend SSH:** +**Config backend SSH:** -- `target`: destinazione SSH nel formato `user@host[:port]` +- `target`: target SSH in formato `user@host[:port]` - `command`: comando client SSH (predefinito: `ssh`) -- `workspaceRoot`: root remota assoluta usata per i workspace per scope +- `workspaceRoot`: radice remota assoluta usata per workspace per-scope - `identityFile` / `certificateFile` / `knownHostsFile`: file locali esistenti passati a OpenSSH - `identityData` / `certificateData` / `knownHostsData`: contenuti inline o SecretRef che OpenClaw materializza in file temporanei a runtime -- `strictHostKeyChecking` / `updateHostKeys`: controlli di criterio chiave host di OpenSSH +- `strictHostKeyChecking` / `updateHostKeys`: controlli del criterio chiave host OpenSSH -**Precedenza autenticazione SSH:** +**Precedenza auth SSH:** -- `identityData` ha priorità su `identityFile` -- `certificateData` ha priorità su `certificateFile` -- `knownHostsData` ha priorità su `knownHostsFile` -- I valori `*Data` supportati da SecretRef vengono risolti dallo snapshot runtime attivo dei segreti prima dell'avvio della sessione sandbox +- `identityData` ha precedenza su `identityFile` +- `certificateData` ha precedenza su `certificateFile` +- `knownHostsData` ha precedenza su `knownHostsFile` +- I valori `*Data` con SecretRef vengono risolti dallo snapshot runtime attivo dei segreti prima che inizi la sessione sandbox **Comportamento backend SSH:** -- inizializza il workspace remoto una volta dopo la creazione o ricreazione -- poi mantiene il workspace SSH remoto come canonico -- instrada `exec`, i tool file e i percorsi media via SSH -- non sincronizza automaticamente all'host le modifiche remote +- inizializza la workspace remota una volta dopo create o recreate +- poi mantiene canonica la workspace remota SSH +- instrada `exec`, strumenti file e percorsi media tramite SSH +- non sincronizza automaticamente le modifiche remote di ritorno sull'host - non supporta contenitori browser sandbox -**Accesso al workspace:** +**Accesso workspace:** -- `none`: workspace sandbox per scope sotto `~/.openclaw/sandboxes` -- `ro`: workspace sandbox in `/workspace`, workspace agente montato in sola lettura in `/agent` -- `rw`: workspace agente montato in lettura/scrittura in `/workspace` +- `none`: workspace sandbox per-scope sotto `~/.openclaw/sandboxes` +- `ro`: workspace sandbox in `/workspace`, workspace agente montata in sola lettura in `/agent` +- `rw`: workspace agente montata in lettura/scrittura in `/workspace` **Scope:** -- `session`: contenitore + workspace per sessione +- `session`: contenitore + workspace per-sessione - `agent`: un contenitore + workspace per agente (predefinito) -- `shared`: contenitore e workspace condivisi (nessun isolamento cross-session) +- `shared`: contenitore e workspace condivisi (nessun isolamento cross-sessione) -**Configurazione plugin OpenShell:** +**Config plugin OpenShell:** ```json5 { @@ -1409,30 +1420,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; il workspace locale resta canonico -- `remote`: inizializza il remoto una volta quando il sandbox viene creato, poi mantiene il workspace remoto come canonico +- `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 viene creata la sandbox, 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 di seed. -Il trasporto è SSH nel sandbox OpenShell, ma il plugin gestisce il ciclo di vita del sandbox e l'eventuale sync mirror. +In modalità `remote`, le modifiche locali sull'host fatte fuori da OpenClaw non vengono sincronizzate automaticamente nella sandbox dopo il passaggio iniziale. +Il trasporto è SSH verso la sandbox OpenShell, ma il plugin gestisce il ciclo di vita della sandbox e la sincronizzazione mirror opzionale. -**`setupCommand`** viene eseguito una volta dopo la creazione del contenitore (tramite `sh -lc`). Richiede uscita di rete, root scrivibile, utente root. +**`setupCommand`** viene eseguito una volta dopo la creazione del contenitore (tramite `sh -lc`). Richiede egress di rete, root scrivibile, utente root. -**I contenitori usano per impostazione predefinita `network: "none"`** — impostalo su `"bridge"` (o una rete bridge personalizzata) se l'agente ha bisogno di accesso in uscita. -`"host"` è bloccato. `"container:"` è bloccato per impostazione predefinita a meno che tu non imposti esplicitamente +**I contenitori usano per impostazione predefinita `network: "none"`** — imposta `"bridge"` (o una rete bridge personalizzata) se l'agente ha bisogno di accesso in uscita. +`"host"` è bloccato. `"container:"` è bloccato per impostazione predefinita salvo che tu imposti esplicitamente `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (break-glass). -**Gli allegati in ingresso** vengono preparati in `media/inbound/*` nel workspace attivo. +**Gli allegati in ingresso** vengono preparati in `media/inbound/*` nella workspace attiva. **`docker.binds`** monta directory host aggiuntive; i bind globali e per-agente vengono uniti. -**Browser sandbox** (`sandbox.browser.enabled`): Chromium + CDP in un contenitore. URL noVNC iniettato nel system prompt. Non richiede `browser.enabled` in `openclaw.json`. +**Browser sandbox** (`sandbox.browser.enabled`): Chromium + CDP in un contenitore. L'URL noVNC viene iniettato nel system prompt. Non richiede `browser.enabled` in `openclaw.json`. L'accesso osservatore noVNC usa per impostazione predefinita l'autenticazione VNC e OpenClaw emette un URL con token a breve durata (invece di esporre la password nell'URL condiviso). -- `allowHostControl: false` (predefinito) impedisce alle sessioni sandbox di puntare al browser host. -- `network` usa come predefinito `openclaw-sandbox-browser` (rete bridge dedicata). Impostalo su `bridge` solo quando vuoi esplicitamente connettività bridge globale. -- `cdpSourceRange` può facoltativamente limitare l'ingresso CDP al bordo del contenitore a un intervallo CIDR (ad esempio `172.21.0.1/32`). +- `allowHostControl: false` (predefinito) blocca le sessioni sandbox dal puntare al browser host. +- `network` usa come predefinito `openclaw-sandbox-browser` (rete bridge dedicata). Imposta `bridge` solo quando vuoi esplicitamente connettività bridge globale. +- `cdpSourceRange` limita facoltativamente l'ingresso CDP al bordo del contenitore a un intervallo CIDR (per esempio `172.21.0.1/32`). - `sandbox.browser.binds` monta directory host aggiuntive solo nel contenitore browser sandbox. Quando impostato (incluso `[]`), sostituisce `docker.binds` per il contenitore browser. -- I valori predefiniti di avvio sono definiti in `scripts/sandbox-browser-entrypoint.sh` e ottimizzati per host con contenitori: +- 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` @@ -1459,20 +1470,20 @@ L'accesso osservatore noVNC usa per impostazione predefinita l'autenticazione VN `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; imposta `0` per usare il limite di processi predefinito di Chromium. - più `--no-sandbox` e `--disable-setuid-sandbox` quando `noSandbox` è abilitato. - - I valori predefiniti sono la baseline dell'immagine del contenitore; usa un'immagine browser personalizzata con un entrypoint personalizzato per cambiare i valori predefiniti del contenitore. + - I valori predefiniti sono la baseline dell'immagine contenitore; usa un'immagine browser personalizzata con un entrypoint personalizzato per cambiare i valori predefiniti del contenitore. Il sandboxing del browser e `sandbox.docker.binds` sono attualmente solo Docker. -Compila le immagini: +Costruisci le immagini: ```bash -scripts/sandbox-setup.sh # main sandbox image -scripts/sandbox-browser-setup.sh # optional browser image +scripts/sandbox-setup.sh # immagine sandbox principale +scripts/sandbox-browser-setup.sh # immagine browser opzionale ``` -### `agents.list` (override per agente) +### `agents.list` (override per-agente) ```json5 { @@ -1481,7 +1492,7 @@ scripts/sandbox-browser-setup.sh # optional browser image { id: "main", default: true, - name: "Main Agent", + name: "Agente principale", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", model: "anthropic/claude-opus-4-6", // or { primary, fallbacks } @@ -1492,7 +1503,7 @@ scripts/sandbox-browser-setup.sh # optional browser image skills: ["docs-search"], // replaces agents.defaults.skills when set identity: { name: "Samantha", - theme: "helpful sloth", + theme: "bradipo utile", emoji: "🦥", avatar: "avatars/samantha.png", }, @@ -1520,26 +1531,26 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `id`: ID agente stabile (obbligatorio). -- `default`: quando più agenti lo impostano, vince il primo (viene registrato un avviso). Se nessuno lo imposta, il predefinito è il primo elemento della lista. -- `model`: la forma stringa sostituisce solo `primary`; la forma oggetto `{ primary, fallbacks }` sostituisce entrambi (`[]` disabilita i fallback globali). I job cron che sostituiscono solo `primary` continuano comunque a ereditare 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 di 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`: livello thinking predefinito facoltativo per-agente (`off | minimal | low | medium | high | xhigh | adaptive`). Sostituisce `agents.defaults.thinkingDefault` per questo agente quando non è impostato alcun override per messaggio o sessione. -- `reasoningDefault`: visibilità del reasoning predefinita facoltativa per-agente (`on | off | stream`). Si applica quando non è impostato alcun override di reasoning per messaggio o sessione. -- `fastModeDefault`: valore predefinito facoltativo per-agente per la fast mode (`true | false`). Si applica quando non è impostato alcun override di fast mode 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 impostazione predefinita sessioni harness ACP. -- `identity.avatar`: percorso relativo al workspace, URL `http(s)` o URI `data:`. -- `identity` ricava i valori predefiniti: `ackReaction` da `emoji`, `mentionPatterns` da `name`/`emoji`. -- `subagents.allowAgents`: allowlist di ID agente per `sessions_spawn` (`["*"]` = qualunque; predefinito: solo lo stesso agente). -- Protezione dell'ereditarietà sandbox: se la sessione richiedente è in sandbox, `sessions_spawn` rifiuta le destinazioni che verrebbero eseguite senza sandbox. -- `subagents.requireAgentId`: quando true, blocca le chiamate `sessions_spawn` che omettono `agentId` (forza una selezione esplicita del profilo; predefinito: false). +- `id`: id agente stabile (obbligatorio). +- `default`: quando ne sono impostati più di uno, vince il primo (viene registrato un avviso). Se nessuno è impostato, il predefinito è il primo elemento della lista. +- `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` ereditano comunque i fallback predefiniti salvo che tu imposti `fallbacks: []`. +- `params`: parametri stream per-agente uniti sopra la voce modello selezionata in `agents.defaults.models`. Usalo per override specifici dell'agente come `cacheRetention`, `temperature` o `maxTokens` senza duplicare l'intero catalogo modelli. +- `skills`: allowlist facoltativa di Skills per-agente. Se omessa, l'agente eredita `agents.defaults.skills` quando impostato; una lista esplicita sostituisce i predefiniti invece di unirli, e `[]` significa nessuna Skills. +- `thinkingDefault`: livello 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`: visibilità reasoning predefinita facoltativa per-agente (`on | off | stream`). Si applica quando non è impostato alcun override reasoning per-messaggio o per-sessione. +- `fastModeDefault`: predefinito facoltativo per-agente per la modalità veloce (`true | false`). Si applica quando non è impostato alcun override della fast-mode per-messaggio o per-sessione. +- `runtime`: descrittore runtime facoltativo per-agente. Usa `type: "acp"` con i predefiniti `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) quando l'agente deve usare per impostazione predefinita sessioni harness ACP. +- `identity.avatar`: percorso relativo alla workspace, URL `http(s)` o URI `data:`. +- `identity` deriva valori predefiniti: `ackReaction` da `emoji`, `mentionPatterns` da `name`/`emoji`. +- `subagents.allowAgents`: allowlist degli id agente per `sessions_spawn` (`["*"]` = qualsiasi; predefinito: 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` (forza la selezione esplicita del profilo; predefinito: false). --- ## Routing multi-agente -Esegui più agenti isolati in un solo 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 { @@ -1556,11 +1567,11 @@ Esegui più agenti isolati in un solo Gateway. Vedi [Multi-Agent](/it/concepts/m } ``` -### Campi di corrispondenza dei binding +### Campi di corrispondenza binding -- `type` (facoltativo): `route` per il routing normale (type mancante equivale a route), `acp` per binding di conversazioni ACP persistenti. +- `type` (facoltativo): `route` per il routing normale (il tipo mancante usa come predefinito route), `acp` per binding persistenti di conversazioni ACP. - `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 }` @@ -1571,14 +1582,14 @@ Esegui più agenti isolati in un solo Gateway. Vedi [Multi-Agent](/it/concepts/m 2. `match.guildId` 3. `match.teamId` 4. `match.accountId` (esatto, senza peer/guild/team) -5. `match.accountId: "*"` (a livello di canale) +5. `match.accountId: "*"` (a livello canale) 6. Agente predefinito All'interno di ogni livello, vince la prima voce `bindings` corrispondente. -Per le voci `type: "acp"`, OpenClaw risolve in base all'identità esatta della conversazione (`match.channel` + account + `match.peer.id`) e non usa l'ordine a livelli dei binding di route sopra. +Per le voci `type: "acp"`, OpenClaw risolve per identità conversazione esatta (`match.channel` + account + `match.peer.id`) e non usa l'ordine a livelli dei binding di route qui sopra. -### Profili di accesso per agente +### Profili di accesso per-agente @@ -1598,7 +1609,7 @@ Per le voci `type: "acp"`, OpenClaw risolve in base all'identità esatta della c - + ```json5 { @@ -1673,7 +1684,7 @@ Per le voci `type: "acp"`, OpenClaw risolve in base all'identità esatta della c -Vedi [Multi-Agent Sandbox & Tools](/it/tools/multi-agent-sandbox-tools) per i dettagli di precedenza. +Vedi [Sandbox e strumenti multi-agente](/it/tools/multi-agent-sandbox-tools) per i dettagli sulla precedenza. --- @@ -1726,35 +1737,35 @@ 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` (predefinito): ogni mittente ottiene una sessione isolata all'interno di un contesto canale. - - `global`: tutti i partecipanti in un contesto canale condividono una singola sessione (da usare solo quando si intende un contesto condiviso). +- **`scope`**: strategia base di raggruppamento sessione 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 il contesto condiviso è intenzionale). - **`dmScope`**: come vengono raggruppati i DM. - `main`: tutti i DM condividono la sessione principale. - - `per-peer`: isola per ID mittente tra i canali. + - `per-peer`: isola per id mittente tra i canali. - `per-channel-peer`: isola per canale + mittente (consigliato per inbox multiutente). - `per-account-channel-peer`: isola per account + canale + mittente (consigliato per multi-account). -- **`identityLinks`**: mappa gli ID canonici a peer con prefisso provider per la condivisione della sessione tra canali. -- **`reset`**: criterio primario di reset. `daily` resetta all'ora locale `atHour`; `idle` resetta dopo `idleMinutes`. Quando entrambi sono configurati, vince quello che scade per primo. +- **`identityLinks`**: mappa id canonici a peer con prefisso provider per la condivisione della sessione cross-channel. +- **`reset`**: criterio di reset primario. `daily` resetta a `atHour` nell'ora locale; `idle` resetta dopo `idleMinutes`. Quando entrambi sono configurati, vince quello che scade per primo. - **`resetByType`**: override per tipo (`direct`, `group`, `thread`). Il legacy `dm` è accettato come alias di `direct`. -- **`parentForkMaxTokens`**: massimo `totalTokens` consentito nella sessione genitore quando si crea una sessione thread derivata (predefinito `100000`). - - Se il `totalTokens` del genitore è sopra questo valore, OpenClaw avvia una nuova sessione thread invece di ereditare la cronologia della trascrizione del genitore. - - Imposta `0` per disabilitare questa protezione e consentire sempre il fork dal genitore. +- **`parentForkMaxTokens`**: massimo `totalTokens` della sessione padre consentito quando si crea una sessione thread forked (predefinito `100000`). + - Se `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 guardia e consentire sempre il fork dal padre. - **`mainKey`**: campo legacy. Il runtime ora usa sempre `"main"` per il bucket principale delle chat dirette. -- **`agentToAgent.maxPingPongTurns`**: massimo di turni di risposta reciproca tra agenti durante gli scambi agent-to-agent (intero, intervallo: `0`–`5`). `0` disabilita la catena ping-pong. -- **`sendPolicy`**: corrisponde per `channel`, `chatType` (`direct|group|channel`, con alias legacy `dm`), `keyPrefix` o `rawKeyPrefix`. Vince il primo deny. -- **`maintenance`**: controlli di pulizia + retention dell'archivio sessioni. +- **`agentToAgent.maxPingPongTurns`**: massimo numero di turni di risposta reciproca tra agenti durante scambi agent-to-agent (intero, intervallo: `0`–`5`). `0` disabilita il chaining 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 per lo storage sessione. - `mode`: `warn` emette solo avvisi; `enforce` applica la pulizia. - - `pruneAfter`: soglia di età per voci obsolete (predefinito `30d`). + - `pruneAfter`: soglia temporale per le voci obsolete (predefinito `30d`). - `maxEntries`: numero massimo di voci in `sessions.json` (predefinito `500`). - `rotateBytes`: ruota `sessions.json` quando supera questa dimensione (predefinito `10mb`). - - `resetArchiveRetention`: retention per gli archivi delle trascrizioni `*.reset.`. Usa come 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. Predefinito: `80%` di `maxDiskBytes`. + - `resetArchiveRetention`: conservazione per gli archivi transcript `*.reset.`. Usa come predefinito `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 la pulizia del budget. Predefinito `80%` di `maxDiskBytes`. - **`threadBindings`**: valori predefiniti globali per le funzionalità di sessione legate ai thread. - - `enabled`: interruttore predefinito master (i provider possono fare override; Discord usa `channels.discord.threadBindings.enabled`) - - `idleHours`: disfocus automatico predefinito per inattività in ore (`0` lo disabilita; i provider possono fare override) - - `maxAgeHours`: età massima rigida predefinita in ore (`0` la disabilita; i provider possono fare override) + - `enabled`: interruttore predefinito principale (i provider possono sovrascriverlo; Discord usa `channels.discord.threadBindings.enabled`) + - `idleHours`: auto-unfocus predefinito per inattività in ore (`0` disabilita; i provider possono sovrascrivere) + - `maxAgeHours`: età massima rigida predefinita in ore (`0` disabilita; i provider possono sovrascrivere) @@ -1790,7 +1801,7 @@ Vedi [Multi-Agent Sandbox & Tools](/it/tools/multi-agent-sandbox-tools) per i de } ``` -### Prefisso della risposta +### Prefisso di risposta Override per canale/account: `channels..responsePrefix`, `channels..accounts..responsePrefix`. @@ -1798,30 +1809,30 @@ Risoluzione (vince il più specifico): account → canale → globale. `""` disa **Variabili del template:** -| Variabile | Descrizione | Esempio | -| ----------------- | ------------------------ | --------------------------- | -| `{model}` | Nome breve del modello | `claude-opus-4-6` | -| `{modelFull}` | Identificatore completo del modello | `anthropic/claude-opus-4-6` | -| `{provider}` | Nome del provider | `anthropic` | -| `{thinkingLevel}` | Livello thinking corrente | `high`, `low`, `off` | -| `{identity.name}` | Nome identità agente | (uguale a `"auto"`) | +| Variabile | Descrizione | Esempio | +| ----------------- | ---------------------- | --------------------------- | +| `{model}` | Nome modello breve | `claude-opus-4-6` | +| `{modelFull}` | Identificatore modello completo | `anthropic/claude-opus-4-6` | +| `{provider}` | Nome provider | `anthropic` | +| `{thinkingLevel}` | Livello thinking corrente | `high`, `low`, `off` | +| `{identity.name}` | Nome identità agente | (uguale a `"auto"`) | Le variabili non distinguono tra maiuscole e minuscole. `{think}` è un alias di `{thinkingLevel}`. -### Ack reaction +### Reazione di ack -- Usa come predefinito `identity.emoji` dell'agente attivo, altrimenti `"👀"`. Imposta `""` per disabilitare. +- Usa come predefinito `identity.emoji` dell'agente attivo, altrimenti `"👀"`. Imposta `""` per disabilitarla. - Override per canale: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Ordine di risoluzione: account → canale → `messages.ackReaction` → fallback dell'identità. +- Ordine di risoluzione: account → canale → `messages.ackReaction` → fallback identità. - Scope: `group-mentions` (predefinito), `group-all`, `direct`, `all`. - `removeAckAfterReply`: rimuove l'ack 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 ack reaction sono attive. - Su Telegram, impostalo esplicitamente su `true` per abilitare le reazioni di stato del ciclo di vita. +- `messages.statusReactions.enabled`: abilita 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. ### Debounce in ingresso -Raggruppa rapidi messaggi di solo testo dallo stesso mittente in un singolo turno dell'agente. Media/allegati vengono inviati immediatamente. I comandi di controllo bypassano il debounce. +Raggruppa messaggi rapidi solo testuali dallo stesso mittente in un singolo turno agente. I media/allegati fanno flush immediato. I comandi di controllo bypassano il debounce. ### TTS (text-to-speech) @@ -1864,12 +1875,12 @@ Raggruppa rapidi messaggi di solo testo dallo stesso mittente in un singolo turn } ``` -- `auto` controlla l'auto-TTS. `/tts off|always|inbound|tagged` fa override per sessione. -- `summaryModel` sostituisce `agents.defaults.model.primary` per l'auto-riepilogo. -- `modelOverrides` è abilitato per impostazione predefinita; `modelOverrides.allowProvider` usa come predefinito `false` (attivazione esplicita). -- Le chiavi API usano come fallback `ELEVENLABS_API_KEY`/`XI_API_KEY` e `OPENAI_API_KEY`. -- `openai.baseUrl` sostituisce 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 con OpenAI e allenta la convalida di modello/voce. +- `auto` controlla l'auto-TTS. `/tts off|always|inbound|tagged` sovrascrive per sessione. +- `summaryModel` sovrascrive `agents.defaults.model.primary` per l'auto-riassunto. +- `modelOverrides` è abilitato per impostazione predefinita; `modelOverrides.allowProvider` usa come predefinito `false` (opt-in). +- Le API key usano in 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 con OpenAI e allenta la validazione di modello/voce. --- @@ -1900,50 +1911,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 legacy piatte (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) sono solo per compatibilità e vengono migrate automaticamente in `talk.providers.`. +- Le chiavi Talk flat legacy (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) sono solo per compatibilità e vengono migrate automaticamente in `talk.providers.`. - Gli ID voce usano come fallback `ELEVENLABS_VOICE_ID` o `SAG_VOICE_ID`. - `providers.*.apiKey` accetta stringhe in chiaro o oggetti SecretRef. -- Il fallback `ELEVENLABS_API_KEY` si applica solo quando non è configurata alcuna chiave API Talk. -- `providers.*.voiceAliases` consente alle direttive Talk di usare nomi descrittivi. -- `silenceTimeoutMs` controlla quanto 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`). +- Il fallback `ELEVENLABS_API_KEY` si applica solo quando non è configurata alcuna API key Talk. +- `providers.*.voiceAliases` consente alle direttive Talk di usare nomi amichevoli. +- `silenceTimeoutMs` controlla quanto a lungo la modalità Talk aspetta 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 degli strumenti +### Profili strumento -`tools.profile` imposta una allowlist di base prima di `tools.allow`/`tools.deny`: +`tools.profile` imposta una allowlist base prima di `tools.allow`/`tools.deny`: -L'onboarding locale imposta per i nuovi config locali `tools.profile: "coding"` quando non impostato (i profili espliciti esistenti vengono preservati). +L'onboarding locale imposta per default nelle nuove configurazioni locali `tools.profile: "coding"` quando non impostato (i profili espliciti esistenti vengono preservati). | Profilo | Include | | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | | `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) | +| `full` | Nessuna restrizione (uguale a non impostato) | ### Gruppi di strumenti -| 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) | +| 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) | ### `tools.allow` / `tools.deny` -Criterio globale di allow/deny degli strumenti (deny ha priorità). Non distingue tra maiuscole e minuscole, supporta wildcard `*`. Applicato anche quando il sandbox Docker è disattivato. +Criterio globale allow/deny degli strumenti (vince il deny). Non distingue tra maiuscole e minuscole, supporta wildcard `*`. Applicato anche quando la sandbox Docker è disattivata. ```json5 { @@ -1953,7 +1964,7 @@ Criterio globale di allow/deny degli strumenti (deny ha priorità). Non distingu ### `tools.byProvider` -Limita ulteriormente gli strumenti per provider o modelli specifici. Ordine: profilo base → profilo provider → allow/deny. +Restringe ulteriormente gli strumenti per provider o modelli specifici. Ordine: profilo base → profilo provider → allow/deny. ```json5 { @@ -1969,7 +1980,7 @@ Limita ulteriormente gli strumenti per provider o modelli specifici. Ordine: pro ### `tools.elevated` -Controlla l'accesso exec elevato fuori dal sandbox: +Controlla l'accesso exec elevated fuori dalla sandbox: ```json5 { @@ -1985,9 +1996,9 @@ Controlla l'accesso exec elevato fuori dal sandbox: } ``` -- L'override per-agente (`agents.list[].tools.elevated`) può solo limitare ulteriormente. -- `/elevated on|off|ask|full` salva lo stato per sessione; le direttive inline si applicano a un singolo messaggio. -- `exec` elevato bypassa il sandbox e usa il percorso di escape configurato (`gateway` per impostazione predefinita, o `node` quando la destinazione exec è `node`). +- L'override per-agente (`agents.list[].tools.elevated`) può solo restringere ulteriormente. +- `/elevated on|off|ask|full` salva lo stato per sessione; le direttive inline si applicano al singolo messaggio. +- `exec` elevated bypassa la sandbox e usa il percorso di escape configurato (`gateway` per impostazione predefinita, o `node` quando il target exec è `node`). ### `tools.exec` @@ -2011,8 +2022,8 @@ Controlla l'accesso exec elevato fuori dal sandbox: ### `tools.loopDetection` -I controlli di sicurezza dei loop tool sono **disabilitati per impostazione predefinita**. Imposta `enabled: true` per attivare il rilevamento. -Le impostazioni possono essere definite globalmente in `tools.loopDetection` e sostituite per agente in `agents.list[].tools.loopDetection`. +I controlli di sicurezza del tool-loop sono **disabilitati per impostazione predefinita**. Imposta `enabled: true` per attivare il rilevamento. +Le impostazioni possono essere definite globalmente in `tools.loopDetection` e sovrascritte per-agente in `agents.list[].tools.loopDetection`. ```json5 { @@ -2033,14 +2044,14 @@ Le impostazioni possono essere definite globalmente in `tools.loopDetection` e s } ``` -- `historySize`: cronologia massima delle chiamate tool mantenuta per l'analisi dei loop. -- `warningThreshold`: soglia di pattern ripetuto senza progresso per gli avvisi. -- `criticalThreshold`: soglia ripetuta 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 su strumenti poll noti (`process.poll`, `command_status`, ecc.). +- `historySize`: massima cronologia di 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 qualunque esecuzione senza progresso. +- `detectors.genericRepeat`: avvisa su chiamate ripetute con stesso strumento/stessi argomenti. +- `detectors.knownPollNoProgress`: avvisa/blocca sui tool di polling noti (`process.poll`, `command_status`, ecc.). - `detectors.pingPong`: avvisa/blocca su pattern alternati a coppie senza progresso. -- Se `warningThreshold >= criticalThreshold` o `criticalThreshold >= globalCircuitBreakerThreshold`, la convalida fallisce. +- Se `warningThreshold >= criticalThreshold` o `criticalThreshold >= globalCircuitBreakerThreshold`, la validazione fallisce. ### `tools.web` @@ -2106,32 +2117,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 dell'ID modello -- `profile` / `preferredProfile`: selezione profilo `auth-profiles.json` +- `provider`: id del provider API (`openai`, `anthropic`, `google`/`gemini`, `groq`, ecc.) +- `model`: override del model id +- `profile` / `preferredProfile`: selezione profilo di `auth-profiles.json` **Voce CLI** (`type: "cli"`): -- `command`: eseguibile da lanciare -- `args`: argomenti con template (supporta `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, ecc.) +- `command`: eseguibile da avviare +- `args`: argomenti templati (supporta `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, ecc.) **Campi comuni:** -- `capabilities`: elenco facoltativo (`image`, `audio`, `video`). Predefiniti: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. +- `capabilities`: lista facoltativa (`image`, `audio`, `video`). Predefiniti: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. - `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: override per voce. -- Gli errori usano come fallback la voce successiva. +- I fallimenti usano come fallback la voce successiva. -L'autenticazione provider segue l'ordine standard: `auth-profiles.json` → variabili env → `models.providers.*.apiKey`. +L'auth provider segue l'ordine standard: `auth-profiles.json` → variabili env → `models.providers.*.apiKey`. -**Campi completamento asincrono:** +**Campi di completamento asincrono:** -- `asyncCompletion.directSend`: quando `true`, le attività asincrone completate di `music_generate` +- `asyncCompletion.directSend`: quando `true`, i task asincroni completati di `music_generate` e `video_generate` provano prima la consegna diretta al canale. Predefinito: `false` - (percorso legacy di wake/sessione richiedente e consegna modello). + (percorso legacy di wake/consegna modello della sessione richiedente). @@ -2152,7 +2163,7 @@ L'autenticazione provider segue l'ordine standard: `auth-profiles.json` → vari Controlla quali sessioni possono essere puntate dagli strumenti di sessione (`sessions_list`, `sessions_history`, `sessions_send`). -Predefinito: `tree` (sessione corrente + sessioni generate da essa, come i subagenti). +Predefinito: `tree` (sessione corrente + sessioni generate da essa, come i subagent). ```json5 { @@ -2168,10 +2179,10 @@ Predefinito: `tree` (sessione corrente + sessioni generate da essa, come i subag Note: - `self`: solo la chiave della sessione corrente. -- `tree`: sessione corrente + sessioni generate dalla sessione corrente (subagenti). -- `agent`: qualsiasi sessione appartenente all'ID agente corrente (può includere altri utenti se usi sessioni per-mittente sotto lo stesso ID agente). +- `tree`: sessione corrente + sessioni generate dalla sessione corrente (subagent). +- `agent`: qualunque sessione appartenente all'id agente corrente (può includere altri utenti se esegui sessioni per-mittente sotto lo stesso id agente). - `all`: qualunque sessione. Il targeting cross-agent richiede comunque `tools.agentToAgent`. -- Clamp sandbox: quando la sessione corrente è in sandbox e `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, la visibilità viene forzata a `tree` anche se `tools.sessions.visibility="all"`. +- 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"`. ### `tools.sessions_spawn` @@ -2196,15 +2207,15 @@ Controlla il supporto agli allegati inline per `sessions_spawn`. Note: - Gli allegati sono supportati solo per `runtime: "subagent"`. Il runtime ACP li rifiuta. -- I file vengono materializzati nel workspace figlio in `.openclaw/attachments//` con un `.manifest.json`. -- Il contenuto degli allegati viene automaticamente redatto dalla persistenza della trascrizione. -- Gli input Base64 vengono convalidati con controlli rigorosi su alfabeto/padding e con una protezione sulle dimensioni prima della decodifica. +- I file vengono materializzati nella workspace figlia in `.openclaw/attachments//` con un `.manifest.json`. +- Il contenuto degli allegati viene automaticamente redatto dalla persistenza del transcript. +- Gli input Base64 vengono validati con controlli rigorosi su alfabeto/padding e una guardia di dimensione pre-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 degli strumenti integrati sperimentali. Predefinito disattivato a meno che non si applichi una regola di auto-abilitazione specifica del runtime. +Flag sperimentali degli strumenti integrati. Disattivati per impostazione predefinita salvo quando si applica una regola di auto-enable specifica del runtime. ```json5 { @@ -2218,9 +2229,9 @@ Flag degli strumenti integrati sperimentali. Predefinito disattivato a meno che Note: -- `planTool`: abilita lo strumento strutturato `update_plan` per il tracciamento di lavori non banali in più fasi. -- Predefinito: `false` per i provider non OpenAI. Le esecuzioni OpenAI e OpenAI Codex lo abilitano automaticamente. -- Quando abilitato, il system prompt aggiunge anche linee guida d'uso così il modello lo usa solo per lavori sostanziali e mantiene al massimo un solo passo `in_progress`. +- `planTool`: abilita lo strumento strutturato `update_plan` per il tracciamento del lavoro multi-step non banale. +- Predefinito: `false` per provider non OpenAI. Le esecuzioni OpenAI e OpenAI Codex lo abilitano automaticamente. +- Quando è abilitato, il system prompt aggiunge anche linee guida d'uso in modo che il modello lo usi solo per lavoro sostanziale e mantenga al massimo un solo passaggio `in_progress`. ### `agents.defaults.subagents` @@ -2240,14 +2251,14 @@ Note: } ``` -- `model`: modello predefinito per i subagenti generati. Se omesso, i subagenti ereditano il modello del chiamante. -- `allowAgents`: allowlist predefinita degli ID agente destinazione per `sessions_spawn` quando l'agente richiedente non imposta il proprio `subagents.allowAgents` (`["*"]` = qualunque; predefinito: solo lo stesso agente). +- `model`: modello predefinito per i sub-agenti generati. Se omesso, i sub-agenti 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 tool omette `runTimeoutSeconds`. `0` significa nessun timeout. -- Criterio strumenti per subagente: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. +- Criterio tool per-subagent: `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` nella configurazione o `~/.openclaw/agents//agent/models.json`. @@ -2279,45 +2290,45 @@ OpenClaw usa il catalogo modelli integrato. Aggiungi provider personalizzati tra ``` - Usa `authHeader: true` + `headers` per esigenze di autenticazione personalizzate. -- Sostituisci la root della configurazione dell'agente con `OPENCLAW_AGENT_DIR` (o `PI_CODING_AGENT_DIR`, alias legacy di variabile d'ambiente). +- Sovrascrivi la radice di configurazione dell'agente con `OPENCLAW_AGENT_DIR` (o `PI_CODING_AGENT_DIR`, alias legacy della variabile d'ambiente). - Precedenza di unione per ID provider corrispondenti: - - I valori non vuoti `baseUrl` dell'agente in `models.json` hanno la priorità. - - I valori non vuoti `apiKey` dell'agente hanno la priorità solo quando quel provider non è gestito da SecretRef nel contesto attuale di config/profilo auth. - - I valori `apiKey` del provider gestiti da SecretRef vengono aggiornati dai marker della fonte (`ENV_VAR_NAME` per ref env, `secretref-managed` per ref file/exec) invece di persistere i segreti risolti. - - I valori header del provider gestiti da SecretRef vengono aggiornati dai marker della fonte (`secretref-env:ENV_VAR_NAME` per ref env, `secretref-managed` per ref file/exec). - - `apiKey`/`baseUrl` dell'agente vuoti o mancanti usano come fallback `models.providers` nella configurazione. - - I valori `contextWindow`/`maxTokens` dei modelli corrispondenti usano il valore più alto tra config esplicita e valori impliciti del catalogo. - - `contextTokens` del modello corrispondente preserva un limite runtime esplicito quando presente; usalo per limitare il contesto effettivo senza cambiare i metadati nativi del modello. - - Usa `models.mode: "replace"` quando vuoi che la configurazione riscriva completamente `models.json`. - - La persistenza dei marker è autorevole rispetto alla fonte: i marker vengono scritti dallo snapshot della configurazione sorgente attiva (pre-risoluzione), non dai valori segreti runtime risolti. + - I valori non vuoti `baseUrl` in `models.json` dell'agente hanno la precedenza. + - I valori non vuoti `apiKey` dell'agente hanno la precedenza solo quando quel provider non è gestito da SecretRef nel contesto corrente di config/auth-profile. + - I valori `apiKey` del provider gestiti da SecretRef vengono aggiornati dai marker della sorgente (`ENV_VAR_NAME` per ref env, `secretref-managed` per ref file/exec) invece di persistere segreti risolti. + - I valori header del provider gestiti da SecretRef vengono aggiornati dai marker della sorgente (`secretref-env:ENV_VAR_NAME` per ref env, `secretref-managed` per ref file/exec). + - `apiKey`/`baseUrl` dell'agente vuoti o mancanti usano come fallback `models.providers` in config. + - I valori corrispondenti `contextWindow`/`maxTokens` del modello usano il valore più alto tra config esplicita e valori impliciti del catalogo. + - Il valore corrispondente `contextTokens` del modello preserva un limite runtime esplicito quando presente; usalo per limitare il contesto effettivo senza cambiare i metadata nativi del modello. + - Usa `models.mode: "replace"` quando vuoi che la config riscriva completamente `models.json`. + - La persistenza dei marker è autorevole rispetto alla sorgente: i marker vengono scritti dallo snapshot config attivo della sorgente (pre-risoluzione), non dai valori segreti runtime risolti. ### Dettagli dei campi provider - `models.mode`: comportamento del catalogo provider (`merge` o `replace`). -- `models.providers`: mappa dei provider personalizzati con chiave ID provider. +- `models.providers`: mappa provider personalizzati indicizzata per provider id. - `models.providers.*.api`: adattatore di richiesta (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai`, ecc). -- `models.providers.*.apiKey`: credenziale del provider (preferire SecretRef/sostituzione env). -- `models.providers.*.auth`: strategia di autenticazione (`api-key`, `token`, `oauth`, `aws-sdk`). +- `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 (predefinito: `true`). - `models.providers.*.authHeader`: forza il trasporto della credenziale nell'header `Authorization` quando richiesto. - `models.providers.*.baseUrl`: URL base dell'API upstream. - `models.providers.*.headers`: header statici extra per routing proxy/tenant. -- `models.providers.*.request`: override del trasporto per le richieste HTTP del model-provider. - - `request.headers`: header extra (uniti a quelli predefiniti del provider). I valori accettano SecretRef. - - `request.auth`: override della strategia auth. Modalità: `"provider-default"` (usa l'autenticazione integrata del provider), `"authorization-bearer"` (con `token`), `"header"` (con `headerName`, `value`, `prefix` facoltativo). - - `request.proxy`: override del proxy HTTP. Modalità: `"env-proxy"` (usa le variabili env `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (con `url`). Entrambe le modalità accettano un sotto-oggetto `tls` facoltativo. +- `models.providers.*.request`: override di trasporto per richieste HTTP del model-provider. + - `request.headers`: header extra (uniti ai predefiniti del 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). + - `request.proxy`: override 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`. -- `models.providers.*.models`: voci esplicite del catalogo modelli del provider. -- `models.providers.*.models.*.contextWindow`: metadati nativi della finestra di contesto del modello. -- `models.providers.*.models.*.contextTokens`: limite runtime facoltativo del contesto. 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 un `baseUrl` non nativo non vuoto (host non `api.openai.com`), OpenClaw lo forza a `false` a runtime. `baseUrl` vuoto/omesso mantiene il comportamento OpenAI predefinito. -- `plugins.entries.amazon-bedrock.config.discovery`: root delle impostazioni di auto-discovery Bedrock. +- `models.providers.*.models`: voci esplicite del catalogo modelli provider. +- `models.providers.*.models.*.contextWindow`: metadata 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 facoltativo di compatibilità. Per `api: "openai-completions"` con un `baseUrl` non nativo non vuoto (host diverso da `api.openai.com`), OpenClaw lo forza a `false` a runtime. `baseUrl` vuoto/omesso mantiene il comportamento predefinito OpenAI. +- `plugins.entries.amazon-bedrock.config.discovery`: radice delle impostazioni di auto-discovery Bedrock. - `plugins.entries.amazon-bedrock.config.discovery.enabled`: attiva/disattiva il discovery implicito. - `plugins.entries.amazon-bedrock.config.discovery.region`: regione AWS per il discovery. -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: filtro facoltativo provider-id per discovery mirato. -- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: intervallo di polling per l'aggiornamento del discovery. +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: filtro facoltativo per provider-id per discovery mirato. +- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: intervallo di polling per il refresh del discovery. - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: finestra di contesto di fallback per i modelli scoperti. -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: token massimi in uscita di fallback per i modelli scoperti. +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: token massimi di output di fallback per i modelli scoperti. ### Esempi di provider @@ -2355,7 +2366,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 diretto. +Usa `cerebras/zai-glm-4.7` per Cerebras; `zai/glm-4.7` per Z.AI direct. @@ -2372,7 +2383,7 @@ Usa `cerebras/zai-glm-4.7` per Cerebras; `zai/glm-4.7` per Z.AI diretto. } ``` -Imposta `OPENCODE_API_KEY` (o `OPENCODE_ZEN_API_KEY`). Usa riferimenti `opencode/...` per il catalogo Zen o riferimenti `opencode-go/...` per il catalogo Go. Scorciatoia: `openclaw onboard --auth-choice opencode-zen` o `openclaw onboard --auth-choice opencode-go`. +Imposta `OPENCODE_API_KEY` (o `OPENCODE_ZEN_API_KEY`). Usa riferimenti `opencode/...` per il catalogo Zen oppure riferimenti `opencode-go/...` per il catalogo Go. Scorciatoia: `openclaw onboard --auth-choice opencode-zen` o `openclaw onboard --auth-choice opencode-go`. @@ -2393,7 +2404,7 @@ Imposta `ZAI_API_KEY`. `z.ai/*` e `z-ai/*` sono alias accettati. Scorciatoia: `o - Endpoint generale: `https://api.z.ai/api/paas/v4` - 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. +- Per l'endpoint generale, definisci un provider personalizzato con l'override dell'URL base. @@ -2434,9 +2445,9 @@ 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`. -Gli endpoint Moonshot nativi pubblicizzano la compatibilità d'uso dello streaming sul trasporto condiviso -`openai-completions`, e OpenClaw ora la gestisce in base alle capacità dell'endpoint -piuttosto che solo all'ID provider integrato. +Gli endpoint Moonshot nativi dichiarano compatibilità d'uso con lo streaming sul trasporto condiviso +`openai-completions`, e OpenClaw ora la determina dalle capacità dell'endpoint +invece che dal solo provider id integrato. @@ -2493,7 +2504,7 @@ Compatibile con Anthropic, provider integrato. Scorciatoia: `openclaw onboard -- } ``` -Il base URL deve omettere `/v1` (il client Anthropic lo aggiunge). Scorciatoia: `openclaw onboard --auth-choice synthetic-api-key`. +L'URL base dovrebbe omettere `/v1` (il client Anthropic lo aggiunge). Scorciatoia: `openclaw onboard --auth-choice synthetic-api-key`. @@ -2534,19 +2545,19 @@ 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 ora usa come predefinito solo M2.7. -Sul percorso di streaming compatibile con Anthropic, OpenClaw disabilita per impostazione predefinita il thinking di MiniMax -a meno che tu non imposti esplicitamente `thinking`. `/fast on` o -`params.fastMode: true` riscrivono `MiniMax-M2.7` in +Il catalogo modelli ora usa per default solo M2.7. +Sul percorso streaming compatibile con Anthropic, OpenClaw disabilita il thinking di MiniMax +per impostazione predefinita salvo che tu non imposti esplicitamente `thinking`. `/fast on` o +`params.fastMode: true` riscrive `MiniMax-M2.7` in `MiniMax-M2.7-highspeed`. -Vedi [Modelli locali](/it/gateway/local-models). In breve: esegui un grande modello locale tramite LM Studio Responses API su hardware serio; mantieni i modelli ospitati uniti per il fallback. +Vedi [Modelli locali](/it/gateway/local-models). In breve: esegui un grande modello locale tramite LM Studio Responses API su hardware adeguato; mantieni i modelli ospitati uniti come fallback. @@ -2577,13 +2588,14 @@ Vedi [Modelli locali](/it/gateway/local-models). In breve: esegui un grande mode } ``` -- `allowBundled`: allowlist facoltativa solo per le Skills incluse (le Skills managed/workspace non sono interessate). -- `load.extraDirs`: root extra condivise per le Skills (precedenza più bassa). -- `install.preferBrew`: quando true, preferisce gli installer Homebrew quando `brew` è disponibile prima di ricorrere ad altri tipi di installer. +- `allowBundled`: allowlist facoltativa solo per le Skills bundled (le Skills managed/workspace non sono interessate). +- `load.extraDirs`: radici condivise aggiuntive delle Skills (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 dell'installer node per le specifiche `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` disabilita una Skills anche se inclusa/installata. -- `entries..apiKey`: campo di praticità per le Skills che dichiarano una variabile env primaria (stringa in chiaro o oggetto SecretRef). +- `entries..enabled: false` disabilita una skill anche se bundled/installata. +- `entries..apiKey`: campo di convenienza API key per skill che dichiarano una variabile env primaria (stringa in chiaro o oggetto SecretRef). --- @@ -2612,34 +2624,34 @@ Vedi [Modelli locali](/it/gateway/local-models). In breve: esegui un grande mode ``` - Caricati da `~/.openclaw/extensions`, `/.openclaw/extensions`, più `plugins.load.paths`. -- Il discovery accetta plugin OpenClaw nativi più bundle compatibili Codex e Claude, inclusi bundle Claude senza manifest con layout predefinito. +- Il discovery accetta plugin OpenClaw nativi oltre a bundle compatibili Codex e bundle Claude, inclusi bundle Claude senza manifest nel layout predefinito. - **Le modifiche di configurazione richiedono un riavvio del gateway.** -- `allow`: allowlist facoltativa (vengono caricati solo i plugin elencati). `deny` ha priorità. -- `plugins.entries..apiKey`: campo di praticità per la chiave API a livello plugin (quando supportato dal plugin). +- `allow`: allowlist facoltativa (si caricano solo i plugin elencati). `deny` ha la precedenza. +- `plugins.entries..apiKey`: campo di convenienza API key a livello plugin (quando supportato dal plugin). - `plugins.entries..env`: mappa di variabili env con ambito 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ò `modelOverride` e `providerOverride` legacy. Si applica agli hook dei plugin nativi e alle directory hook fornite dai bundle supportati. -- `plugins.entries..subagent.allowModelOverride`: considera esplicitamente affidabile questo plugin per richiedere override per-esecuzione di `provider` e `model` per esecuzioni di subagenti in background. -- `plugins.entries..subagent.allowedModels`: allowlist facoltativa di destinazioni canoniche `provider/model` per override di subagenti affidabili. Usa `"*"` solo quando vuoi intenzionalmente consentire qualunque 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 web-fetch Firecrawl. - - `apiKey`: chiave API Firecrawl (accetta SecretRef). Usa come fallback `plugins.entries.firecrawl.config.webSearch.apiKey`, il legacy `tools.web.fetch.firecrawl.apiKey` o la variabile env `FIRECRAWL_API_KEY`. - - `baseUrl`: URL base dell'API Firecrawl (predefinito: `https://api.firecrawl.dev`). +- `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 però i legacy `modelOverride` e `providerOverride`. Si applica agli hook plugin nativi e alle directory hook fornite dai bundle supportati. +- `plugins.entries..subagent.allowModelOverride`: considera esplicitamente affidabile questo plugin per richiedere override per-esecuzione di `provider` e `model` per esecuzioni subagent in background. +- `plugins.entries..subagent.allowedModels`: allowlist facoltativa di target canonici `provider/model` per override affidabili dei subagent. Usa `"*"` solo quando vuoi intenzionalmente consentire qualunque modello. +- `plugins.entries..config`: oggetto config definito dal plugin (convalidato dallo schema plugin OpenClaw nativo quando disponibile). +- `plugins.entries.firecrawl.config.webFetch`: impostazioni del provider Firecrawl web-fetch. + - `apiKey`: API key Firecrawl (accetta SecretRef). Usa come fallback `plugins.entries.firecrawl.config.webSearch.apiKey`, il legacy `tools.web.fetch.firecrawl.apiKey` oppure la variabile env `FIRECRAWL_API_KEY`. + - `baseUrl`: URL base 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). + - `maxAgeMs`: età massima cache in millisecondi (predefinito: `172800000` / 2 giorni). - `timeoutSeconds`: timeout della richiesta scrape in secondi (predefinito: `60`). - `plugins.entries.xai.config.xSearch`: impostazioni 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 memory dreaming (sperimentale). Vedi [Dreaming](/concepts/dreaming) per fasi e soglie. - - `enabled`: interruttore principale dreaming (predefinito `false`). - - `frequency`: cadenza cron per ogni sweep completo di dreaming (`"0 3 * * *"` per impostazione predefinita). - - il criterio delle fasi e le soglie sono dettagli implementativi (non chiavi di configurazione rivolte all'utente). +- `plugins.entries.memory-core.config.dreaming`: impostazioni dreaming della memoria (sperimentale). Vedi [Dreaming](/it/concepts/dreaming) per fasi e soglie. + - `enabled`: interruttore principale del dreaming (predefinito `false`). + - `frequency`: cadenza cron per ogni sweep completo di dreaming (predefinito `"0 3 * * *"`). + - il criterio di fase e le soglie sono dettagli implementativi (non chiavi di configurazione rivolte all'utente). - 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 raw della 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 context engine attivo; usa come predefinito `"legacy"` a meno che tu non ne installi e selezioni un altro. -- `plugins.installs`: metadati di installazione gestiti dalla CLI usati da `openclaw plugins update`. +- `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"` salvo installazione e selezione di un altro motore. +- `plugins.installs`: metadata di installazione gestiti dalla CLI usati da `openclaw plugins update`. - Include `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. - - Considera `plugins.installs.*` come stato gestito; preferisci i comandi CLI alle modifiche manuali. + - Tratta `plugins.installs.*` come stato gestito; preferisci i comandi CLI alle modifiche manuali. Vedi [Plugin](/it/tools/plugin). @@ -2683,23 +2695,26 @@ Vedi [Plugin](/it/tools/plugin). - `evaluateEnabled: false` disabilita `act:evaluate` e `wait --fn`. - `ssrfPolicy.dangerouslyAllowPrivateNetwork` usa 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 di profilo CDP remoti (`profiles.*.cdpUrl`) sono soggetti allo stesso blocco di rete privata durante i controlli di raggiungibilità/discovery. +- Imposta `ssrfPolicy.dangerouslyAllowPrivateNetwork: false` per una navigazione browser rigorosa solo pubblica. +- In modalità strict, gli endpoint di profilo CDP remoto (`profiles.*.cdpUrl`) sono soggetti allo stesso blocco di rete privata durante i controlli di raggiungibilità/discovery. - `ssrfPolicy.allowPrivateNetwork` resta supportato come alias legacy. -- In modalità rigorosa, usa `ssrfPolicy.hostnameAllowlist` e `ssrfPolicy.allowedHostnames` per eccezioni esplicite. +- In modalità strict, usa `ssrfPolicy.hostnameAllowlist` e `ssrfPolicy.allowedHostnames` per eccezioni esplicite. - I profili remoti sono solo attach-only (start/stop/reset disabilitati). - `profiles.*.cdpUrl` accetta `http://`, `https://`, `ws://` e `wss://`. Usa HTTP(S) quando vuoi che OpenClaw scopra `/json/version`; usa WS(S) - quando il tuo provider ti fornisce un URL WebSocket DevTools diretto. + quando il provider ti fornisce un URL WebSocket DevTools diretto. - I profili `existing-session` sono solo host e usano Chrome MCP invece di CDP. - I profili `existing-session` possono impostare `userDataDir` per puntare a uno specifico - profilo di browser basato su Chromium come Brave o Edge. -- I profili `existing-session` mantengono gli attuali limiti del routing Chrome MCP: - azioni basate su snapshot/ref invece del targeting tramite selettore CSS, hook di upload di un solo file, nessun override del timeout dialoghi, nessun `wait --load networkidle` e nessun `responsebody`, export PDF, intercettazione download o azioni batch. -- I profili locali gestiti `openclaw` assegnano automaticamente `cdpPort` e `cdpUrl`; imposta `cdpUrl` esplicitamente solo per CDP remoto. + profilo browser basato su Chromium come Brave o Edge. +- I profili `existing-session` mantengono gli attuali limiti del percorso Chrome MCP: + azioni guidate da snapshot/ref invece di targeting con selettori CSS, hook per upload + di un solo file, nessun override timeout dialog, 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-rilevamento: browser predefinito se basato su Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. - Servizio di controllo: solo loopback (porta derivata da `gateway.port`, predefinito `18791`). -- `extraArgs` aggiunge flag extra all'avvio locale di Chromium (ad esempio +- `extraArgs` aggiunge flag extra di avvio a Chromium locale (per esempio `--disable-gpu`, dimensioni finestra o flag di debug). --- @@ -2718,8 +2733,8 @@ Vedi [Plugin](/it/tools/plugin). } ``` -- `seamColor`: colore di accento per l'interfaccia nativa dell'app (tinta bolla modalità Talk, ecc.). -- `assistant`: override dell'identità nella Control UI. Usa come fallback l'identità dell'agente attivo. +- `seamColor`: colore di accento per il chrome UI dell'app nativa (tinta della bolla in modalità Talk, ecc.). +- `assistant`: override dell'identità della Control UI. Usa come fallback l'identità dell'agente attivo. --- @@ -2786,12 +2801,13 @@ Vedi [Plugin](/it/tools/plugin). -- `mode`: `local` (esegui il gateway) o `remote` (connettiti a un gateway remoto). Il gateway rifiuta di avviarsi a meno che non sia `local`. +- `mode`: `local` (esegue il gateway) o `remote` (si collega a un gateway remoto). Il gateway rifiuta di avviarsi salvo che sia `local`. - `port`: singola porta multiplexata per WS + HTTP. Precedenza: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. -- `bind`: `auto`, `loopback` (predefinito), `lan` (`0.0.0.0`), `tailnet` (solo IP Tailscale) o `custom`. -- **Alias bind legacy**: usa i valori della modalità bind in `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), non gli alias host (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Nota Docker**: il bind predefinito `loopback` ascolta su `127.0.0.1` dentro il contenitore. Con il networking bridge Docker (`-p 18789:18789`), il traffico arriva su `eth0`, quindi il gateway non è raggiungibile. Usa `--network host`, oppure imposta `bind: "lan"` (o `bind: "custom"` con `customBindHost: "0.0.0.0"`) per ascoltare su tutte le interfacce. -- **Auth**: obbligatoria per impostazione predefinita. I bind non loopback richiedono l'autenticazione del gateway. In pratica questo significa un token/password condiviso o un reverse proxy identity-aware con `gateway.auth.mode: "trusted-proxy"`. L'onboarding wizard genera un token per impostazione predefinita. +- `bind`: `auto`, `loopback` (predefinito), `lan` (`0.0.0.0`), `tailnet` (solo IP Tailscale), oppure `custom`. +- **Alias bind legacy**: usa valori di modalità bind in `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), non alias host (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). +- **Nota Docker**: il bind predefinito `loopback` ascolta su `127.0.0.1` all'interno del contenitore. Con la rete bridge Docker (`-p 18789:18789`), il traffico arriva su `eth0`, quindi il gateway non è raggiungibile. Usa `--network host`, oppure imposta `bind: "lan"` (o `bind: "custom"` con `customBindHost: "0.0.0.0"`) per ascoltare su tutte le interfacce. +- **Auth**: richiesta per impostazione predefinita. I bind non-loopback richiedono auth del gateway. In pratica significa un token/password condiviso o un reverse proxy identity-aware con `gateway.auth.mode: "trusted-proxy"`. La procedura guidata di onboarding genera un token per impostazione predefinita. - Se sono configurati sia `gateway.auth.token` sia `gateway.auth.password` (inclusi SecretRef), imposta esplicitamente `gateway.auth.mode` su `token` o `password`. L'avvio e i flussi di installazione/riparazione del servizio falliscono quando entrambi sono configurati e la modalità non è impostata. -- `gateway.auth.mode: "none"`: modalità senza autenticazione esplicita. Usala solo per configurazioni loopback locali fidate; questa opzione non viene intenzionalmente proposta dai prompt di onboarding. -- `gateway.auth.mode: "trusted-proxy"`: delega l'autenticazione a un reverse proxy identity-aware e considera affidabili gli header identità provenienti da `gateway.trustedProxies` (vedi [Trusted Proxy Auth](/gateway \ No newline at end of file +- `gateway.auth.mode: "none"`: modalità esplicita senza auth. Usala solo per configurazioni locali loopback affidabili; questa opzione intenzionalmente non viene proposta dai prompt di onboarding. +- `gateway.auth.mode: "trusted-proxy"`: delega l'auth a un reverse proxy identity-aware e si fida degli header di identità da `gateway.trustedProxies` (vedi [Auth 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'auth trusted-proxy. +- `gateway.auth.allowTailscale`: quando `true`, gli header di identità Tailscale Serve possono soddisfare l'auth della Control UI/WebSocket (verificati tramite `tailscale whois`). Gli endpoint API HTTP **non** usano questa auth header Tailscale; seguono invece la \ No newline at end of file diff --git a/docs/it/plugins/sdk-migration.md b/docs/it/plugins/sdk-migration.md index f7377729e..7ed277925 100644 --- a/docs/it/plugins/sdk-migration.md +++ b/docs/it/plugins/sdk-migration.md @@ -3,79 +3,81 @@ read_when: - Vedi l'avviso OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED - Vedi l'avviso OPENCLAW_EXTENSION_API_DEPRECATED - Stai aggiornando un plugin alla moderna architettura dei plugin - - Mantieni un plugin OpenClaw esterno + - Mantieni un plugin esterno di OpenClaw sidebarTitle: Migrate to SDK -summary: Migra dal layer legacy di retrocompatibilità al moderno Plugin SDK +summary: Migra dal livello legacy di retrocompatibilità al moderno Plugin SDK title: Migrazione del Plugin SDK x-i18n: - generated_at: "2026-04-06T03:10:03Z" + generated_at: "2026-04-06T08:16:01Z" model: gpt-5.4 provider: openai - source_hash: b71ce69b30c3bb02da1b263b1d11dc3214deae5f6fc708515e23b5a1c7bb7c8f + source_hash: 94f12d1376edd8184714cc4dbea4a88fa8ed652f65e9365ede6176f3bf441b33 source_path: plugins/sdk-migration.md workflow: 15 --- # Migrazione del Plugin SDK -OpenClaw è passato da un ampio layer di retrocompatibilità a una moderna -architettura dei plugin con importazioni mirate e documentate. Se il tuo plugin è stato creato prima -della nuova architettura, questa guida ti aiuta a migrare. +OpenClaw è passato da un ampio livello di retrocompatibilità a una moderna +architettura dei plugin con importazioni mirate e documentate. Se il tuo plugin +è stato creato prima della nuova architettura, questa guida ti aiuterà nella +migrazione. ## Cosa sta cambiando -Il vecchio sistema di plugin forniva due superfici molto ampie che permettevano ai plugin di importare -qualsiasi cosa servisse da un unico punto di ingresso: +Il vecchio sistema dei plugin forniva due superfici molto ampie che permettevano +ai plugin di importare tutto ciò di cui avevano bisogno da un unico punto di accesso: -- **`openclaw/plugin-sdk/compat`** — una singola importazione che riesportava decine di - helper. È stata introdotta per mantenere funzionanti i vecchi plugin basati su hook mentre la - nuova architettura dei plugin veniva costruita. -- **`openclaw/extension-api`** — un bridge che dava ai plugin accesso diretto agli - helper lato host come l'embedded agent runner. +- **`openclaw/plugin-sdk/compat`** — una singola importazione che riesportava + decine di helper. È stata introdotta per mantenere funzionanti i vecchi + plugin basati su hook mentre veniva sviluppata la nuova architettura dei plugin. +- **`openclaw/extension-api`** — un bridge che forniva ai plugin accesso diretto + agli helper lato host, come l'embedded agent runner. -Entrambe le superfici sono ora **deprecate**. Funzionano ancora a runtime, ma i nuovi -plugin non devono usarle e i plugin esistenti dovrebbero migrare prima che la prossima -major release le rimuova. +Entrambe le superfici sono ora **deprecate**. Continuano a funzionare a runtime, +ma i nuovi plugin non devono usarle e i plugin esistenti dovrebbero migrare prima +che la prossima major release le rimuova. - Il layer di retrocompatibilità verrà rimosso in una futura major release. - I plugin che continuano a importare da queste superfici smetteranno di funzionare quando ciò accadrà. + Il livello di retrocompatibilità verrà rimosso in una futura major release. + I plugin che importano ancora da queste superfici smetteranno di funzionare quando ciò accadrà. -## Perché questo è cambiato +## Perché è cambiato Il vecchio approccio causava problemi: - **Avvio lento** — importare un helper caricava decine di moduli non correlati - **Dipendenze circolari** — le riesportazioni ampie rendevano facile creare cicli di importazione -- **Superficie API poco chiara** — non c'era modo di capire quali esportazioni fossero stabili rispetto a quelle interne +- **Superficie API poco chiara** — non c'era modo di capire quali export fossero stabili e quali interni Il moderno Plugin SDK risolve questo problema: ogni percorso di importazione (`openclaw/plugin-sdk/\`) è un modulo piccolo e autosufficiente con uno scopo chiaro e un contratto documentato. -Sono state rimosse anche le vecchie superfici di comodo dei provider per i canali bundled. Le importazioni +Anche le vecchie convenience seam dei provider per i canali bundled non esistono più. Importazioni come `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, -superfici helper con marchio del canale e +le helper seam con branding del canale e `openclaw/plugin-sdk/telegram-core` erano scorciatoie private del mono-repo, non -contratti plugin stabili. Usa invece sottopercorsi SDK generici e stretti. All'interno del -workspace dei plugin bundled, mantieni gli helper di proprietà del provider nel proprio -`api.ts` o `runtime-api.ts` di quel plugin. +contratti stabili per i plugin. Usa invece i sotto-percorsi SDK generici e mirati. All'interno del +workspace dei plugin bundled, mantieni gli helper di proprietà del provider nel file +`api.ts` o `runtime-api.ts` del plugin stesso. Esempi attuali di provider bundled: -- Anthropic mantiene gli helper di stream specifici di Claude nella propria superficie `api.ts` / +- Anthropic mantiene gli helper di stream specifici per Claude nel proprio `api.ts` / `contract-api.ts` -- OpenAI mantiene builder provider, helper per i modelli predefiniti e builder di provider - realtime nel proprio `api.ts` -- OpenRouter mantiene nel proprio `api.ts` il builder del provider e gli helper di onboarding/configurazione +- OpenAI mantiene builder dei provider, helper per i modelli predefiniti e builder del provider realtime + nel proprio `api.ts` +- OpenRouter mantiene il builder del provider e gli helper di onboarding/config nel proprio + `api.ts` ## Come migrare Se il tuo plugin usa `openclaw/plugin-sdk/windows-spawn`, i wrapper Windows - `.cmd`/`.bat` non risolti ora falliscono in modalità fail-closed a meno che tu non passi esplicitamente + `.cmd`/`.bat` non risolti ora falliscono in modo chiuso, a meno che tu non passi esplicitamente `allowShellFallback: true`. ```typescript @@ -92,7 +94,7 @@ Esempi attuali di provider bundled: ``` Se il tuo chiamante non dipende intenzionalmente dal fallback della shell, non impostare - `allowShellFallback` e gestisci invece l'errore lanciato. + `allowShellFallback` e gestisci invece l'errore sollevato. @@ -107,7 +109,7 @@ Esempi attuali di provider bundled: - Ogni esportazione della vecchia superficie corrisponde a uno specifico percorso di importazione moderno: + Ogni export dalla vecchia superficie corrisponde a uno specifico percorso di importazione moderno: ```typescript // Before (deprecated backwards-compatibility layer) @@ -145,11 +147,11 @@ Esempi attuali di provider bundled: | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` | | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` | | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` | - | helper dell'archivio sessioni | `api.runtime.agent.session.*` | + | helper del session store | `api.runtime.agent.session.*` | - + ```bash pnpm build pnpm test -- my-plugin/ @@ -160,158 +162,166 @@ Esempi attuali di provider bundled: ## Riferimento dei percorsi di importazione - | Percorso di importazione | Scopo | Esportazioni principali | + | Percorso di importazione | Scopo | Export chiave | | --- | --- | --- | - | `plugin-sdk/plugin-entry` | Helper canonico del punto di ingresso plugin | `definePluginEntry` | - | `plugin-sdk/core` | Riesportazione legacy ombrello per definizioni/builder di entry dei canali | `defineChannelPluginEntry`, `createChatChannelPlugin` | - | `plugin-sdk/config-schema` | Esportazione dello schema di configurazione root | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | Helper di entry per singolo provider | `defineSingleProviderPluginEntry` | - | `plugin-sdk/channel-core` | Definizioni e builder focalizzati per le entry dei canali | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | Helper condivisi del wizard di setup | Prompt di allowlist, builder dello stato di setup | - | `plugin-sdk/setup-runtime` | Helper runtime per il setup | Adattatori di patch setup import-safe, helper per note di lookup, `promptResolvedAllowFrom`, `splitSetupEntries`, proxy di setup delegati | - | `plugin-sdk/setup-adapter-runtime` | Helper per l'adattatore di setup | `createEnvPatchedAccountSetupAdapter` | - | `plugin-sdk/setup-tools` | Helper degli strumenti di setup | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Helper multi-account | Helper per elenco account/config/action-gate | - | `plugin-sdk/account-id` | Helper per l'ID account | `DEFAULT_ACCOUNT_ID`, normalizzazione dell'ID account | - | `plugin-sdk/account-resolution` | Helper per la lookup degli account | Helper di lookup account + fallback predefinito | - | `plugin-sdk/account-helpers` | Helper ristretti per gli account | Helper per elenco account/azioni account | - | `plugin-sdk/channel-setup` | Adattatori del wizard di setup | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, più `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/channel-pairing` | Primitive di pairing DM | `createChannelPairingController` | + | `plugin-sdk/plugin-entry` | Helper canonico per l'entry del plugin | `definePluginEntry` | + | `plugin-sdk/core` | Riesportazione legacy ombrello per definizioni/builder dell'entry del canale | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/config-schema` | Export dello schema di configurazione root | `OpenClawSchema` | + | `plugin-sdk/provider-entry` | Helper di entry per provider singolo | `defineSingleProviderPluginEntry` | + | `plugin-sdk/channel-core` | Definizioni e builder mirati per l'entry del canale | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | + | `plugin-sdk/setup` | Helper condivisi della procedura guidata di setup | Prompt allowlist, builder dello stato di setup | + | `plugin-sdk/setup-runtime` | Helper runtime per il setup | Adattatori patch di setup sicuri per l'importazione, helper per note di lookup, `promptResolvedAllowFrom`, `splitSetupEntries`, proxy di setup delegati | + | `plugin-sdk/setup-adapter-runtime` | Helper per gli adattatori di setup | `createEnvPatchedAccountSetupAdapter` | + | `plugin-sdk/setup-tools` | Helper di tooling per il setup | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | + | `plugin-sdk/account-core` | Helper multi-account | Helper per elenco/configurazione/azione-gate degli account | + | `plugin-sdk/account-id` | Helper per account-id | `DEFAULT_ACCOUNT_ID`, normalizzazione di account-id | + | `plugin-sdk/account-resolution` | Helper per la ricerca degli account | Helper per ricerca account + fallback predefinito | + | `plugin-sdk/account-helpers` | Helper mirati per gli account | Helper per elenco account/azioni account | + | `plugin-sdk/channel-setup` | Adattatori della procedura guidata di setup | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, più `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | + | `plugin-sdk/channel-pairing` | Primitive di abbinamento DM | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | Wiring di prefisso risposta + digitazione | `createChannelReplyPipeline` | - | `plugin-sdk/channel-config-helpers` | Factory di adattatori config | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Builder di schema config | Tipi di schema della configurazione del canale | - | `plugin-sdk/telegram-command-config` | Helper della configurazione dei comandi Telegram | Normalizzazione del nome del comando, trim della descrizione, validazione di duplicati/conflitti | + | `plugin-sdk/channel-config-helpers` | Factory degli adattatori di configurazione | `createHybridChannelConfigAdapter` | + | `plugin-sdk/channel-config-schema` | Builder dello schema di configurazione | Tipi di schema di configurazione del canale | + | `plugin-sdk/telegram-command-config` | Helper di configurazione dei comandi Telegram | Normalizzazione dei nomi dei comandi, trimming delle descrizioni, validazione di duplicati/conflitti | | `plugin-sdk/channel-policy` | Risoluzione delle policy gruppo/DM | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | Tracciamento dello stato dell'account | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Helper per l'envelope inbound | Helper condivisi per route + builder dell'envelope | - | `plugin-sdk/inbound-reply-dispatch` | Helper per le risposte inbound | Helper condivisi per record-and-dispatch | - | `plugin-sdk/messaging-targets` | Parsing dei target di messaggistica | Helper per parsing/matching dei target | - | `plugin-sdk/outbound-media` | Helper per i media outbound | Caricamento condiviso dei media outbound | - | `plugin-sdk/outbound-runtime` | Helper runtime outbound | Helper delegati per identità/send outbound | - | `plugin-sdk/thread-bindings-runtime` | Helper per i thread binding | Lifecycle dei thread binding e helper degli adattatori | - | `plugin-sdk/agent-media-payload` | Helper legacy per il payload media | Builder del payload media agente per layout di campi legacy | - | `plugin-sdk/channel-runtime` | Shim di compatibilità deprecato | Solo utility runtime legacy del canale | - | `plugin-sdk/channel-send-result` | Tipi del risultato di invio | Tipi del risultato della risposta | + | `plugin-sdk/channel-lifecycle` | Tracciamento dello stato degli account | `createAccountStatusSink` | + | `plugin-sdk/inbound-envelope` | Helper per inbound envelope | Helper condivisi di route + builder di envelope | + | `plugin-sdk/inbound-reply-dispatch` | Helper per le risposte in ingresso | Helper condivisi di registrazione e dispatch | + | `plugin-sdk/messaging-targets` | Parsing dei target di messaggistica | Helper per parsing/corrispondenza dei target | + | `plugin-sdk/outbound-media` | Helper per media in uscita | Caricamento condiviso dei media in uscita | + | `plugin-sdk/outbound-runtime` | Helper runtime in uscita | Helper per identità in uscita/delegati di invio | + | `plugin-sdk/thread-bindings-runtime` | Helper per thread-binding | Ciclo di vita dei thread-binding e helper degli adattatori | + | `plugin-sdk/agent-media-payload` | Helper legacy per media payload | Builder del media payload dell'agente per layout legacy dei campi | + | `plugin-sdk/channel-runtime` | Shim di compatibilità deprecato | Solo utility legacy del runtime del canale | + | `plugin-sdk/channel-send-result` | Tipi di risultato dell'invio | Tipi di risultato della risposta | | `plugin-sdk/runtime-store` | Storage persistente del plugin | `createPluginRuntimeStore` | | `plugin-sdk/runtime` | Helper runtime ampi | Helper per runtime/logging/backup/installazione plugin | - | `plugin-sdk/runtime-env` | Helper ristretti dell'ambiente runtime | Logger/runtime env, helper per timeout, retry e backoff | - | `plugin-sdk/plugin-runtime` | Helper runtime condivisi del plugin | Helper per comandi/hook/http/interattivi del plugin | - | `plugin-sdk/hook-runtime` | Helper della pipeline hook | Helper condivisi per pipeline di webhook/hook interni | + | `plugin-sdk/runtime-env` | Helper mirati per runtime env | Helper per logger/runtime env, timeout, retry e backoff | + | `plugin-sdk/plugin-runtime` | Helper runtime condivisi del plugin | Helper per comandi/hook/http/interattività del plugin | + | `plugin-sdk/hook-runtime` | Helper della pipeline di hook | Helper condivisi della pipeline di webhook/internal hook | | `plugin-sdk/lazy-runtime` | Helper runtime lazy | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Helper di processo | Helper exec condivisi | - | `plugin-sdk/cli-runtime` | Helper runtime CLI | Formattazione dei comandi, attese, helper di versione | - | `plugin-sdk/gateway-runtime` | Helper del gateway | Client gateway e helper di patch dello stato dei canali | + | `plugin-sdk/process-runtime` | Helper di processo | Helper condivisi di exec | + | `plugin-sdk/cli-runtime` | Helper runtime della CLI | Formattazione dei comandi, attese, helper per la versione | + | `plugin-sdk/gateway-runtime` | Helper del gateway | Client del gateway e helper patch dello stato dei canali | | `plugin-sdk/config-runtime` | Helper di configurazione | Helper di caricamento/scrittura della configurazione | - | `plugin-sdk/telegram-command-config` | Helper dei comandi Telegram | Helper di validazione dei comandi Telegram con fallback stabile quando la superficie contrattuale Telegram bundled non è disponibile | - | `plugin-sdk/approval-runtime` | Helper per i prompt di approvazione | Payload di approvazione exec/plugin, helper di capability/profilo di approvazione, helper runtime/instradamento di approvazione nativa | - | `plugin-sdk/approval-auth-runtime` | Helper auth delle approvazioni | Risoluzione dell'approvatore, auth per azione nella stessa chat | - | `plugin-sdk/approval-client-runtime` | Helper client delle approvazioni | Helper nativi di profilo/filtro per approvazione exec | - | `plugin-sdk/approval-delivery-runtime` | Helper delivery delle approvazioni | Adattatori di capability/delivery per approvazione nativa | - | `plugin-sdk/approval-native-runtime` | Helper per il target di approvazione | Helper di binding target/account per approvazione nativa | - | `plugin-sdk/approval-reply-runtime` | Helper per le risposte di approvazione | Helper di payload di risposta per approvazione exec/plugin | - | `plugin-sdk/security-runtime` | Helper di sicurezza | Helper condivisi per trust, controllo DM, contenuti esterni e raccolta dei segreti | - | `plugin-sdk/ssrf-policy` | Helper della policy SSRF | Helper di allowlist host e policy di rete privata | - | `plugin-sdk/ssrf-runtime` | Helper runtime SSRF | Pinned-dispatcher, fetch protetto, helper di policy SSRF | - | `plugin-sdk/collection-runtime` | Helper di cache limitata | `pruneMapToMaxSize` | - | `plugin-sdk/diagnostic-runtime` | Helper di gating diagnostico | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | - | `plugin-sdk/error-runtime` | Helper di formattazione degli errori | `formatUncaughtError`, `isApprovalNotFoundError`, helper del grafo degli errori | - | `plugin-sdk/fetch-runtime` | Helper di fetch/proxy incapsulati | `resolveFetch`, helper proxy | + | `plugin-sdk/telegram-command-config` | Helper per comandi Telegram | Helper di validazione dei comandi Telegram con fallback stabile quando la superficie contrattuale del Telegram bundled non è disponibile | + | `plugin-sdk/approval-runtime` | Helper per prompt di approvazione | Payload di approvazione exec/plugin, helper per capability/profilo di approvazione, helper nativi di routing/runtime dell'approvazione | + | `plugin-sdk/approval-auth-runtime` | Helper auth per approvazione | Risoluzione degli approvatori, auth di azione nella stessa chat | + | `plugin-sdk/approval-client-runtime` | Helper client per approvazione | Helper per profilo/filtro di approvazione nativa di exec | + | `plugin-sdk/approval-delivery-runtime` | Helper di delivery per approvazione | Adattatori nativi di capability/delivery dell'approvazione | + | `plugin-sdk/approval-native-runtime` | Helper target per approvazione | Helper nativi per target/account binding dell'approvazione | + | `plugin-sdk/approval-reply-runtime` | Helper per risposte di approvazione | Helper per payload di risposta di approvazione exec/plugin | + | `plugin-sdk/security-runtime` | Helper di sicurezza | Helper condivisi per trust, gating DM, contenuti esterni e raccolta dei segreti | + | `plugin-sdk/ssrf-policy` | Helper per policy SSRF | Helper per allowlist host e policy di rete privata | + | `plugin-sdk/ssrf-runtime` | Helper runtime SSRF | Pinned-dispatcher, fetch protetto, helper per policy SSRF | + | `plugin-sdk/collection-runtime` | Helper per cache bounded | `pruneMapToMaxSize` | + | `plugin-sdk/diagnostic-runtime` | Helper per gating diagnostico | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | + | `plugin-sdk/error-runtime` | Helper di formattazione degli errori | `formatUncaughtError`, `isApprovalNotFoundError`, helper per grafi di errore | + | `plugin-sdk/fetch-runtime` | Helper per fetch/proxy wrapped | `resolveFetch`, helper proxy | | `plugin-sdk/host-runtime` | Helper di normalizzazione host | `normalizeHostname`, `normalizeScpRemoteHost` | | `plugin-sdk/retry-runtime` | Helper di retry | `RetryConfig`, `retryAsync`, esecutori di policy | - | `plugin-sdk/allow-from` | Formattazione della allowlist | `formatAllowFromLowercase` | - | `plugin-sdk/allowlist-resolution` | Mappatura dell'input della allowlist | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | Gating dei comandi e helper della superficie dei comandi | `resolveControlCommandGate`, helper di autorizzazione del mittente, helper del registro comandi | - | `plugin-sdk/secret-input` | Parsing dell'input dei segreti | Helper per l'input dei segreti | - | `plugin-sdk/webhook-ingress` | Helper per richieste webhook | Utility per i target webhook | - | `plugin-sdk/webhook-request-guards` | Helper delle guardie per il body del webhook | Helper per lettura/limite del body della richiesta | - | `plugin-sdk/reply-runtime` | Runtime condiviso della risposta | Dispatch inbound, heartbeat, pianificatore di risposte, chunking | - | `plugin-sdk/reply-dispatch-runtime` | Helper ristretti per il dispatch delle risposte | Helper di finalize + provider dispatch | - | `plugin-sdk/reply-history` | Helper della cronologia delle risposte | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | - | `plugin-sdk/reply-reference` | Pianificazione del riferimento della risposta | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Helper dei chunk di risposta | Helper di chunking del testo/markdown | - | `plugin-sdk/session-store-runtime` | Helper dell'archivio sessioni | Helper per percorso dell'archivio + updated-at | - | `plugin-sdk/state-paths` | Helper dei percorsi di stato | Helper per directory di stato e OAuth | - | `plugin-sdk/routing` | Helper di routing/chiave di sessione | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, helper di normalizzazione della chiave di sessione | - | `plugin-sdk/status-helpers` | Helper dello stato del canale | Builder del riepilogo di stato canale/account, valori predefiniti dello stato runtime, helper per i metadati dei problemi | - | `plugin-sdk/target-resolver-runtime` | Helper del risolutore del target | Helper condivisi del risolutore del target | - | `plugin-sdk/string-normalization-runtime` | Helper di normalizzazione delle stringhe | Helper per normalizzazione di slug/stringhe | - | `plugin-sdk/request-url` | Helper per URL della richiesta | Estrai URL stringa da input simili a request | + | `plugin-sdk/allow-from` | Formattazione allowlist | `formatAllowFromLowercase` | + | `plugin-sdk/allowlist-resolution` | Mappatura input dell'allowlist | `mapAllowlistResolutionInputs` | + | `plugin-sdk/command-auth` | Gating dei comandi e helper per la superficie dei comandi | `resolveControlCommandGate`, helper di autorizzazione del mittente, helper del registro comandi | + | `plugin-sdk/secret-input` | Parsing dell'input segreto | Helper per input segreti | + | `plugin-sdk/webhook-ingress` | Helper per richieste webhook | Utility per target webhook | + | `plugin-sdk/webhook-request-guards` | Helper guard per il body dei webhook | Helper per lettura/limite del body della richiesta | + | `plugin-sdk/reply-runtime` | Runtime condiviso delle risposte | Dispatch in ingresso, heartbeat, pianificatore delle risposte, chunking | + | `plugin-sdk/reply-dispatch-runtime` | Helper mirati per dispatch delle risposte | Helper per finalize + dispatch del provider | + | `plugin-sdk/reply-history` | Helper per reply-history | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/reply-reference` | Pianificazione dei riferimenti di risposta | `createReplyReferencePlanner` | + | `plugin-sdk/reply-chunking` | Helper per chunk delle risposte | Helper per chunking di testo/markdown | + | `plugin-sdk/session-store-runtime` | Helper per session store | Helper per percorso dello store + updated-at | + | `plugin-sdk/state-paths` | Helper per i percorsi di stato | Helper per directory di stato e OAuth | + | `plugin-sdk/routing` | Helper per routing/session-key | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, helper di normalizzazione session-key | + | `plugin-sdk/status-helpers` | Helper per stato del canale | Builder di riepilogo dello stato canale/account, valori predefiniti dello stato runtime, helper per metadati dei problemi | + | `plugin-sdk/target-resolver-runtime` | Helper per target resolver | Helper condivisi per target resolver | + | `plugin-sdk/string-normalization-runtime` | Helper per normalizzazione delle stringhe | Helper per normalizzazione di slug/stringhe | + | `plugin-sdk/request-url` | Helper per URL della richiesta | Estrae URL stringa da input simili a richieste | | `plugin-sdk/run-command` | Helper per comandi temporizzati | Runner di comandi temporizzati con stdout/stderr normalizzati | - | `plugin-sdk/param-readers` | Lettori di parametri | Lettori comuni di parametri tool/CLI | - | `plugin-sdk/tool-send` | Estrazione del send del tool | Estrai campi target di invio canonici dagli argomenti del tool | - | `plugin-sdk/temp-path` | Helper per i percorsi temporanei | Helper condivisi per i percorsi di download temporaneo | - | `plugin-sdk/logging-core` | Helper di logging | Logger del sottosistema e helper di redazione | - | `plugin-sdk/markdown-table-runtime` | Helper per tabelle Markdown | Helper per la modalità tabelle Markdown | - | `plugin-sdk/reply-payload` | Tipi della risposta del messaggio | Tipi del payload della risposta | - | `plugin-sdk/provider-setup` | Helper curati di setup del provider locale/self-hosted | Helper di discovery/configurazione del provider self-hosted | - | `plugin-sdk/self-hosted-provider-setup` | Helper focalizzati di setup del provider self-hosted compatibile con OpenAI | Gli stessi helper di discovery/configurazione del provider self-hosted | - | `plugin-sdk/provider-auth-runtime` | Helper runtime auth del provider | Helper runtime per la risoluzione della chiave API | - | `plugin-sdk/provider-auth-api-key` | Helper di setup della chiave API del provider | Helper di onboarding/scrittura profilo per chiave API | - | `plugin-sdk/provider-auth-result` | Helper del risultato auth del provider | Builder standard del risultato auth OAuth | - | `plugin-sdk/provider-auth-login` | Helper di login interattivo del provider | Helper condivisi di login interattivo | - | `plugin-sdk/provider-env-vars` | Helper per env var del provider | Helper di lookup delle env var auth del provider | - | `plugin-sdk/provider-model-shared` | Helper condivisi per modello/replay del provider | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builder condivisi della policy di replay, helper degli endpoint del provider e helper di normalizzazione dell'ID del modello | - | `plugin-sdk/provider-catalog-shared` | Helper condivisi per il catalogo del provider | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/param-readers` | Lettori di parametri | Lettori comuni di parametri di tool/CLI | + | `plugin-sdk/tool-send` | Estrazione dell'invio del tool | Estrae i campi target di invio canonici dagli argomenti del tool | + | `plugin-sdk/temp-path` | Helper per percorsi temporanei | Helper condivisi per percorsi temporanei di download | + | `plugin-sdk/logging-core` | Helper di logging | Logger di sottosistema e helper di redazione | + | `plugin-sdk/markdown-table-runtime` | Helper per markdown table | Helper per modalità markdown table | + | `plugin-sdk/reply-payload` | Tipi di risposta del messaggio | Tipi di payload della risposta | + | `plugin-sdk/provider-setup` | Helper curati per setup di provider locali/self-hosted | Helper per scoperta/configurazione di provider self-hosted | + | `plugin-sdk/self-hosted-provider-setup` | Helper mirati per setup di provider self-hosted compatibili con OpenAI | Gli stessi helper per scoperta/configurazione di provider self-hosted | + | `plugin-sdk/provider-auth-runtime` | Helper auth runtime del provider | Helper runtime per risoluzione delle API key | + | `plugin-sdk/provider-auth-api-key` | Helper per setup delle API key del provider | Helper per onboarding/scrittura del profilo delle API key | + | `plugin-sdk/provider-auth-result` | Helper per auth-result del provider | Builder standard di auth-result OAuth | + | `plugin-sdk/provider-auth-login` | Helper per login interattivo del provider | Helper condivisi per login interattivo | + | `plugin-sdk/provider-env-vars` | Helper per env var del provider | Helper per lookup delle env var auth del provider | + | `plugin-sdk/provider-model-shared` | Helper condivisi per modelli/replay del provider | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builder condivisi per replay-policy, helper per endpoint del provider e normalizzazione degli id modello | + | `plugin-sdk/provider-catalog-shared` | Helper condivisi per cataloghi provider | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | | `plugin-sdk/provider-onboard` | Patch di onboarding del provider | Helper di configurazione dell'onboarding | - | `plugin-sdk/provider-http` | Helper HTTP del provider | Helper generici per capability HTTP/endpoint del provider | - | `plugin-sdk/provider-web-fetch` | Helper web-fetch del provider | Helper di registrazione/cache del provider web-fetch | - | `plugin-sdk/provider-web-search` | Helper web-search del provider | Helper di registrazione/cache/configurazione del provider web-search | - | `plugin-sdk/provider-tools` | Helper di compatibilità tool/schema del provider | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, pulizia dello schema Gemini + diagnostica, e helper di compatibilità xAI come `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-http` | Helper HTTP del provider | Helper generici per HTTP/capability degli endpoint del provider | + | `plugin-sdk/provider-web-fetch` | Helper per web-fetch del provider | Helper per registrazione/cache del provider web-fetch | + | `plugin-sdk/provider-web-search` | Helper per web-search del provider | Helper per registrazione/cache/configurazione del provider web-search | + | `plugin-sdk/provider-tools` | Helper di compatibilità tool/schema del provider | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, pulizia dello schema Gemini + diagnostica e helper di compatibilità xAI come `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | Helper di utilizzo del provider | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` e altri helper di utilizzo del provider | - | `plugin-sdk/provider-stream` | Helper wrapper degli stream del provider | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipi di wrapper degli stream, e helper wrapper condivisi per Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/keyed-async-queue` | Coda asincrona ordinata | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | Helper media condivisi | Helper di fetch/transform/store dei media più builder del payload media | - | `plugin-sdk/media-understanding` | Helper di media-understanding | Tipi del provider di media understanding più esportazioni helper lato provider per immagini/audio | - | `plugin-sdk/text-runtime` | Helper testuali condivisi | Rimozione del testo visibile all'assistant, helper di render/chunking/tabella markdown, helper di redazione, helper di directive-tag, utility di testo sicuro e helper correlati di testo/logging | - | `plugin-sdk/text-chunking` | Helper di chunking del testo | Helper di chunking del testo outbound | - | `plugin-sdk/speech` | Helper speech | Tipi del provider speech più helper lato provider per direttive, registro e validazione | - | `plugin-sdk/speech-core` | Core speech condiviso | Tipi del provider speech, registro, direttive, normalizzazione | - | `plugin-sdk/realtime-transcription` | Helper per trascrizione realtime | Tipi del provider e helper del registro | - | `plugin-sdk/realtime-voice` | Helper per voce realtime | Tipi del provider e helper del registro | - | `plugin-sdk/image-generation-core` | Core condiviso per generazione immagini | Tipi per generazione immagini, failover, auth e helper del registro | - | `plugin-sdk/music-generation` | Helper per generazione musicale | Tipi provider/richiesta/risultato per generazione musicale | - | `plugin-sdk/music-generation-core` | Core condiviso per generazione musicale | Tipi per generazione musicale, helper di failover, lookup provider e parsing dei riferimenti modello | - | `plugin-sdk/video-generation` | Helper per generazione video | Tipi provider/richiesta/risultato per generazione video | - | `plugin-sdk/video-generation-core` | Core condiviso per generazione video | Tipi per generazione video, helper di failover, lookup provider e parsing dei riferimenti modello | - | `plugin-sdk/interactive-runtime` | Helper di risposta interattiva | Normalizzazione/riduzione del payload di risposta interattiva | - | `plugin-sdk/channel-config-primitives` | Primitive della configurazione del canale | Primitive ristrette dello schema config del canale | + | `plugin-sdk/provider-stream` | Helper wrapper degli stream del provider | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipi di stream wrapper e helper wrapper condivisi per Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/keyed-async-queue` | Coda async ordinata | `KeyedAsyncQueue` | + | `plugin-sdk/media-runtime` | Helper media condivisi | Helper per fetch/trasformazione/storage dei media più builder di media payload | + | `plugin-sdk/media-generation-runtime` | Helper condivisi per media-generation | Helper condivisi per failover, selezione dei candidati e messaggi di modello mancante per generazione di immagini/video/musica | + | `plugin-sdk/media-understanding` | Helper per media-understanding | Tipi di provider media-understanding più export di helper immagine/audio lato provider | + | `plugin-sdk/text-runtime` | Helper di testo condivisi | Rimozione del testo visibile all'assistente, helper di rendering/chunking/tabelle markdown, helper di redazione, helper directive-tag, utility di testo sicuro e relativi helper di testo/logging | + | `plugin-sdk/text-chunking` | Helper per chunking del testo | Helper per chunking del testo in uscita | + | `plugin-sdk/speech` | Helper speech | Tipi di provider speech più export di helper lato provider per direttive, registry e validazione | + | `plugin-sdk/speech-core` | Core speech condiviso | Tipi di provider speech, registry, direttive, normalizzazione | + | `plugin-sdk/realtime-transcription` | Helper per trascrizione realtime | Tipi di provider e helper del registry | + | `plugin-sdk/realtime-voice` | Helper per voce realtime | Tipi di provider e helper del registry | + | `plugin-sdk/image-generation-core` | Core condiviso per image-generation | Tipi, failover, auth e helper del registry per image-generation | + | `plugin-sdk/music-generation` | Helper per music-generation | Tipi di provider/richiesta/risultato per music-generation | + | `plugin-sdk/music-generation-core` | Core condiviso per music-generation | Tipi di music-generation, helper di failover, lookup dei provider e parsing di model-ref | + | `plugin-sdk/video-generation` | Helper per video-generation | Tipi di provider/richiesta/risultato per video-generation | + | `plugin-sdk/video-generation-core` | Core condiviso per video-generation | Tipi di video-generation, helper di failover, lookup dei provider e parsing di model-ref | + | `plugin-sdk/interactive-runtime` | Helper per risposte interattive | Normalizzazione/riduzione del payload delle risposte interattive | + | `plugin-sdk/channel-config-primitives` | Primitive di configurazione del canale | Primitive mirate dello schema di configurazione del canale | | `plugin-sdk/channel-config-writes` | Helper di scrittura della configurazione del canale | Helper di autorizzazione per la scrittura della configurazione del canale | - | `plugin-sdk/channel-plugin-common` | Prelude condivisa del canale | Esportazioni della prelude condivisa del plugin canale | - | `plugin-sdk/channel-status` | Helper dello stato del canale | Helper condivisi per snapshot/riepilogo dello stato del canale | - | `plugin-sdk/allowlist-config-edit` | Helper della configurazione allowlist | Helper per modifica/lettura della configurazione allowlist | - | `plugin-sdk/group-access` | Helper di accesso al gruppo | Helper condivisi per le decisioni di accesso al gruppo | - | `plugin-sdk/direct-dm` | Helper direct-DM | Helper condivisi per auth/guard dei direct-DM | + | `plugin-sdk/channel-plugin-common` | Prelude condiviso del canale | Export condivisi del preludio del plugin del canale | + | `plugin-sdk/channel-status` | Helper per stato del canale | Helper condivisi per snapshot/riepilogo dello stato del canale | + | `plugin-sdk/allowlist-config-edit` | Helper di configurazione dell'allowlist | Helper per modifica/lettura della configurazione dell'allowlist | + | `plugin-sdk/group-access` | Helper per accesso ai gruppi | Helper condivisi per decisioni di accesso ai gruppi | + | `plugin-sdk/direct-dm` | Helper per direct-DM | Helper condivisi per auth/guard di direct-DM | | `plugin-sdk/extension-shared` | Helper condivisi delle estensioni | Primitive helper per canali passivi/stato | - | `plugin-sdk/webhook-targets` | Helper per i target webhook | Registro dei target webhook e helper di installazione delle route | - | `plugin-sdk/webhook-path` | Helper del percorso webhook | Helper di normalizzazione del percorso webhook | - | `plugin-sdk/web-media` | Helper condivisi per i media web | Helper di caricamento dei media remoti/locali | - | `plugin-sdk/zod` | Riesportazione Zod | Riesportazione di `zod` per i consumatori del Plugin SDK | - | `plugin-sdk/memory-core` | Helper bundled memory-core | Superficie helper di memory manager/config/file/CLI | - | `plugin-sdk/memory-core-engine-runtime` | Facade runtime del motore memory | Facade runtime di indicizzazione/ricerca memory | - | `plugin-sdk/memory-core-host-engine-foundation` | Motore foundation host memory | Esportazioni del motore foundation host memory | - | `plugin-sdk/memory-core-host-engine-embeddings` | Motore embeddings host memory | Esportazioni del motore embeddings host memory | - | `plugin-sdk/memory-core-host-engine-qmd` | Motore QMD host memory | Esportazioni del motore QMD host memory | - | `plugin-sdk/memory-core-host-engine-storage` | Motore storage host memory | Esportazioni del motore storage host memory | - | `plugin-sdk/memory-core-host-multimodal` | Helper multimodali host memory | Helper multimodali host memory | - | `plugin-sdk/memory-core-host-query` | Helper query host memory | Helper query host memory | - | `plugin-sdk/memory-core-host-secret` | Helper secret host memory | Helper secret host memory | - | `plugin-sdk/memory-core-host-status` | Helper stato host memory | Helper stato host memory | - | `plugin-sdk/memory-core-host-runtime-cli` | Runtime CLI host memory | Helper runtime CLI host memory | - | `plugin-sdk/memory-core-host-runtime-core` | Runtime core host memory | Helper runtime core host memory | - | `plugin-sdk/memory-core-host-runtime-files` | Helper file/runtime host memory | Helper file/runtime host memory | + | `plugin-sdk/webhook-targets` | Helper per target webhook | Registry dei target webhook e helper per installazione delle route | + | `plugin-sdk/webhook-path` | Helper per percorsi webhook | Helper di normalizzazione dei percorsi webhook | + | `plugin-sdk/web-media` | Helper web media condivisi | Helper per caricamento di media remoti/locali | + | `plugin-sdk/zod` | Riesportazione di zod | Riesporta `zod` per i consumer del Plugin SDK | + | `plugin-sdk/memory-core` | Helper bundled memory-core | Superficie helper per gestore memoria/configurazione/file/CLI | + | `plugin-sdk/memory-core-engine-runtime` | Facade runtime del motore di memoria | Facade runtime per indice/ricerca della memoria | + | `plugin-sdk/memory-core-host-engine-foundation` | Motore foundation host di memoria | Export del motore foundation host di memoria | + | `plugin-sdk/memory-core-host-engine-embeddings` | Motore embedding host di memoria | Export del motore embedding host di memoria | + | `plugin-sdk/memory-core-host-engine-qmd` | Motore QMD host di memoria | Export del motore QMD host di memoria | + | `plugin-sdk/memory-core-host-engine-storage` | Motore storage host di memoria | Export del motore storage host di memoria | + | `plugin-sdk/memory-core-host-multimodal` | Helper multimodali host di memoria | Helper multimodali host di memoria | + | `plugin-sdk/memory-core-host-query` | Helper query host di memoria | Helper query host di memoria | + | `plugin-sdk/memory-core-host-secret` | Helper secret host di memoria | Helper secret host di memoria | + | `plugin-sdk/memory-core-host-events` | Helper per journal degli eventi host di memoria | Helper per journal degli eventi host di memoria | + | `plugin-sdk/memory-core-host-status` | Helper stato host di memoria | Helper stato host di memoria | + | `plugin-sdk/memory-core-host-runtime-cli` | Runtime CLI host di memoria | Helper runtime CLI host di memoria | + | `plugin-sdk/memory-core-host-runtime-core` | Runtime core host di memoria | Helper runtime core host di memoria | + | `plugin-sdk/memory-core-host-runtime-files` | Helper file/runtime host di memoria | Helper file/runtime host di memoria | + | `plugin-sdk/memory-host-core` | Alias runtime core host di memoria | Alias vendor-neutral per helper runtime core host di memoria | + | `plugin-sdk/memory-host-events` | Alias journal eventi host di memoria | Alias vendor-neutral per helper journal eventi host di memoria | + | `plugin-sdk/memory-host-files` | Alias file/runtime host di memoria | Alias vendor-neutral per helper file/runtime host di memoria | + | `plugin-sdk/memory-host-markdown` | Helper managed markdown | Helper condivisi managed-markdown per plugin adiacenti alla memoria | + | `plugin-sdk/memory-host-search` | Facade di ricerca della memoria attiva | Facade runtime lazy del gestore di ricerca della memoria attiva | + | `plugin-sdk/memory-host-status` | Alias stato host di memoria | Alias vendor-neutral per helper stato host di memoria | | `plugin-sdk/memory-lancedb` | Helper bundled memory-lancedb | Superficie helper memory-lancedb | | `plugin-sdk/testing` | Utility di test | Helper e mock di test | Questa tabella è intenzionalmente il sottoinsieme comune per la migrazione, non l'intera -superficie dell'SDK. L'elenco completo degli oltre 200 entrypoint si trova in +superficie dell'SDK. L'elenco completo di oltre 200 entrypoint si trova in `scripts/lib/plugin-sdk-entrypoints.json`. -Questo elenco include ancora alcune superfici helper dei plugin bundled come +Questo elenco include ancora alcune helper seam dei plugin bundled, come `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, -`plugin-sdk/zalo-setup` e `plugin-sdk/matrix*`. Restano esportate per -manutenzione e compatibilità dei plugin bundled, ma sono intenzionalmente -omesse dalla tabella comune di migrazione e non sono la destinazione consigliata per +`plugin-sdk/zalo-setup` e `plugin-sdk/matrix*`. Rimangono esportate per +la manutenzione e la compatibilità dei plugin bundled, ma sono intenzionalmente +omesse dalla tabella di migrazione comune e non sono il target consigliato per nuovo codice plugin. La stessa regola si applica ad altre famiglie di helper bundled come: @@ -320,7 +330,7 @@ La stessa regola si applica ad altre famiglie di helper bundled come: - Matrix: `plugin-sdk/matrix*` - LINE: `plugin-sdk/line*` - IRC: `plugin-sdk/irc*` -- superfici helper/plugin bundled come `plugin-sdk/googlechat`, +- superfici bundled helper/plugin come `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`, `plugin-sdk/mattermost*`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, @@ -329,18 +339,18 @@ La stessa regola si applica ad altre famiglie di helper bundled come: `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership` e `plugin-sdk/voice-call` -`plugin-sdk/github-copilot-token` espone attualmente la ristretta -superficie helper dei token `DEFAULT_COPILOT_API_BASE_URL`, +`plugin-sdk/github-copilot-token` espone attualmente la superficie mirata degli helper token +`DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` e `resolveCopilotApiToken`. -Usa l'importazione più stretta che corrisponde al lavoro da svolgere. Se non riesci a trovare un'esportazione, -controlla il sorgente in `src/plugin-sdk/` o chiedi su Discord. +Usa l'importazione più mirata che corrisponde al compito. Se non riesci a trovare un export, +controlla il codice sorgente in `src/plugin-sdk/` o chiedi su Discord. -## Timeline di rimozione +## Tempistiche di rimozione -| Quando | Cosa succede | -| ---------------------- | ---------------------------------------------------------------------- | -| **Adesso** | Le superfici deprecate emettono avvisi a runtime | +| Quando | Cosa succede | +| ---------------------- | ----------------------------------------------------------------------- | +| **Ora** | Le superfici deprecate emettono avvisi a runtime | | **Prossima major release** | Le superfici deprecate verranno rimosse; i plugin che le usano ancora smetteranno di funzionare | Tutti i plugin core sono già stati migrati. I plugin esterni dovrebbero migrare @@ -348,7 +358,7 @@ prima della prossima major release. ## Sopprimere temporaneamente gli avvisi -Imposta queste variabili d'ambiente mentre lavori alla migrazione: +Imposta queste variabili di ambiente mentre lavori alla migrazione: ```bash OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run @@ -360,8 +370,8 @@ Questa è una via di fuga temporanea, non una soluzione permanente. ## Correlati - [Per iniziare](/it/plugins/building-plugins) — crea il tuo primo plugin -- [Panoramica SDK](/it/plugins/sdk-overview) — riferimento completo delle importazioni per sottopercorso -- [Plugin canale](/it/plugins/sdk-channel-plugins) — creazione di plugin canale -- [Plugin provider](/it/plugins/sdk-provider-plugins) — creazione di plugin provider -- [Interni dei plugin](/it/plugins/architecture) — approfondimento sull'architettura -- [Manifesto plugin](/it/plugins/manifest) — riferimento dello schema del manifesto +- [Panoramica dell'SDK](/it/plugins/sdk-overview) — riferimento completo delle importazioni per sottopercorso +- [Plugin di canale](/it/plugins/sdk-channel-plugins) — creare plugin di canale +- [Plugin provider](/it/plugins/sdk-provider-plugins) — creare plugin provider +- [Elementi interni dei plugin](/it/plugins/architecture) — approfondimento sull'architettura +- [Manifest del plugin](/it/plugins/manifest) — riferimento dello schema del manifest diff --git a/docs/it/plugins/sdk-overview.md b/docs/it/plugins/sdk-overview.md index d46dd51d2..79586d832 100644 --- a/docs/it/plugins/sdk-overview.md +++ b/docs/it/plugins/sdk-overview.md @@ -1,30 +1,30 @@ --- read_when: - - Devi sapere da quale sottopercorso SDK importare + - Devi sapere da quale sottopercorso dell'SDK importare - Vuoi un riferimento per tutti i metodi di registrazione su OpenClawPluginApi - Stai cercando una specifica esportazione dell'SDK sidebarTitle: SDK Overview -summary: Riferimento della mappa di importazione, dell'API di registrazione e dell'architettura SDK -title: Panoramica del Plugin SDK +summary: Mappa di importazione, riferimento dell'API di registrazione e architettura dell'SDK +title: Panoramica dell'SDK plugin x-i18n: - generated_at: "2026-04-06T03:10:57Z" + generated_at: "2026-04-06T08:16:19Z" model: gpt-5.4 provider: openai - source_hash: d801641f26f39dc21490d2a69a337ff1affb147141360916b8b58a267e9f822a + source_hash: acd2887ef52c66b2f234858d812bb04197ecd0bfb3e4f7bf3622f8fdc765acad source_path: plugins/sdk-overview.md workflow: 15 --- -# Panoramica del Plugin SDK +# Panoramica dell'SDK plugin -Il plugin SDK è il contratto tipizzato tra plugin e core. Questa pagina è il -riferimento per **cosa importare** e **cosa puoi registrare**. +L'SDK plugin è il contratto tipizzato tra i plugin e il core. Questa pagina è il +riferimento per **cosa importare** e **cosa è possibile registrare**. **Cerchi una guida pratica?** - - Primo plugin? Inizia con [Getting Started](/it/plugins/building-plugins) - - Plugin canale? Vedi [Channel Plugins](/it/plugins/sdk-channel-plugins) - - Plugin provider? Vedi [Provider Plugins](/it/plugins/sdk-provider-plugins) + - Primo plugin? Inizia con [Introduzione](/it/plugins/building-plugins) + - Plugin di canale? Vedi [Plugin di canale](/it/plugins/sdk-channel-plugins) + - Plugin provider? Vedi [Plugin provider](/it/plugins/sdk-provider-plugins) ## Convenzione di importazione @@ -37,7 +37,7 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` Ogni sottopercorso è un modulo piccolo e autosufficiente. Questo mantiene -l'avvio rapido e previene problemi di dipendenze circolari. Per gli helper di +l'avvio rapido e previene i problemi di dipendenze circolari. Per gli helper di entry/build specifici del canale, preferisci `openclaw/plugin-sdk/channel-core`; mantieni `openclaw/plugin-sdk/core` per la superficie ombrello più ampia e per gli helper condivisi come `buildChannelConfigSchema`. @@ -45,26 +45,26 @@ gli helper condivisi come `buildChannelConfigSchema`. Non aggiungere né dipendere da seam di convenienza con nome del provider come `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp` o -seam helper con branding del canale. I plugin bundled dovrebbero comporre +seam di helper a marchio di canale. I plugin inclusi dovrebbero comporre sottopercorsi SDK generici all'interno dei propri barrel `api.ts` o `runtime-api.ts`, e il core dovrebbe usare quei barrel locali al plugin oppure aggiungere un contratto SDK -generico e ristretto quando l'esigenza è davvero cross-channel. +generico e ristretto quando l'esigenza è davvero trasversale ai canali. -La mappa di export generata contiene ancora un piccolo insieme di seam helper di plugin bundled -come `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, +La mappa di esportazione generata contiene ancora un piccolo insieme di +seam helper per plugin inclusi come `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` e `plugin-sdk/matrix*`. Questi -sottopercorsi esistono solo per manutenzione e compatibilità dei plugin bundled; -sono volutamente omessi dalla tabella comune qui sotto e non sono il percorso di -importazione consigliato per nuovi plugin di terze parti. +sottopercorsi esistono solo per la manutenzione e la compatibilità dei plugin inclusi; +sono intenzionalmente omessi dalla tabella comune qui sotto e non sono il +percorso di importazione consigliato per nuovi plugin di terze parti. ## Riferimento dei sottopercorsi -I sottopercorsi usati più comunemente, raggruppati per scopo. L'elenco completo generato di -oltre 200 sottopercorsi si trova in `scripts/lib/plugin-sdk-entrypoints.json`. +I sottopercorsi più comunemente usati, raggruppati per scopo. L'elenco completo +generato di oltre 200 sottopercorsi si trova in `scripts/lib/plugin-sdk-entrypoints.json`. -I sottopercorsi helper riservati ai plugin bundled compaiono ancora in questo elenco generato. -Trattali come superfici di dettaglio implementativo/compatibilità a meno che una pagina della documentazione -non ne promuova esplicitamente una come pubblica. +I sottopercorsi helper riservati per plugin inclusi compaiono ancora in +quell'elenco generato. Trattali come superfici di dettaglio implementativo/compatibilità +a meno che una pagina della documentazione non ne promuova esplicitamente uno come pubblico. ### Entry del plugin @@ -76,208 +76,216 @@ non ne promuova esplicitamente una come pubblica. | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - + | Sottopercorso | Esportazioni chiave | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/config-schema` | Export dello schema Zod radice di `openclaw.json` (`OpenClawSchema`) | - | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, più `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | Helper condivisi per setup wizard, prompt allowlist, builder dello stato di setup | + | `plugin-sdk/config-schema` | Esportazione dello schema Zod radice `openclaw.json` (`OpenClawSchema`) | + | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, oltre a `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | + | `plugin-sdk/setup` | Helper condivisi per il wizard di configurazione, prompt per allowlist, builder dello stato della configurazione | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Helper per config/action-gate multi-account, helper di fallback per account predefinito | + | `plugin-sdk/account-core` | Helper di config/action-gate multi-account e helper di fallback per account predefinito | | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helper di normalizzazione dell'ID account | - | `plugin-sdk/account-resolution` | Ricerca account + helper di fallback al predefinito | + | `plugin-sdk/account-resolution` | Helper di ricerca account + fallback predefinito | | `plugin-sdk/account-helpers` | Helper ristretti per elenco account/azioni account | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Tipi di schema config del canale | - | `plugin-sdk/telegram-command-config` | Helper di normalizzazione/validazione dei comandi personalizzati Telegram con fallback al contratto bundled | + | `plugin-sdk/channel-config-schema` | Tipi di schema della configurazione del canale | + | `plugin-sdk/telegram-command-config` | Helper di normalizzazione/validazione dei comandi personalizzati di Telegram con fallback al contratto incluso | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Helper condivisi per route inbound + builder dell'envelope | - | `plugin-sdk/inbound-reply-dispatch` | Helper condivisi per registrazione e dispatch inbound | - | `plugin-sdk/messaging-targets` | Helper per parsing/corrispondenza dei target | - | `plugin-sdk/outbound-media` | Helper condivisi per il caricamento dei media in uscita | - | `plugin-sdk/outbound-runtime` | Helper per identità/delegati di invio in uscita | - | `plugin-sdk/thread-bindings-runtime` | Helper per ciclo di vita e adapter dei thread binding | + | `plugin-sdk/inbound-envelope` | Helper condivisi di instradamento in ingresso + builder di envelope | + | `plugin-sdk/inbound-reply-dispatch` | Helper condivisi di registrazione e dispatch in ingresso | + | `plugin-sdk/messaging-targets` | Helper di parsing/corrispondenza dei target | + | `plugin-sdk/outbound-media` | Helper condivisi di caricamento dei media in uscita | + | `plugin-sdk/outbound-runtime` | Helper di delega per identità/invio in uscita | + | `plugin-sdk/thread-bindings-runtime` | Helper di lifecycle e adapter per thread-binding | | `plugin-sdk/agent-media-payload` | Builder legacy del payload media dell'agente | - | `plugin-sdk/conversation-runtime` | Helper per binding di conversazione/thread, pairing e binding configurati | - | `plugin-sdk/runtime-config-snapshot` | Helper per snapshot di config runtime | - | `plugin-sdk/runtime-group-policy` | Helper per la risoluzione della group policy runtime | + | `plugin-sdk/conversation-runtime` | Helper per binding conversazione/thread, pairing e binding configurato | + | `plugin-sdk/runtime-config-snapshot` | Helper per snapshot della config runtime | + | `plugin-sdk/runtime-group-policy` | Helper runtime per la risoluzione delle policy di gruppo | | `plugin-sdk/channel-status` | Helper condivisi per snapshot/riepilogo dello stato del canale | - | `plugin-sdk/channel-config-primitives` | Primitive ristrette di schema config del canale | - | `plugin-sdk/channel-config-writes` | Helper di autorizzazione alle scritture config del canale | - | `plugin-sdk/channel-plugin-common` | Export di preambolo condivisi per i plugin canale | - | `plugin-sdk/allowlist-config-edit` | Helper di lettura/modifica config allowlist | + | `plugin-sdk/channel-config-primitives` | Primitive ristrette per lo schema di configurazione del canale | + | `plugin-sdk/channel-config-writes` | Helper di autorizzazione per la scrittura della configurazione del canale | + | `plugin-sdk/channel-plugin-common` | Esportazioni prelude condivise del plugin di canale | + | `plugin-sdk/allowlist-config-edit` | Helper di modifica/lettura della configurazione dell'allowlist | | `plugin-sdk/group-access` | Helper condivisi per le decisioni di accesso ai gruppi | - | `plugin-sdk/direct-dm` | Helper condivisi di auth/guard per DM diretti | - | `plugin-sdk/interactive-runtime` | Helper di normalizzazione/riduzione del payload delle risposte interattive | - | `plugin-sdk/channel-inbound` | Helper per debounce, corrispondenza menzioni, envelope | + | `plugin-sdk/direct-dm` | Helper condivisi di autenticazione/protezione direct-DM | + | `plugin-sdk/interactive-runtime` | Helper di normalizzazione/riduzione del payload di risposta interattiva | + | `plugin-sdk/channel-inbound` | Debounce, corrispondenza delle menzioni, helper di envelope | | `plugin-sdk/channel-send-result` | Tipi del risultato di risposta | | `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` | - | `plugin-sdk/channel-targets` | Helper per parsing/corrispondenza dei target | + | `plugin-sdk/channel-targets` | Helper di parsing/corrispondenza dei target | | `plugin-sdk/channel-contract` | Tipi del contratto del canale | | `plugin-sdk/channel-feedback` | Wiring di feedback/reazioni | - + | Sottopercorso | Esportazioni chiave | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | Helper di setup curati per provider locali/self-hosted | - | `plugin-sdk/self-hosted-provider-setup` | Helper di setup focalizzati per provider self-hosted compatibili OpenAI | - | `plugin-sdk/provider-auth-runtime` | Helper di risoluzione runtime della chiave API per i plugin provider | + | `plugin-sdk/provider-setup` | Helper selezionati di configurazione del provider locale/self-hosted | + | `plugin-sdk/self-hosted-provider-setup` | Helper focalizzati di configurazione del provider self-hosted compatibile con OpenAI | + | `plugin-sdk/provider-auth-runtime` | Helper runtime di risoluzione della chiave API per plugin provider | | `plugin-sdk/provider-auth-api-key` | Helper di onboarding/scrittura profilo per chiavi API | - | `plugin-sdk/provider-auth-result` | Builder standard del risultato auth OAuth | - | `plugin-sdk/provider-auth-login` | Helper condivisi di login interattivo per i plugin provider | - | `plugin-sdk/provider-env-vars` | Helper di lookup delle variabili env auth dei provider | + | `plugin-sdk/provider-auth-result` | Builder standard del risultato di autenticazione OAuth | + | `plugin-sdk/provider-auth-login` | Helper condivisi di login interattivo per plugin provider | + | `plugin-sdk/provider-env-vars` | Helper di ricerca delle variabili d'ambiente di autenticazione del provider | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builder condivisi di replay-policy, helper per endpoint provider e helper di normalizzazione model-id come `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builder condivisi di replay-policy, helper per endpoint provider e helper di normalizzazione dell'ID modello come `normalizeNativeXaiModelId` | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | Helper generici di capacità HTTP/endpoint provider | - | `plugin-sdk/provider-web-fetch` | Helper di registrazione/cache per provider web-fetch | - | `plugin-sdk/provider-web-search` | Helper di registrazione/cache/config per provider web-search | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, pulizia schema Gemini + diagnostica e helper di compatibilità xAI come `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-http` | Helper generici di capacità HTTP/endpoint del provider | + | `plugin-sdk/provider-web-fetch` | Helper di registrazione/cache del provider web-fetch | + | `plugin-sdk/provider-web-search` | Helper di registrazione/cache/config del provider web-search | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, cleanup + diagnostica dello schema Gemini e helper di compatibilità xAI come `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | `fetchClaudeUsage` e simili | | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipi di stream wrapper e helper wrapper condivisi per Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-onboard` | Helper di patch config per onboarding | - | `plugin-sdk/global-singleton` | Helper per singleton/mappe/cache locali al processo | + | `plugin-sdk/provider-onboard` | Helper di patch della configurazione di onboarding | + | `plugin-sdk/global-singleton` | Helper di singleton/map/cache locali al processo | - + | Sottopercorso | Esportazioni chiave | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`, helper per registro comandi, helper di autorizzazione del mittente | - | `plugin-sdk/approval-auth-runtime` | Helper per risoluzione degli approvatori e auth delle azioni nella stessa chat | - | `plugin-sdk/approval-client-runtime` | Helper per profili/filtri di approvazione exec nativi | - | `plugin-sdk/approval-delivery-runtime` | Adapter per capacità/consegna delle approvazioni native | - | `plugin-sdk/approval-native-runtime` | Helper per target di approvazione nativa + binding account | - | `plugin-sdk/approval-reply-runtime` | Helper per payload di risposta di approvazione exec/plugin | - | `plugin-sdk/command-auth-native` | Auth dei comandi nativi + helper per target sessione nativa | - | `plugin-sdk/command-detection` | Helper condivisi di rilevamento dei comandi | - | `plugin-sdk/command-surface` | Helper per normalizzazione del corpo del comando e command-surface | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`, helper del registro comandi, helper di autorizzazione del mittente | + | `plugin-sdk/approval-auth-runtime` | Risoluzione dell'approvatore e helper di action-auth nella stessa chat | + | `plugin-sdk/approval-client-runtime` | Helper nativi per profilo/filtro di approvazione exec | + | `plugin-sdk/approval-delivery-runtime` | Adapter nativi per capacità/consegna dell'approvazione | + | `plugin-sdk/approval-native-runtime` | Helper nativi per target di approvazione + binding account | + | `plugin-sdk/approval-reply-runtime` | Helper per il payload di risposta di approvazione exec/plugin | + | `plugin-sdk/command-auth-native` | Autenticazione nativa dei comandi + helper nativi per target di sessione | + | `plugin-sdk/command-detection` | Helper condivisi per il rilevamento dei comandi | + | `plugin-sdk/command-surface` | Normalizzazione del corpo del comando e helper della superficie dei comandi | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/security-runtime` | Helper condivisi per trust, gating DM, contenuti esterni e raccolta segreti | - | `plugin-sdk/ssrf-policy` | Helper per policy SSRF con allowlist host e rete privata | + | `plugin-sdk/security-runtime` | Helper condivisi per trust, gating DM, contenuto esterno e raccolta di secret | + | `plugin-sdk/ssrf-policy` | Helper di policy SSRF per allowlist host e reti private | | `plugin-sdk/ssrf-runtime` | Helper per pinned-dispatcher, fetch protetto da SSRF e policy SSRF | - | `plugin-sdk/secret-input` | Helper per parsing dell'input segreto | - | `plugin-sdk/webhook-ingress` | Helper per richiesta/target webhook | - | `plugin-sdk/webhook-request-guards` | Helper per dimensione body richiesta/timeout | + | `plugin-sdk/secret-input` | Helper di parsing degli input secret | + | `plugin-sdk/webhook-ingress` | Helper per richieste/target webhook | + | `plugin-sdk/webhook-request-guards` | Helper per dimensione body/timeout della richiesta | | Sottopercorso | Esportazioni chiave | | --- | --- | - | `plugin-sdk/runtime` | Helper ampi per runtime/logging/backup/installazione plugin | + | `plugin-sdk/runtime` | Ampi helper di runtime/logging/backup/installazione plugin | | `plugin-sdk/runtime-env` | Helper ristretti per env runtime, logger, timeout, retry e backoff | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Helper condivisi per comando/hook/http/interattivi dei plugin | - | `plugin-sdk/hook-runtime` | Helper condivisi per la pipeline di hook webhook/interni | + | `plugin-sdk/plugin-runtime` | Helper condivisi per comandi/hook/http/interattività del plugin | + | `plugin-sdk/hook-runtime` | Helper condivisi per la pipeline di webhook/hook interni | | `plugin-sdk/lazy-runtime` | Helper di importazione/binding runtime lazy come `createLazyRuntimeModule`, `createLazyRuntimeMethod` e `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Helper di esecuzione processi | - | `plugin-sdk/cli-runtime` | Helper per formattazione CLI, attesa e versione | - | `plugin-sdk/gateway-runtime` | Helper per client gateway e patch dello stato del canale | - | `plugin-sdk/config-runtime` | Helper per caricamento/scrittura della config | - | `plugin-sdk/telegram-command-config` | Normalizzazione di nome/descrizione dei comandi Telegram e controlli di duplicati/conflitti, anche quando la superficie di contratto Telegram bundled non è disponibile | - | `plugin-sdk/approval-runtime` | Helper per approvazione exec/plugin, builder di approval-capability, helper auth/profilo, helper di routing/runtime nativi | - | `plugin-sdk/reply-runtime` | Helper condivisi per runtime inbound/risposta, chunking, dispatch, heartbeat, pianificatore delle risposte | + | `plugin-sdk/process-runtime` | Helper di esecuzione dei processi | + | `plugin-sdk/cli-runtime` | Helper CLI di formattazione, attesa e versione | + | `plugin-sdk/gateway-runtime` | Helper del client gateway e di patch dello stato del canale | + | `plugin-sdk/config-runtime` | Helper di caricamento/scrittura della configurazione | + | `plugin-sdk/telegram-command-config` | Normalizzazione di nome/descrizione del comando Telegram e controlli di duplicati/conflitti, anche quando la superficie contrattuale Telegram inclusa non è disponibile | + | `plugin-sdk/approval-runtime` | Helper di approvazione exec/plugin, builder di capacità di approvazione, helper di autenticazione/profilo, helper nativi di instradamento/runtime | + | `plugin-sdk/reply-runtime` | Helper condivisi di runtime inbound/reply, chunking, dispatch, heartbeat, pianificatore di risposte | | `plugin-sdk/reply-dispatch-runtime` | Helper ristretti per dispatch/finalizzazione della risposta | | `plugin-sdk/reply-history` | Helper condivisi per la cronologia delle risposte a breve finestra come `buildHistoryContext`, `recordPendingHistoryEntry` e `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | | `plugin-sdk/reply-chunking` | Helper ristretti per chunking di testo/markdown | - | `plugin-sdk/session-store-runtime` | Helper per percorso store sessione + updated-at | - | `plugin-sdk/state-paths` | Helper per percorsi state/OAuth dir | - | `plugin-sdk/routing` | Helper per route/session-key/account binding come `resolveAgentRoute`, `buildAgentSessionKey` e `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Helper condivisi per riepilogo stato canale/account, valori predefiniti dello stato runtime e metadati dei problemi | - | `plugin-sdk/target-resolver-runtime` | Helper condivisi per resolver dei target | + | `plugin-sdk/session-store-runtime` | Helper per percorso dello store di sessione + updated-at | + | `plugin-sdk/state-paths` | Helper di percorso per directory di stato/OAuth | + | `plugin-sdk/routing` | Helper per route/session-key/binding account come `resolveAgentRoute`, `buildAgentSessionKey` e `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Helper condivisi per il riepilogo dello stato di canale/account, valori predefiniti dello stato runtime e helper dei metadati dei problemi | + | `plugin-sdk/target-resolver-runtime` | Helper condivisi per la risoluzione dei target | | `plugin-sdk/string-normalization-runtime` | Helper di normalizzazione slug/stringhe | - | `plugin-sdk/request-url` | Estrae URL stringa da input simili a fetch/request | - | `plugin-sdk/run-command` | Runner di comandi temporizzato con risultati stdout/stderr normalizzati | - | `plugin-sdk/param-readers` | Reader comuni dei parametri tool/CLI | - | `plugin-sdk/tool-send` | Estrae campi canonicali del target di invio dagli argomenti dello strumento | + | `plugin-sdk/request-url` | Estrae URL stringa da input simili a fetch/richiesta | + | `plugin-sdk/run-command` | Runner di comandi con timing e risultati stdout/stderr normalizzati | + | `plugin-sdk/param-readers` | Lettori comuni di parametri per tool/CLI | + | `plugin-sdk/tool-send` | Estrae i campi del target di invio canonico dagli argomenti del tool | | `plugin-sdk/temp-path` | Helper condivisi per percorsi temporanei di download | - | `plugin-sdk/logging-core` | Helper per logger del sottosistema e redazione | + | `plugin-sdk/logging-core` | Helper di logger del sottosistema e redazione | | `plugin-sdk/markdown-table-runtime` | Helper per la modalità tabella Markdown | - | `plugin-sdk/json-store` | Piccoli helper di lettura/scrittura stato JSON | + | `plugin-sdk/json-store` | Piccoli helper di lettura/scrittura dello stato JSON | | `plugin-sdk/file-lock` | Helper di file-lock rientrante | - | `plugin-sdk/persistent-dedupe` | Helper per cache dedupe persistente su disco | - | `plugin-sdk/acp-runtime` | Helper per runtime/sessione ACP e reply-dispatch | - | `plugin-sdk/agent-config-primitives` | Primitive ristrette di schema config runtime dell'agente | - | `plugin-sdk/boolean-param` | Reader flessibile di parametri booleani | - | `plugin-sdk/dangerous-name-runtime` | Helper di risoluzione per matching di nomi pericolosi | + | `plugin-sdk/persistent-dedupe` | Helper di cache dedupe persistente su disco | + | `plugin-sdk/acp-runtime` | Helper di runtime/sessione ACP e reply-dispatch | + | `plugin-sdk/agent-config-primitives` | Primitive ristrette per lo schema di configurazione runtime dell'agente | + | `plugin-sdk/boolean-param` | Lettore permissivo di parametri booleani | + | `plugin-sdk/dangerous-name-runtime` | Helper di risoluzione per la corrispondenza di nomi pericolosi | | `plugin-sdk/device-bootstrap` | Helper per bootstrap del dispositivo e token di pairing | | `plugin-sdk/extension-shared` | Primitive condivise per canali passivi e helper di stato | - | `plugin-sdk/models-provider-runtime` | Helper di risposta del comando `/models`/provider | - | `plugin-sdk/skill-commands-runtime` | Helper di elenco dei comandi Skills | - | `plugin-sdk/native-command-registry` | Helper per registro/build/serializzazione dei comandi nativi | + | `plugin-sdk/models-provider-runtime` | Helper di risposta per comando `/models`/provider | + | `plugin-sdk/skill-commands-runtime` | Helper per l'elenco dei comandi di Skills | + | `plugin-sdk/native-command-registry` | Helper nativi di registro/build/serializzazione dei comandi | | `plugin-sdk/provider-zai-endpoint` | Helper di rilevamento endpoint Z.AI | - | `plugin-sdk/infra-runtime` | Helper per eventi di sistema/heartbeat | - | `plugin-sdk/collection-runtime` | Piccoli helper per cache limitate | - | `plugin-sdk/diagnostic-runtime` | Helper per flag ed eventi diagnostici | - | `plugin-sdk/error-runtime` | Grafo degli errori, formattazione, helper condivisi di classificazione errori, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Helper per fetch incapsulato, proxy e lookup fissati | - | `plugin-sdk/host-runtime` | Helper di normalizzazione per hostname e host SCP | - | `plugin-sdk/retry-runtime` | Helper per config retry e runner retry | - | `plugin-sdk/agent-runtime` | Helper per agent dir/identity/workspace | - | `plugin-sdk/directory-runtime` | Query/dedup delle directory supportata dalla config | + | `plugin-sdk/infra-runtime` | Helper di eventi di sistema/heartbeat | + | `plugin-sdk/collection-runtime` | Piccoli helper di cache limitata | + | `plugin-sdk/diagnostic-runtime` | Helper di flag ed eventi diagnostici | + | `plugin-sdk/error-runtime` | Grafo degli errori, formattazione, helper condivisi di classificazione degli errori, `isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | Helper per fetch incapsulato, proxy e ricerca pinned | + | `plugin-sdk/host-runtime` | Helper di normalizzazione hostname e host SCP | + | `plugin-sdk/retry-runtime` | Helper di configurazione retry ed esecuzione retry | + | `plugin-sdk/agent-runtime` | Helper per directory/identità/workspace dell'agente | + | `plugin-sdk/directory-runtime` | Query/dedup di directory basata su config | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | | Sottopercorso | Esportazioni chiave | | --- | --- | - | `plugin-sdk/media-runtime` | Helper condivisi per fetch/transform/store dei media più builder del payload media | - | `plugin-sdk/media-understanding` | Tipi del provider media understanding più export helper lato provider per immagini/audio | - | `plugin-sdk/text-runtime` | Helper condivisi per testo/markdown/logging come stripping del testo visibile all'assistente, helper di rendering/chunking/tabella markdown, helper di redazione, helper per tag direttiva e utility di testo sicuro | + | `plugin-sdk/media-runtime` | Helper condivisi per fetch/transform/store dei media più builder di payload media | + | `plugin-sdk/media-generation-runtime` | Helper condivisi per failover della generazione media, selezione candidati e messaggistica per modelli mancanti | + | `plugin-sdk/media-understanding` | Tipi provider per media understanding più esportazioni helper orientate al provider per immagini/audio | + | `plugin-sdk/text-runtime` | Helper condivisi per testo/markdown/logging come rimozione del testo visibile all'assistente, helper di render/chunking/tabella Markdown, helper di redazione, helper di directive-tag e utility di testo sicuro | | `plugin-sdk/text-chunking` | Helper per chunking del testo in uscita | - | `plugin-sdk/speech` | Tipi del provider speech più export helper lato provider per directive, registro e validazione | - | `plugin-sdk/speech-core` | Tipi condivisi del provider speech, helper per registro, directive e normalizzazione | - | `plugin-sdk/realtime-transcription` | Tipi del provider di trascrizione realtime e helper del registro | - | `plugin-sdk/realtime-voice` | Tipi del provider voce realtime e helper del registro | - | `plugin-sdk/image-generation` | Tipi del provider per generazione immagini | - | `plugin-sdk/image-generation-core` | Tipi condivisi di generazione immagini, helper per failover, auth e registro | - | `plugin-sdk/music-generation` | Tipi di provider/richiesta/risultato per generazione musicale | - | `plugin-sdk/music-generation-core` | Tipi condivisi di generazione musicale, helper per failover, ricerca provider e parsing model-ref | - | `plugin-sdk/video-generation` | Tipi di provider/richiesta/risultato per generazione video | - | `plugin-sdk/video-generation-core` | Tipi condivisi di generazione video, helper per failover, ricerca provider e parsing model-ref | - | `plugin-sdk/webhook-targets` | Registro dei target webhook e helper per installazione delle route | + | `plugin-sdk/speech` | Tipi provider speech più helper orientati al provider per directive, registro e validazione | + | `plugin-sdk/speech-core` | Tipi provider speech condivisi, helper di registro, directive e normalizzazione | + | `plugin-sdk/realtime-transcription` | Tipi provider di trascrizione realtime e helper di registro | + | `plugin-sdk/realtime-voice` | Tipi provider di voce realtime e helper di registro | + | `plugin-sdk/image-generation` | Tipi provider di generazione immagini | + | `plugin-sdk/image-generation-core` | Tipi condivisi di generazione immagini, helper di failover, autenticazione e registro | + | `plugin-sdk/music-generation` | Tipi provider/richiesta/risultato per generazione musicale | + | `plugin-sdk/music-generation-core` | Tipi condivisi di generazione musicale, helper di failover, ricerca provider e parsing model-ref | + | `plugin-sdk/video-generation` | Tipi provider/richiesta/risultato per generazione video | + | `plugin-sdk/video-generation-core` | Tipi condivisi di generazione video, helper di failover, ricerca provider e parsing model-ref | + | `plugin-sdk/webhook-targets` | Registro dei target webhook e helper di installazione route | | `plugin-sdk/webhook-path` | Helper di normalizzazione del percorso webhook | - | `plugin-sdk/web-media` | Helper condivisi per il caricamento di media remoti/locali | - | `plugin-sdk/zod` | `zod` riesportato per i consumer del plugin SDK | + | `plugin-sdk/web-media` | Helper condivisi di caricamento media remoti/locali | + | `plugin-sdk/zod` | `zod` riesportato per i consumatori dell'SDK plugin | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | | Sottopercorso | Esportazioni chiave | | --- | --- | - | `plugin-sdk/memory-core` | Superficie helper bundled memory-core per helper di manager/config/file/CLI | - | `plugin-sdk/memory-core-engine-runtime` | Facciata runtime per indice/ricerca memory | - | `plugin-sdk/memory-core-host-engine-foundation` | Export del motore foundation dell'host memory | - | `plugin-sdk/memory-core-host-engine-embeddings` | Export del motore embeddings dell'host memory | - | `plugin-sdk/memory-core-host-engine-qmd` | Export del motore QMD dell'host memory | - | `plugin-sdk/memory-core-host-engine-storage` | Export del motore storage dell'host memory | - | `plugin-sdk/memory-core-host-multimodal` | Helper multimodali dell'host memory | - | `plugin-sdk/memory-core-host-query` | Helper di query dell'host memory | - | `plugin-sdk/memory-core-host-secret` | Helper dei segreti dell'host memory | - | `plugin-sdk/memory-core-host-status` | Helper di stato dell'host memory | - | `plugin-sdk/memory-core-host-runtime-cli` | Helper runtime CLI dell'host memory | - | `plugin-sdk/memory-core-host-runtime-core` | Helper runtime core dell'host memory | - | `plugin-sdk/memory-core-host-runtime-files` | Helper file/runtime dell'host memory | - | `plugin-sdk/memory-lancedb` | Superficie helper bundled memory-lancedb | + | `plugin-sdk/memory-core` | Superficie helper `memory-core` inclusa per helper di manager/config/file/CLI | + | `plugin-sdk/memory-core-engine-runtime` | Facade runtime di indice/ricerca memory | + | `plugin-sdk/memory-core-host-engine-foundation` | Esportazioni del motore foundation host memory | + | `plugin-sdk/memory-core-host-engine-embeddings` | Esportazioni del motore embedding host memory | + | `plugin-sdk/memory-core-host-engine-qmd` | Esportazioni del motore QMD host memory | + | `plugin-sdk/memory-core-host-engine-storage` | Esportazioni del motore storage host memory | + | `plugin-sdk/memory-core-host-multimodal` | Helper multimodali host memory | + | `plugin-sdk/memory-core-host-query` | Helper query host memory | + | `plugin-sdk/memory-core-host-secret` | Helper secret host memory | + | `plugin-sdk/memory-core-host-events` | Helper journal degli eventi host memory | + | `plugin-sdk/memory-core-host-status` | Helper di stato host memory | + | `plugin-sdk/memory-core-host-runtime-cli` | Helper runtime CLI host memory | + | `plugin-sdk/memory-core-host-runtime-core` | Helper runtime core host memory | + | `plugin-sdk/memory-core-host-runtime-files` | Helper file/runtime host memory | + | `plugin-sdk/memory-host-core` | Alias neutrale rispetto al vendor per helper runtime core host memory | + | `plugin-sdk/memory-host-events` | Alias neutrale rispetto al vendor per helper journal degli eventi host memory | + | `plugin-sdk/memory-host-files` | Alias neutrale rispetto al vendor per helper file/runtime host memory | + | `plugin-sdk/memory-host-markdown` | Helper condivisi di markdown gestito per plugin adiacenti a memory | + | `plugin-sdk/memory-host-search` | Facade runtime della memory attiva per l'accesso al search-manager | + | `plugin-sdk/memory-host-status` | Alias neutrale rispetto al vendor per helper di stato host memory | + | `plugin-sdk/memory-lancedb` | Superficie helper `memory-lancedb` inclusa | - - | Famiglia | Sottopercorsi correnti | Utilizzo previsto | + + | Famiglia | Sottopercorsi attuali | Uso previsto | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helper di supporto del plugin browser bundled (`browser-support` resta il barrel di compatibilità) | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Superficie helper/runtime Matrix bundled | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Superficie helper/runtime LINE bundled | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Superficie helper IRC bundled | - | Helper specifici del canale | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Seam helper/compatibilità dei canali bundled | - | Helper auth/plugin-specifici | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Seam helper per funzionalità/plugin bundled; `plugin-sdk/github-copilot-token` attualmente esporta `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` e `resolveCopilotApiToken` | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helper di supporto per il plugin browser incluso (`browser-support` rimane il barrel di compatibilità) | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Superficie helper/runtime Matrix inclusa | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Superficie helper/runtime LINE inclusa | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Superficie helper IRC inclusa | + | Helper specifici del canale | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Seam di compatibilità/helper per canali inclusi | + | Helper specifici di auth/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Seam helper per funzionalità/plugin inclusi; `plugin-sdk/github-copilot-token` esporta attualmente `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` e `resolveCopilotApiToken` | @@ -290,7 +298,7 @@ metodi: | Metodo | Cosa registra | | ------------------------------------------------ | -------------------------------- | -| `api.registerProvider(...)` | Inferenza testuale (LLM) | +| `api.registerProvider(...)` | Inferenza del testo (LLM) | | `api.registerChannel(...)` | Canale di messaggistica | | `api.registerSpeechProvider(...)` | Sintesi text-to-speech / STT | | `api.registerRealtimeTranscriptionProvider(...)` | Trascrizione realtime in streaming | @@ -299,42 +307,44 @@ metodi: | `api.registerImageGenerationProvider(...)` | Generazione di immagini | | `api.registerMusicGenerationProvider(...)` | Generazione musicale | | `api.registerVideoGenerationProvider(...)` | Generazione video | -| `api.registerWebFetchProvider(...)` | Provider di web fetch / scraping | +| `api.registerWebFetchProvider(...)` | Provider di web fetch / scrape | | `api.registerWebSearchProvider(...)` | Ricerca web | -### Strumenti e comandi +### Tool e comandi -| Metodo | Cosa registra | -| ------------------------------- | --------------------------------------------- | -| `api.registerTool(tool, opts?)` | Strumento dell'agente (obbligatorio o `{ optional: true }`) | -| `api.registerCommand(def)` | Comando personalizzato (bypassa l'LLM) | +| Metodo | Cosa registra | +| ------------------------------- | -------------------------------------------- | +| `api.registerTool(tool, opts?)` | Tool dell'agente (obbligatorio o `{ optional: true }`) | +| `api.registerCommand(def)` | Comando personalizzato (bypassa l'LLM) | ### Infrastruttura -| Metodo | Cosa registra | -| ---------------------------------------------- | --------------------- | -| `api.registerHook(events, handler, opts?)` | Hook evento | -| `api.registerHttpRoute(params)` | Endpoint HTTP gateway | -| `api.registerGatewayMethod(name, handler)` | Metodo RPC gateway | -| `api.registerCli(registrar, opts?)` | Sottocomando CLI | -| `api.registerService(service)` | Servizio in background | -| `api.registerInteractiveHandler(registration)` | Gestore interattivo | +| Metodo | Cosa registra | +| ---------------------------------------------- | -------------------------------------- | +| `api.registerHook(events, handler, opts?)` | Hook di evento | +| `api.registerHttpRoute(params)` | Endpoint HTTP del gateway | +| `api.registerGatewayMethod(name, handler)` | Metodo RPC del gateway | +| `api.registerCli(registrar, opts?)` | Sottocomando CLI | +| `api.registerService(service)` | Servizio in background | +| `api.registerInteractiveHandler(registration)` | Handler interattivo | +| `api.registerMemoryPromptSupplement(builder)` | Sezione di prompt additiva adiacente a memory | +| `api.registerMemoryCorpusSupplement(adapter)` | Corpus additivo di ricerca/lettura memory | -I namespace amministrativi core riservati (`config.*`, `exec.approvals.*`, `wizard.*`, -`update.*`) rimangono sempre `operator.admin`, anche se un plugin prova ad assegnare -uno scope del metodo gateway più ristretto. Preferisci prefissi specifici del plugin per -i metodi posseduti dal plugin. +I namespace amministrativi del core riservati (`config.*`, `exec.approvals.*`, `wizard.*`, +`update.*`) restano sempre `operator.admin`, anche se un plugin prova ad assegnare +uno scope più ristretto a un metodo gateway. Preferisci prefissi specifici del plugin per +i metodi di proprietà del plugin. -### Metadati di registrazione CLI +### Metadati di registrazione della CLI `api.registerCli(registrar, opts?)` accetta due tipi di metadati di primo livello: -- `commands`: root di comando esplicite possedute dal registrar -- `descriptors`: descrittori di comando in fase di parsing usati per help della CLI root, - routing e registrazione CLI lazy del plugin +- `commands`: radici di comando esplicite possedute dal registrar +- `descriptors`: descrittori di comando in fase di parsing usati per l'help della CLI radice, + l'instradamento e la registrazione lazy della CLI del plugin -Se vuoi che un comando del plugin resti caricato lazy nel normale percorso della CLI root, -fornisci `descriptors` che coprano ogni root di comando di primo livello esposta da quel +Se vuoi che un comando del plugin resti caricato lazy nel normale percorso della CLI radice, +fornisci `descriptors` che coprano ogni radice di comando di primo livello esposta da quel registrar. ```typescript @@ -347,7 +357,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "Manage Matrix accounts, verification, devices, and profile state", + description: "Gestisci account Matrix, verifica, dispositivi e stato del profilo", hasSubcommands: true, }, ], @@ -355,66 +365,67 @@ api.registerCli( ); ``` -Usa `commands` da solo solo quando non hai bisogno della registrazione lazy della CLI root. -Quel percorso di compatibilità eager resta supportato, ma non installa -placeholder supportati da descriptor per il caricamento lazy in fase di parsing. +Usa `commands` da solo solo quando non hai bisogno della registrazione lazy della CLI radice. +Questo percorso di compatibilità eager rimane supportato, ma non installa +placeholder basati su descriptor per il caricamento lazy in fase di parsing. ### Slot esclusivi -| Metodo | Cosa registra | -| ------------------------------------------ | -------------------------------------- | +| Metodo | Cosa registra | +| ------------------------------------------ | ------------------------------------ | | `api.registerContextEngine(id, factory)` | Motore di contesto (uno attivo alla volta) | -| `api.registerMemoryPromptSection(builder)` | Builder di sezione del prompt memory | -| `api.registerMemoryFlushPlan(resolver)` | Resolver del piano di flush memory | -| `api.registerMemoryRuntime(runtime)` | Adapter runtime memory | +| `api.registerMemoryPromptSection(builder)` | Builder della sezione del prompt memory | +| `api.registerMemoryFlushPlan(resolver)` | Resolver del piano di flush memory | +| `api.registerMemoryRuntime(runtime)` | Adapter runtime memory | ### Adapter di embedding memory -| Metodo | Cosa registra | -| ---------------------------------------------- | -------------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter di embedding memory per il plugin attivo | +| Metodo | Cosa registra | +| ---------------------------------------------- | --------------------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter di embedding memory per il plugin attivo | - `registerMemoryPromptSection`, `registerMemoryFlushPlan` e `registerMemoryRuntime` sono esclusivi dei plugin memory. -- `registerMemoryEmbeddingProvider` consente al plugin memory attivo di registrare uno - o più ID di adapter embedding (per esempio `openai`, `gemini` o un ID personalizzato definito dal plugin). -- La config utente come `agents.defaults.memorySearch.provider` e - `agents.defaults.memorySearch.fallback` viene risolta rispetto a quegli ID di adapter - registrati. +- `registerMemoryEmbeddingProvider` consente al plugin memory attivo di registrare + uno o più ID di adapter di embedding (per esempio `openai`, `gemini` o un ID + personalizzato definito dal plugin). +- La configurazione utente come `agents.defaults.memorySearch.provider` e + `agents.defaults.memorySearch.fallback` viene risolta rispetto a quegli ID + di adapter registrati. -### Eventi e ciclo di vita +### Eventi e lifecycle -| Metodo | Cosa fa | -| -------------------------------------------- | --------------------------- | -| `api.on(hookName, handler, opts?)` | Hook del ciclo di vita tipizzato | +| Metodo | Cosa fa | +| -------------------------------------------- | -------------------------- | +| `api.on(hookName, handler, opts?)` | Hook lifecycle tipizzato | | `api.onConversationBindingResolved(handler)` | Callback di binding della conversazione | ### Semantica delle decisioni degli hook -- `before_tool_call`: restituire `{ block: true }` è terminale. Una volta che un gestore lo imposta, i gestori a priorità più bassa vengono saltati. -- `before_tool_call`: restituire `{ block: false }` è trattato come nessuna decisione (uguale a omettere `block`), non come override. -- `before_install`: restituire `{ block: true }` è terminale. Una volta che un gestore lo imposta, i gestori a priorità più bassa vengono saltati. -- `before_install`: restituire `{ block: false }` è trattato come nessuna decisione (uguale a omettere `block`), non come override. -- `reply_dispatch`: restituire `{ handled: true, ... }` è terminale. Una volta che un gestore rivendica il dispatch, i gestori a priorità più bassa e il percorso predefinito di dispatch del modello vengono saltati. -- `message_sending`: restituire `{ cancel: true }` è terminale. Una volta che un gestore lo imposta, i gestori a priorità più bassa vengono saltati. -- `message_sending`: restituire `{ cancel: false }` è trattato come nessuna decisione (uguale a omettere `cancel`), non come override. +- `before_tool_call`: restituire `{ block: true }` è terminale. Una volta che un handler lo imposta, gli handler a priorità inferiore vengono saltati. +- `before_tool_call`: restituire `{ block: false }` viene trattato come nessuna decisione (come omettere `block`), non come override. +- `before_install`: restituire `{ block: true }` è terminale. Una volta che un handler lo imposta, gli handler a priorità inferiore vengono saltati. +- `before_install`: restituire `{ block: false }` viene trattato come nessuna decisione (come omettere `block`), non come override. +- `reply_dispatch`: restituire `{ handled: true, ... }` è terminale. Una volta che un handler rivendica il dispatch, gli handler a priorità inferiore e il percorso predefinito di dispatch del modello vengono saltati. +- `message_sending`: restituire `{ cancel: true }` è terminale. Una volta che un handler lo imposta, gli handler a priorità inferiore vengono saltati. +- `message_sending`: restituire `{ cancel: false }` viene trattato come nessuna decisione (come omettere `cancel`), non come override. ### Campi dell'oggetto API -| Campo | Tipo | Descrizione | -| ------------------------ | ------------------------- | -------------------------------------------------------------------------------------------- | -| `api.id` | `string` | ID del plugin | -| `api.name` | `string` | Nome visualizzato | -| `api.version` | `string?` | Versione del plugin (facoltativa) | -| `api.description` | `string?` | Descrizione del plugin (facoltativa) | -| `api.source` | `string` | Percorso sorgente del plugin | -| `api.rootDir` | `string?` | Directory root del plugin (facoltativa) | -| `api.config` | `OpenClawConfig` | Snapshot della config corrente (snapshot runtime in-memory attivo quando disponibile) | -| `api.pluginConfig` | `Record` | Config specifica del plugin da `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Helper runtime](/it/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Logger con scope (`debug`, `info`, `warn`, `error`) | -| `api.registrationMode` | `PluginRegistrationMode` | Modalità di caricamento corrente; `"setup-runtime"` è la finestra leggera di avvio/setup pre-full-entry | -| `api.resolvePath(input)` | `(string) => string` | Risolve il percorso relativo alla root del plugin | +| Campo | Tipo | Descrizione | +| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | +| `api.id` | `string` | ID del plugin | +| `api.name` | `string` | Nome visualizzato | +| `api.version` | `string?` | Versione del plugin (facoltativa) | +| `api.description` | `string?` | Descrizione del plugin (facoltativa) | +| `api.source` | `string` | Percorso sorgente del plugin | +| `api.rootDir` | `string?` | Directory radice del plugin (facoltativa) | +| `api.config` | `OpenClawConfig` | Snapshot della configurazione corrente (snapshot runtime in memoria attivo quando disponibile) | +| `api.pluginConfig` | `Record` | Configurazione specifica del plugin da `plugins.entries..config` | +| `api.runtime` | `PluginRuntime` | [Helper runtime](/it/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | Logger con scope (`debug`, `info`, `warn`, `error`) | +| `api.registrationMode` | `PluginRegistrationMode` | Modalità di caricamento corrente; `"setup-runtime"` è la finestra leggera di avvio/configurazione prima della full-entry | +| `api.resolvePath(input)` | `(string) => string` | Risolve un percorso relativo alla radice del plugin | ## Convenzione dei moduli interni @@ -422,49 +433,49 @@ All'interno del tuo plugin, usa file barrel locali per le importazioni interne: ``` my-plugin/ - api.ts # Export pubblici per consumer esterni - runtime-api.ts # Export runtime solo interni + api.ts # Esportazioni pubbliche per i consumatori esterni + runtime-api.ts # Esportazioni runtime solo interne index.ts # Punto di ingresso del plugin - setup-entry.ts # Entry leggera solo setup (facoltativa) + setup-entry.ts # Entry leggera solo per la configurazione (facoltativa) ``` Non importare mai il tuo stesso plugin tramite `openclaw/plugin-sdk/` - dal codice di produzione. Instrada le importazioni interne tramite `./api.ts` o + dal codice di produzione. Instrada le importazioni interne attraverso `./api.ts` o `./runtime-api.ts`. Il percorso SDK è solo il contratto esterno. -Le superfici pubbliche dei plugin bundled caricate tramite facade (`api.ts`, `runtime-api.ts`, +Le superfici pubbliche dei plugin inclusi caricate tramite facade (`api.ts`, `runtime-api.ts`, `index.ts`, `setup-entry.ts` e file di entry pubblici simili) ora preferiscono lo -snapshot attivo della config runtime quando OpenClaw è già in esecuzione. Se non esiste ancora -uno snapshot runtime, usano come fallback il file di config risolto su disco. +snapshot della configurazione runtime attivo quando OpenClaw è già in esecuzione. Se non esiste ancora +uno snapshot runtime, fanno fallback al file di configurazione risolto su disco. -I plugin provider possono anche esporre un barrel di contratto locale al plugin quando un -helper è intenzionalmente specifico del provider e non appartiene ancora a un sottopercorso SDK -generico. Esempio bundled attuale: il provider Anthropic mantiene i propri helper -stream Claude nel proprio seam pubblico `api.ts` / `contract-api.ts` invece di -promuovere la logica degli header beta Anthropic e `service_tier` in un contratto +Anche i plugin provider possono esporre un barrel contrattuale locale al plugin e ristretto quando un +helper è intenzionalmente specifico del provider e non appartiene ancora a un +sottopercorso SDK generico. Esempio incluso attuale: il provider Anthropic mantiene i suoi helper +di stream Claude nel proprio seam pubblico `api.ts` / `contract-api.ts` invece di +promuovere la logica dell'header beta Anthropic e `service_tier` in un contratto generico `plugin-sdk/*`. -Altri esempi bundled attuali: +Altri esempi inclusi attuali: -- `@openclaw/openai-provider`: `api.ts` esporta builder dei provider, - helper dei modelli predefiniti e builder dei provider realtime +- `@openclaw/openai-provider`: `api.ts` esporta builder di provider, + helper di modelli predefiniti e builder di provider realtime - `@openclaw/openrouter-provider`: `api.ts` esporta il builder del provider più - helper di onboarding/config + helper di onboarding/configurazione - Anche il codice di produzione delle estensioni dovrebbe evitare importazioni + Anche il codice di produzione delle estensioni dovrebbe evitare le importazioni `openclaw/plugin-sdk/`. Se un helper è davvero condiviso, promuovilo a un sottopercorso SDK neutrale come `openclaw/plugin-sdk/speech`, `.../provider-model-shared` o un'altra - superficie orientata alla capacità invece di accoppiare due plugin tra loro. + superficie orientata alle capacità invece di accoppiare due plugin tra loro. ## Correlati -- [Entry Points](/it/plugins/sdk-entrypoints) — opzioni di `definePluginEntry` e `defineChannelPluginEntry` -- [Runtime Helpers](/it/plugins/sdk-runtime) — riferimento completo del namespace `api.runtime` -- [Setup and Config](/it/plugins/sdk-setup) — packaging, manifest, schemi di config -- [Testing](/it/plugins/sdk-testing) — utility di test e regole lint -- [SDK Migration](/it/plugins/sdk-migration) — migrazione dalle superfici deprecate -- [Plugin Internals](/it/plugins/architecture) — architettura approfondita e modello delle capacità +- [Punti di ingresso](/it/plugins/sdk-entrypoints) — opzioni di `definePluginEntry` e `defineChannelPluginEntry` +- [Helper runtime](/it/plugins/sdk-runtime) — riferimento completo dello spazio dei nomi `api.runtime` +- [Configurazione e config](/it/plugins/sdk-setup) — packaging, manifest, schemi di configurazione +- [Test](/it/plugins/sdk-testing) — utility di test e regole lint +- [Migrazione dell'SDK](/it/plugins/sdk-migration) — migrazione dalle superfici deprecate +- [Interni dei plugin](/it/plugins/architecture) — architettura approfondita e modello di capacità diff --git a/docs/it/tools/image-generation.md b/docs/it/tools/image-generation.md index 4119c9475..a6cd7c4f6 100644 --- a/docs/it/tools/image-generation.md +++ b/docs/it/tools/image-generation.md @@ -2,30 +2,30 @@ read_when: - Generazione di immagini tramite l'agente - Configurazione dei provider e dei modelli per la generazione di immagini - - Comprensione dei parametri dello strumento `image_generate` -summary: Genera e modifica immagini usando i provider configurati (OpenAI, Google Gemini, fal, MiniMax, ComfyUI, Vydra) + - Comprensione dei parametri dello strumento image_generate +summary: Genera e modifica immagini utilizzando i provider configurati (OpenAI, Google Gemini, fal, MiniMax, ComfyUI, Vydra) title: Generazione di immagini x-i18n: - generated_at: "2026-04-06T03:12:38Z" + generated_at: "2026-04-06T08:15:08Z" model: gpt-5.4 provider: openai - source_hash: dde416dd1441a06605db85b5813cf61ccfc525813d6db430b7b7dfa53d6a3134 + source_hash: 903cc522c283a8da2cbd449ae3e25f349a74d00ecfdaf0f323fd8aa3f2107aea source_path: tools/image-generation.md workflow: 15 --- # Generazione di immagini -Lo strumento `image_generate` consente all'agente di creare e modificare immagini usando i provider configurati. Le immagini generate vengono recapitate automaticamente come allegati multimediali nella risposta dell'agente. +Lo strumento `image_generate` consente all'agente di creare e modificare immagini utilizzando i provider configurati. Le immagini generate vengono recapitate automaticamente come allegati multimediali nella risposta dell'agente. -Lo strumento appare solo quando è disponibile almeno un provider di generazione di immagini. Se non vedi `image_generate` tra gli strumenti del tuo agente, configura `agents.defaults.imageGenerationModel` o imposta una chiave API del provider. +Lo strumento appare solo quando è disponibile almeno un provider per la generazione di immagini. Se non vedi `image_generate` tra gli strumenti del tuo agente, configura `agents.defaults.imageGenerationModel` oppure imposta una chiave API di un provider. ## Avvio rapido -1. Imposta una chiave API per almeno un provider (ad esempio `OPENAI_API_KEY` o `GEMINI_API_KEY`). -2. Facoltativamente imposta il tuo modello preferito: +1. Imposta una chiave API per almeno un provider, ad esempio `OPENAI_API_KEY` o `GEMINI_API_KEY`. +2. Facoltativamente, imposta il modello preferito: ```json5 { @@ -41,20 +41,20 @@ Lo strumento appare solo quando è disponibile almeno un provider di generazione 3. Chiedi all'agente: _"Genera un'immagine di una simpatica mascotte aragosta."_ -L'agente chiama automaticamente `image_generate`. Non serve alcuna allowlist degli strumenti — è abilitato per impostazione predefinita quando un provider è disponibile. +L'agente chiama automaticamente `image_generate`. Non è necessario alcun allowlist degli strumenti: è abilitato per impostazione predefinita quando è disponibile un provider. ## Provider supportati -| Provider | Modello predefinito | Supporto modifica | Chiave API | -| -------- | ------------------------------- | ---------------------------------- | ------------------------------------------------------ | -| OpenAI | `gpt-image-1` | Sì (fino a 5 immagini) | `OPENAI_API_KEY` | -| Google | `gemini-3.1-flash-image-preview` | Sì | `GEMINI_API_KEY` o `GOOGLE_API_KEY` | -| fal | `fal-ai/flux/dev` | Sì | `FAL_KEY` | -| MiniMax | `image-01` | Sì (riferimento del soggetto) | `MINIMAX_API_KEY` o OAuth MiniMax (`minimax-portal`) | -| ComfyUI | `workflow` | Sì (1 immagine, configurata dal workflow) | `COMFY_API_KEY` o `COMFY_CLOUD_API_KEY` per il cloud | -| Vydra | `grok-imagine` | No | `VYDRA_API_KEY` | +| Provider | Modello predefinito | Supporto per la modifica | Chiave API | +| -------- | -------------------------------- | ----------------------------------- | ----------------------------------------------------- | +| OpenAI | `gpt-image-1` | Sì (fino a 5 immagini) | `OPENAI_API_KEY` | +| Google | `gemini-3.1-flash-image-preview` | Sì | `GEMINI_API_KEY` o `GOOGLE_API_KEY` | +| fal | `fal-ai/flux/dev` | Sì | `FAL_KEY` | +| MiniMax | `image-01` | Sì (riferimento al soggetto) | `MINIMAX_API_KEY` o OAuth MiniMax (`minimax-portal`) | +| ComfyUI | `workflow` | Sì (1 immagine, configurata tramite workflow) | `COMFY_API_KEY` o `COMFY_CLOUD_API_KEY` per il cloud | +| Vydra | `grok-imagine` | No | `VYDRA_API_KEY` | -Usa `action: "list"` per ispezionare provider e modelli disponibili a runtime: +Usa `action: "list"` per esaminare i provider e i modelli disponibili in fase di esecuzione: ``` /tool image_generate action=list @@ -62,20 +62,20 @@ Usa `action: "list"` per ispezionare provider e modelli disponibili a runtime: ## Parametri dello strumento -| Parametro | Tipo | Descrizione | -| ------------- | -------- | ---------------------------------------------------------------------------------- | -| `prompt` | string | Prompt di generazione dell'immagine (obbligatorio per `action: "generate"`) | -| `action` | string | `"generate"` (predefinito) o `"list"` per ispezionare i provider | -| `model` | string | Override provider/modello, ad esempio `openai/gpt-image-1` | -| `image` | string | Singolo percorso immagine di riferimento o URL per la modalità modifica | -| `images` | string[] | Più immagini di riferimento per la modalità modifica (fino a 5) | -| `size` | string | Suggerimento di dimensione: `1024x1024`, `1536x1024`, `1024x1536`, `1024x1792`, `1792x1024` | -| `aspectRatio` | string | Rapporto di aspetto: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` | -| `resolution` | string | Suggerimento di risoluzione: `1K`, `2K` o `4K` | -| `count` | number | Numero di immagini da generare (1–4) | -| `filename` | string | Suggerimento per il nome del file di output | +| Parametro | Tipo | Descrizione | +| ------------- | -------- | ------------------------------------------------------------------------------------ | +| `prompt` | string | Prompt per la generazione di immagini (obbligatorio per `action: "generate"`) | +| `action` | string | `"generate"` (predefinito) oppure `"list"` per esaminare i provider | +| `model` | string | Override di provider/modello, ad esempio `openai/gpt-image-1` | +| `image` | string | Percorso o URL di una singola immagine di riferimento per la modalità modifica | +| `images` | string[] | Più immagini di riferimento per la modalità modifica (fino a 5) | +| `size` | string | Indicazione della dimensione: `1024x1024`, `1536x1024`, `1024x1536`, `1024x1792`, `1792x1024` | +| `aspectRatio` | string | Rapporto d'aspetto: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` | +| `resolution` | string | Indicazione della risoluzione: `1K`, `2K` o `4K` | +| `count` | number | Numero di immagini da generare (1–4) | +| `filename` | string | Indicazione del nome file di output | -Non tutti i provider supportano tutti i parametri. Lo strumento passa ciò che ciascun provider supporta, ignora il resto e segnala gli override scartati nel risultato dello strumento. +Non tutti i provider supportano tutti i parametri. Lo strumento passa ciò che ogni provider supporta, ignora il resto e segnala gli override scartati nel risultato dello strumento. ## Configurazione @@ -94,58 +94,57 @@ Non tutti i provider supportano tutti i parametri. Lo strumento passa ciò che c } ``` -### Ordine di selezione del provider +### Ordine di selezione dei provider Quando genera un'immagine, OpenClaw prova i provider in questo ordine: -1. Il parametro **`model`** della chiamata allo strumento (se l'agente ne specifica uno) +1. **Parametro `model`** della chiamata allo strumento (se l'agente ne specifica uno) 2. **`imageGenerationModel.primary`** dalla configurazione 3. **`imageGenerationModel.fallbacks`** nell'ordine indicato -4. **Rilevamento automatico** — usa solo i valori predefiniti dei provider supportati dall'autenticazione: +4. **Rilevamento automatico** — usa solo i provider predefiniti supportati dall'autenticazione: - prima il provider predefinito corrente - - poi i restanti provider di generazione di immagini registrati in ordine di ID provider + - poi i restanti provider di generazione di immagini registrati, in ordine di provider id -Se un provider fallisce (errore di autenticazione, rate limit, ecc.), il candidato successivo viene provato automaticamente. Se falliscono tutti, l'errore include i dettagli di ogni tentativo. +Se un provider non riesce (errore di autenticazione, limite di velocità, ecc.), viene provato automaticamente il candidato successivo. Se falliscono tutti, l'errore include i dettagli di ogni tentativo. Note: - Il rilevamento automatico è consapevole dell'autenticazione. Un provider predefinito entra nell'elenco dei candidati solo quando OpenClaw può effettivamente autenticare quel provider. -- Usa `action: "list"` per ispezionare i provider attualmente registrati, i loro - modelli predefiniti e i suggerimenti sulle env var di autenticazione. +- Usa `action: "list"` per esaminare i provider attualmente registrati, i loro modelli predefiniti e i suggerimenti sulle variabili d'ambiente per l'autenticazione. ### Modifica delle immagini -OpenAI, Google, fal, MiniMax e ComfyUI supportano la modifica di immagini di riferimento. Passa un percorso immagine di riferimento o un URL: +OpenAI, Google, fal, MiniMax e ComfyUI supportano la modifica di immagini di riferimento. Passa un percorso o un URL di un'immagine di riferimento: ``` -"Genera una versione acquerello di questa foto" + image: "/path/to/photo.jpg" +"Genera una versione ad acquerello di questa foto" + image: "/path/to/photo.jpg" ``` OpenAI e Google supportano fino a 5 immagini di riferimento tramite il parametro `images`. fal, MiniMax e ComfyUI ne supportano 1. -La generazione di immagini MiniMax è disponibile tramite entrambi i percorsi auth MiniMax bundled: +La generazione di immagini MiniMax è disponibile tramite entrambi i percorsi di autenticazione MiniMax inclusi: -- `minimax/image-01` per configurazioni con chiave API -- `minimax-portal/image-01` per configurazioni OAuth +- `minimax/image-01` per le configurazioni con chiave API +- `minimax-portal/image-01` per le configurazioni con OAuth -## Capability dei provider +## Capacità dei provider -| Capability | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | -| --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ----- | -| Generazione | Sì (fino a 4) | Sì (fino a 4) | Sì (fino a 4) | Sì (fino a 9) | Sì (output definiti dal workflow) | Sì (1) | -| Modifica/riferimento | Sì (fino a 5 immagini) | Sì (fino a 5 immagini) | Sì (1 immagine) | Sì (1 immagine, riferimento soggetto) | Sì (1 immagine, configurata dal workflow) | No | -| Controllo dimensione | Sì | Sì | Sì | No | No | No | -| Rapporto di aspetto | No | Sì | Sì (solo generazione) | Sì | No | No | -| Risoluzione (1K/2K/4K) | No | Sì | Sì | No | No | No | +| Capacità | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | +| --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ------- | +| Generazione | Sì (fino a 4) | Sì (fino a 4) | Sì (fino a 4) | Sì (fino a 9) | Sì (output definiti dal workflow) | Sì (1) | +| Modifica/riferimento | Sì (fino a 5 immagini) | Sì (fino a 5 immagini) | Sì (1 immagine) | Sì (1 immagine, rif. soggetto) | Sì (1 immagine, configurata tramite workflow) | No | +| Controllo dimensione | Sì | Sì | Sì | No | No | No | +| Rapporto d'aspetto | No | Sì | Sì (solo generazione) | Sì | No | No | +| Risoluzione (1K/2K/4K) | No | Sì | Sì | No | No | No | ## Correlati -- [Panoramica degli strumenti](/it/tools) — tutti gli strumenti agente disponibili -- [fal](/providers/fal) — configurazione del provider immagini e video fal -- [ComfyUI](/providers/comfy) — configurazione del workflow locale ComfyUI e Comfy Cloud -- [Google (Gemini)](/it/providers/google) — configurazione del provider immagini Gemini -- [MiniMax](/it/providers/minimax) — configurazione del provider immagini MiniMax +- [Panoramica degli strumenti](/it/tools) — tutti gli strumenti dell'agente disponibili +- [fal](/it/providers/fal) — configurazione del provider di immagini e video fal +- [ComfyUI](/it/providers/comfy) — configurazione locale di ComfyUI e dei workflow Comfy Cloud +- [Google (Gemini)](/it/providers/google) — configurazione del provider di immagini Gemini +- [MiniMax](/it/providers/minimax) — configurazione del provider di immagini MiniMax - [OpenAI](/it/providers/openai) — configurazione del provider OpenAI Images -- [Vydra](/providers/vydra) — configurazione di immagini, video e speech Vydra -- [Riferimento di configurazione](/it/gateway/configuration-reference#agent-defaults) — configurazione `imageGenerationModel` +- [Vydra](/it/providers/vydra) — configurazione di immagini, video e voce per Vydra +- [Riferimento della configurazione](/it/gateway/configuration-reference#agent-defaults) — configurazione `imageGenerationModel` - [Modelli](/it/concepts/models) — configurazione dei modelli e failover diff --git a/docs/it/tools/video-generation.md b/docs/it/tools/video-generation.md index a32fbf595..8f5b63eb2 100644 --- a/docs/it/tools/video-generation.md +++ b/docs/it/tools/video-generation.md @@ -1,30 +1,30 @@ --- read_when: - - Generazione di video tramite l'agent - - Configurazione dei provider e dei modelli di generazione video + - Generazione di video tramite l'agente + - Configurazione dei provider e dei modelli per la generazione video - Comprensione dei parametri dello strumento video_generate -summary: Genera video da testo, immagini o video esistenti usando 12 backend provider -title: Generazione di video +summary: Genera video da testo, immagini o video esistenti utilizzando 12 backend provider +title: Generazione video x-i18n: - generated_at: "2026-04-06T03:13:31Z" + generated_at: "2026-04-06T08:15:18Z" model: gpt-5.4 provider: openai - source_hash: 4afec87368232221db1aa5a3980254093d6a961b17271b2dcbf724e6bd455b16 + source_hash: 90d8a392b35adbd899232b02c55c10895b9d7ffc9858d6ca448f2e4e4a57f12f source_path: tools/video-generation.md workflow: 15 --- -# Generazione di video +# Generazione video -Gli agent OpenClaw possono generare video da prompt di testo, immagini di riferimento o video esistenti. Sono supportati dodici backend provider, ciascuno con opzioni di modello, modalità di input e set di funzionalità differenti. L'agent sceglie automaticamente il provider corretto in base alla tua configurazione e alle API key disponibili. +Gli agenti OpenClaw possono generare video da prompt di testo, immagini di riferimento o video esistenti. Sono supportati dodici backend provider, ciascuno con diverse opzioni di modello, modalità di input e set di funzionalità. L'agente sceglie automaticamente il provider corretto in base alla tua configurazione e alle chiavi API disponibili. -Lo strumento `video_generate` compare solo quando è disponibile almeno un provider di generazione video. Se non lo vedi tra gli strumenti del tuo agent, imposta una API key del provider o configura `agents.defaults.videoGenerationModel`. +Lo strumento `video_generate` appare solo quando è disponibile almeno un provider per la generazione video. Se non lo vedi tra gli strumenti del tuo agente, imposta una chiave API del provider o configura `agents.defaults.videoGenerationModel`. -## Guida rapida +## Avvio rapido -1. Imposta una API key per un provider supportato: +1. Imposta una chiave API per qualsiasi provider supportato: ```bash export GEMINI_API_KEY="your-key" @@ -36,58 +36,58 @@ export GEMINI_API_KEY="your-key" openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview" ``` -3. Chiedi all'agent: +3. Chiedi all'agente: > Genera un video cinematografico di 5 secondi di un'aragosta amichevole che fa surf al tramonto. -L'agent chiama automaticamente `video_generate`. Non è necessaria alcuna allowlist degli strumenti. +L'agente chiama automaticamente `video_generate`. Non è necessaria alcuna allowlist degli strumenti. ## Cosa succede quando generi un video -La generazione video è asincrona. Quando l'agent chiama `video_generate` in una sessione: +La generazione video è asincrona. Quando l'agente chiama `video_generate` in una sessione: 1. OpenClaw invia la richiesta al provider e restituisce immediatamente un ID attività. -2. Il provider elabora il job in background (tipicamente da 30 secondi a 5 minuti a seconda del provider e della risoluzione). +2. Il provider elabora il lavoro in background (in genere da 30 secondi a 5 minuti a seconda del provider e della risoluzione). 3. Quando il video è pronto, OpenClaw riattiva la stessa sessione con un evento interno di completamento. -4. L'agent pubblica il video completato nella conversazione originale. +4. L'agente pubblica il video completato nella conversazione originale. -Mentre un job è in corso, chiamate duplicate a `video_generate` nella stessa sessione restituiscono lo stato corrente dell'attività invece di avviare un'altra generazione. Usa `openclaw tasks list` o `openclaw tasks show ` per controllare l'avanzamento dalla CLI. +Mentre un'attività è in corso, le chiamate duplicate a `video_generate` nella stessa sessione restituiscono lo stato corrente dell'attività invece di avviare un'altra generazione. Usa `openclaw tasks list` o `openclaw tasks show ` per controllare l'avanzamento dalla CLI. -Al di fuori delle esecuzioni dell'agent supportate da sessione (ad esempio invocazioni dirette dello strumento), lo strumento usa come fallback la generazione inline e restituisce il percorso finale del media nello stesso turno. +Al di fuori delle esecuzioni dell'agente supportate da sessione (ad esempio, invocazioni dirette degli strumenti), lo strumento torna alla generazione inline e restituisce il percorso finale del file multimediale nello stesso turno. ## Provider supportati -| Provider | Modello predefinito | Testo | Riferimento immagine | Riferimento video | API key | -| -------- | ------------------------------- | ----- | -------------------- | ----------------- | ---------------------------------------- | -| Alibaba | `wan2.6-t2v` | Sì | Sì (URL remoto) | Sì (URL remoto) | `MODELSTUDIO_API_KEY` | -| BytePlus | `seedance-1-0-lite-t2v-250428` | Sì | 1 immagine | No | `BYTEPLUS_API_KEY` | -| ComfyUI | `workflow` | Sì | 1 immagine | No | `COMFY_API_KEY` o `COMFY_CLOUD_API_KEY` | -| fal | `fal-ai/minimax/video-01-live` | Sì | 1 immagine | No | `FAL_KEY` | -| Google | `veo-3.1-fast-generate-preview` | Sì | 1 immagine | 1 video | `GEMINI_API_KEY` | -| MiniMax | `MiniMax-Hailuo-2.3` | Sì | 1 immagine | No | `MINIMAX_API_KEY` | -| OpenAI | `sora-2` | Sì | 1 immagine | 1 video | `OPENAI_API_KEY` | -| Qwen | `wan2.6-t2v` | Sì | Sì (URL remoto) | Sì (URL remoto) | `QWEN_API_KEY` | -| Runway | `gen4.5` | Sì | 1 immagine | 1 video | `RUNWAYML_API_SECRET` | -| Together | `Wan-AI/Wan2.2-T2V-A14B` | Sì | 1 immagine | No | `TOGETHER_API_KEY` | -| Vydra | `veo3` | Sì | 1 immagine (`kling`) | No | `VYDRA_API_KEY` | -| xAI | `grok-imagine-video` | Sì | 1 immagine | 1 video | `XAI_API_KEY` | +| Provider | Modello predefinito | Testo | Immagine rif. | Video rif. | Chiave API | +| -------- | ------------------------------- | ----- | ----------------- | ---------------- | ----------------------------------------- | +| Alibaba | `wan2.6-t2v` | Sì | Sì (URL remoto) | Sì (URL remoto) | `MODELSTUDIO_API_KEY` | +| BytePlus | `seedance-1-0-lite-t2v-250428` | Sì | 1 immagine | No | `BYTEPLUS_API_KEY` | +| ComfyUI | `workflow` | Sì | 1 immagine | No | `COMFY_API_KEY` o `COMFY_CLOUD_API_KEY` | +| fal | `fal-ai/minimax/video-01-live` | Sì | 1 immagine | No | `FAL_KEY` | +| Google | `veo-3.1-fast-generate-preview` | Sì | 1 immagine | 1 video | `GEMINI_API_KEY` | +| MiniMax | `MiniMax-Hailuo-2.3` | Sì | 1 immagine | No | `MINIMAX_API_KEY` | +| OpenAI | `sora-2` | Sì | 1 immagine | 1 video | `OPENAI_API_KEY` | +| Qwen | `wan2.6-t2v` | Sì | Sì (URL remoto) | Sì (URL remoto) | `QWEN_API_KEY` | +| Runway | `gen4.5` | Sì | 1 immagine | 1 video | `RUNWAYML_API_SECRET` | +| Together | `Wan-AI/Wan2.2-T2V-A14B` | Sì | 1 immagine | No | `TOGETHER_API_KEY` | +| Vydra | `veo3` | Sì | 1 immagine (`kling`) | No | `VYDRA_API_KEY` | +| xAI | `grok-imagine-video` | Sì | 1 immagine | 1 video | `XAI_API_KEY` | -Alcuni provider accettano variabili env API key aggiuntive o alternative. Vedi le singole [pagine provider](#related) per i dettagli. +Alcuni provider accettano variabili d'ambiente aggiuntive o alternative per la chiave API. Consulta le singole [pagine dei provider](#related) per i dettagli. -Esegui `video_generate action=list` per ispezionare i provider e i modelli disponibili a runtime. +Esegui `video_generate action=list` per esaminare i provider e i modelli disponibili in fase di esecuzione. ## Parametri dello strumento ### Obbligatori -| Parametro | Tipo | Descrizione | -| --------- | ------ | ------------------------------------------------------------------------------ | +| Parametro | Tipo | Descrizione | +| --------- | ------ | --------------------------------------------------------------------------- | | `prompt` | string | Descrizione testuale del video da generare (obbligatoria per `action: "generate"`) | ### Input di contenuto -| Parametro | Tipo | Descrizione | -| --------- | -------- | ---------------------------------------- | +| Parametro | Tipo | Descrizione | +| --------- | -------- | --------------------------------------- | | `image` | string | Singola immagine di riferimento (percorso o URL) | | `images` | string[] | Immagini di riferimento multiple (fino a 5) | | `video` | string | Singolo video di riferimento (percorso o URL) | @@ -95,41 +95,41 @@ Esegui `video_generate action=list` per ispezionare i provider e i modelli dispo ### Controlli di stile -| Parametro | Tipo | Descrizione | -| ----------------- | ------- | ------------------------------------------------------------------------ | -| `aspectRatio` | string | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` | -| `resolution` | string | `480P`, `720P` o `1080P` | -| `durationSeconds` | number | Durata target in secondi (arrotondata al valore supportato più vicino dal provider) | -| `size` | string | Suggerimento di dimensione quando il provider lo supporta | -| `audio` | boolean | Abilita l'audio generato quando supportato | -| `watermark` | boolean | Attiva/disattiva la filigrana del provider quando supportata | +| Parametro | Tipo | Descrizione | +| ---------------- | ------- | ---------------------------------------------------------------------- | +| `aspectRatio` | string | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` | +| `resolution` | string | `480P`, `720P` o `1080P` | +| `durationSeconds`| number | Durata target in secondi (arrotondata al valore supportato dal provider più vicino) | +| `size` | string | Indicazione di dimensione quando il provider la supporta | +| `audio` | boolean | Abilita l'audio generato quando supportato | +| `watermark` | boolean | Attiva o disattiva il watermark del provider quando supportato | ### Avanzati | Parametro | Tipo | Descrizione | | ---------- | ------ | ------------------------------------------------ | | `action` | string | `"generate"` (predefinito), `"status"` o `"list"` | -| `model` | string | Override provider/model (ad esempio `runway/gen4.5`) | +| `model` | string | Override di provider/modello (ad es. `runway/gen4.5`) | | `filename` | string | Suggerimento per il nome del file di output | -Non tutti i provider supportano tutti i parametri. Gli override non supportati vengono ignorati su base best-effort e segnalati come avvisi nel risultato dello strumento. I limiti rigidi delle capability (come troppi input di riferimento) falliscono prima dell'invio. +Non tutti i provider supportano tutti i parametri. Gli override non supportati vengono ignorati in base al miglior sforzo e segnalati come avvisi nel risultato dello strumento. I limiti rigidi di capacità (come un numero eccessivo di input di riferimento) falliscono prima dell'invio. ## Azioni -- **generate** (predefinita) -- crea un video dal prompt fornito e dagli eventuali input di riferimento. +- **generate** (predefinita) -- crea un video a partire dal prompt fornito e dagli input di riferimento facoltativi. - **status** -- controlla lo stato dell'attività video in corso per la sessione corrente senza avviare un'altra generazione. -- **list** -- mostra provider, modelli disponibili e relative capability. +- **list** -- mostra i provider, i modelli e le relative capacità disponibili. ## Selezione del modello Quando genera un video, OpenClaw risolve il modello in questo ordine: -1. **Parametro dello strumento `model`** -- se l'agent ne specifica uno nella chiamata. +1. **Parametro dello strumento `model`** -- se l'agente ne specifica uno nella chiamata. 2. **`videoGenerationModel.primary`** -- dalla configurazione. 3. **`videoGenerationModel.fallbacks`** -- provati in ordine. -4. **Rilevamento automatico** -- usa i provider che hanno auth valida, iniziando dal provider predefinito corrente, poi i provider rimanenti in ordine alfabetico. +4. **Rilevamento automatico** -- usa i provider con autenticazione valida, iniziando dal provider predefinito corrente, poi i provider rimanenti in ordine alfabetico. -Se un provider fallisce, viene provato automaticamente il candidato successivo. Se tutti i candidati falliscono, l'errore include i dettagli di ogni tentativo. +Se un provider fallisce, il candidato successivo viene provato automaticamente. Se tutti i candidati falliscono, l'errore include i dettagli di ogni tentativo. ```json5 { @@ -146,24 +146,24 @@ Se un provider fallisce, viene provato automaticamente il candidato successivo. ## Note sui provider -| Provider | Note | -| -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -| Alibaba | Usa l'endpoint asincrono DashScope/Model Studio. Le immagini e i video di riferimento devono essere URL remoti `http(s)`. | -| BytePlus | Solo un'immagine di riferimento. | -| ComfyUI | Esecuzione locale o cloud guidata da workflow. Supporta text-to-video e image-to-video tramite il grafo configurato. | -| fal | Usa un flusso supportato da coda per job di lunga durata. Solo un'immagine di riferimento. | -| Google | Usa Gemini/Veo. Supporta un'immagine o un video di riferimento. | -| MiniMax | Solo un'immagine di riferimento. | -| OpenAI | Viene inoltrato solo l'override `size`. Gli altri override di stile (`aspectRatio`, `resolution`, `audio`, `watermark`) vengono ignorati con un avviso. | -| Qwen | Stesso backend DashScope di Alibaba. Gli input di riferimento devono essere URL remoti `http(s)`; i file locali vengono rifiutati in anticipo. | -| Runway | Supporta file locali tramite data URI. Video-to-video richiede `runway/gen4_aleph`. Le esecuzioni solo testo espongono rapporti d'aspetto `16:9` e `9:16`. | -| Together | Solo un'immagine di riferimento. | -| Vydra | Usa direttamente `https://www.vydra.ai/api/v1` per evitare redirect che perdono auth. `veo3` è integrato solo come text-to-video; `kling` richiede un URL immagine remoto. | -| xAI | Supporta flussi text-to-video, image-to-video e modifica/estensione di video remoti. | +| Provider | Note | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Alibaba | Usa l'endpoint asincrono DashScope/Model Studio. Le immagini e i video di riferimento devono essere URL `http(s)` remoti. | +| BytePlus | Solo un'immagine di riferimento. | +| ComfyUI | Esecuzione locale o cloud basata su workflow. Supporta text-to-video e image-to-video tramite il grafo configurato. | +| fal | Usa un flusso supportato da coda per lavori di lunga durata. Solo un'immagine di riferimento. | +| Google | Usa Gemini/Veo. Supporta un'immagine o un video di riferimento. | +| MiniMax | Solo un'immagine di riferimento. | +| OpenAI | Viene inoltrato solo l'override `size`. Gli altri override di stile (`aspectRatio`, `resolution`, `audio`, `watermark`) vengono ignorati con un avviso. | +| Qwen | Stesso backend DashScope di Alibaba. Gli input di riferimento devono essere URL `http(s)` remoti; i file locali vengono rifiutati in anticipo. | +| Runway | Supporta file locali tramite URI di dati. Video-to-video richiede `runway/gen4_aleph`. Le esecuzioni solo testo espongono i rapporti d'aspetto `16:9` e `9:16`. | +| Together | Solo un'immagine di riferimento. | +| Vydra | Usa direttamente `https://www.vydra.ai/api/v1` per evitare reindirizzamenti che eliminano l'autenticazione. `veo3` è incluso solo come text-to-video; `kling` richiede un URL immagine remoto. | +| xAI | Supporta flussi text-to-video, image-to-video e di modifica/estensione video remota. | ## Configurazione -Imposta il modello di generazione video predefinito nella configurazione OpenClaw: +Imposta il modello predefinito per la generazione video nella configurazione di OpenClaw: ```json5 { @@ -187,18 +187,18 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2 ## Correlati - [Panoramica degli strumenti](/it/tools) -- [Attività in background](/it/automation/tasks) -- tracciamento delle attività per la generazione video asincrona -- [Alibaba Model Studio](/providers/alibaba) -- [BytePlus](/providers/byteplus) -- [ComfyUI](/providers/comfy) -- [fal](/providers/fal) +- [Attività in background](/it/automation/tasks) -- monitoraggio delle attività per la generazione video asincrona +- [Alibaba Model Studio](/it/providers/alibaba) +- [BytePlus](/it/concepts/model-providers#byteplus-international) +- [ComfyUI](/it/providers/comfy) +- [fal](/it/providers/fal) - [Google (Gemini)](/it/providers/google) - [MiniMax](/it/providers/minimax) - [OpenAI](/it/providers/openai) - [Qwen](/it/providers/qwen) -- [Runway](/providers/runway) +- [Runway](/it/providers/runway) - [Together AI](/it/providers/together) -- [Vydra](/providers/vydra) +- [Vydra](/it/providers/vydra) - [xAI](/it/providers/xai) -- [Riferimento configurazione](/it/gateway/configuration-reference#agent-defaults) +- [Riferimento della configurazione](/it/gateway/configuration-reference#agent-defaults) - [Modelli](/it/concepts/models)