diff --git a/docs/it/channels/pairing.md b/docs/it/channels/pairing.md index 9cfed0927..3faf4b230 100644 --- a/docs/it/channels/pairing.md +++ b/docs/it/channels/pairing.md @@ -1,40 +1,40 @@ --- read_when: - - Configurazione del controllo degli accessi DM - - Pairing di un nuovo nodo iOS/Android + - Configurazione del controllo di accesso ai messaggi diretti + - Associazione di un nuovo Node iOS/Android - Revisione della postura di sicurezza di OpenClaw -summary: 'Panoramica del pairing: approva chi può inviarti DM e quali nodi possono unirsi' -title: Pairing +summary: 'Panoramica dell''associazione: approva chi può inviarti messaggi diretti + quali nodi possono unirsi' +title: Associazione x-i18n: - generated_at: "2026-04-05T13:43:36Z" + generated_at: "2026-04-20T08:30:53Z" model: gpt-5.4 provider: openai - source_hash: 2bd99240b3530def23c05a26915d07cf8b730565c2822c6338437f8fb3f285c9 + source_hash: 4161629ead02dc0bdcd283cc125fe6579a579e03740127f4feb22dfe344bd028 source_path: channels/pairing.md workflow: 15 --- -# Pairing +# Associazione -Il “pairing” è il passaggio esplicito di **approvazione del proprietario** di OpenClaw. -Viene usato in due punti: +L’“associazione” è il passaggio esplicito di **approvazione del proprietario** di OpenClaw. +Viene utilizzata in due casi: -1. **DM pairing** (chi è autorizzato a parlare con il bot) -2. **Node pairing** (quali dispositivi/nodi sono autorizzati a unirsi alla rete del gateway) +1. **Associazione DM** (chi è autorizzato a parlare con il bot) +2. **Associazione del Node** (quali dispositivi/nodi sono autorizzati a unirsi alla rete Gateway) -Contesto di sicurezza: [Security](/gateway/security) +Contesto di sicurezza: [Security](/it/gateway/security) -## 1) DM pairing (accesso alla chat in ingresso) +## 1) Associazione DM (accesso alla chat in ingresso) -Quando un canale è configurato con la policy DM `pairing`, i mittenti sconosciuti ricevono un codice breve e il loro messaggio **non viene elaborato** finché non approvi. +Quando un canale è configurato con il criterio DM `pairing`, i mittenti sconosciuti ricevono un codice breve e il loro messaggio **non viene elaborato** finché non approvi. -Le policy DM predefinite sono documentate in: [Security](/gateway/security) +I criteri DM predefiniti sono documentati in: [Security](/it/gateway/security) -Codici di pairing: +Codici di associazione: - 8 caratteri, maiuscoli, senza caratteri ambigui (`0O1I`). -- **Scadono dopo 1 ora**. Il bot invia il messaggio di pairing solo quando viene creata una nuova richiesta (all'incirca una volta all'ora per mittente). -- Le richieste di DM pairing in sospeso sono limitate per impostazione predefinita a **3 per canale**; le richieste aggiuntive vengono ignorate finché una non scade o non viene approvata. +- **Scadono dopo 1 ora**. Il bot invia il messaggio di associazione solo quando viene creata una nuova richiesta (circa una volta all’ora per mittente). +- Le richieste DM di associazione in sospeso sono limitate a **3 per canale** per impostazione predefinita; le richieste aggiuntive vengono ignorate finché una non scade o non viene approvata. ### Approvare un mittente @@ -45,57 +45,57 @@ openclaw pairing approve telegram Canali supportati: `bluebubbles`, `discord`, `feishu`, `googlechat`, `imessage`, `irc`, `line`, `matrix`, `mattermost`, `msteams`, `nextcloud-talk`, `nostr`, `openclaw-weixin`, `signal`, `slack`, `synology-chat`, `telegram`, `twitch`, `whatsapp`, `zalo`, `zalouser`. -### Dove si trova lo stato +### Dove risiede lo stato Memorizzato in `~/.openclaw/credentials/`: - Richieste in sospeso: `-pairing.json` -- Archivio allowlist approvata: +- Archivio delle allowlist approvate: - Account predefinito: `-allowFrom.json` - Account non predefinito: `--allowFrom.json` -Comportamento dell'ambito account: +Comportamento dell’ambito account: -- Gli account non predefiniti leggono/scrivono solo il proprio file allowlist con ambito. -- L'account predefinito usa il file allowlist senza ambito, con ambito del canale. +- Gli account non predefiniti leggono/scrivono solo il proprio file allowlist con ambito specifico. +- L’account predefinito usa il file allowlist senza ambito specifico del canale. -Tratta questi file come sensibili (controllano l'accesso al tuo assistente). +Trattali come dati sensibili (controllano l’accesso al tuo assistente). -Importante: questo archivio serve per l'accesso DM. L'autorizzazione dei gruppi è separata. -Approvare un codice di DM pairing non consente automaticamente a quel mittente di eseguire comandi di gruppo o controllare il bot nei gruppi. Per l'accesso ai gruppi, configura le allowlist esplicite del canale per i gruppi (ad esempio `groupAllowFrom`, `groups` o override per gruppo/per argomento a seconda del canale). +Importante: questo archivio è per l’accesso DM. L’autorizzazione dei gruppi è separata. +Approvare un codice di associazione DM non consente automaticamente a quel mittente di eseguire comandi di gruppo o controllare il bot nei gruppi. Per l’accesso ai gruppi, configura le allowlist esplicite del canale per i gruppi (ad esempio `groupAllowFrom`, `groups` o override per gruppo/per topic, a seconda del canale). -## 2) Pairing del dispositivo nodo (nodi iOS/Android/macOS/headless) +## 2) Associazione del dispositivo Node (nodi iOS/Android/macOS/headless) -I nodi si connettono al Gateway come **dispositivi** con `role: node`. Il Gateway -crea una richiesta di pairing del dispositivo che deve essere approvata. +I Node si connettono al Gateway come **dispositivi** con `role: node`. Il Gateway +crea una richiesta di associazione del dispositivo che deve essere approvata. -### Pairing tramite Telegram (consigliato per iOS) +### Associare tramite Telegram (consigliato per iOS) -Se usi il plugin `device-pair`, puoi eseguire il primo pairing del dispositivo interamente da Telegram: +Se utilizzi il plugin `device-pair`, puoi eseguire la prima associazione del dispositivo interamente da Telegram: -1. In Telegram, invia al tuo bot: `/pair` +1. In Telegram, invia un messaggio al tuo bot: `/pair` 2. Il bot risponde con due messaggi: un messaggio di istruzioni e un messaggio separato con il **codice di configurazione** (facile da copiare/incollare in Telegram). -3. Sul telefono, apri l'app iOS di OpenClaw → Impostazioni → Gateway. +3. Sul telefono, apri l’app OpenClaw iOS → Settings → Gateway. 4. Incolla il codice di configurazione e connettiti. -5. Tornato in Telegram: `/pair pending` (rivedi ID richiesta, ruolo e scope), quindi approva. +5. Torna in Telegram: `/pair pending` (controlla ID richiesta, ruolo e ambiti), quindi approva. Il codice di configurazione è un payload JSON codificato in base64 che contiene: -- `url`: l'URL WebSocket del Gateway (`ws://...` oppure `wss://...`) -- `bootstrapToken`: un bootstrap token a breve durata, per un solo dispositivo, usato per l'handshake iniziale di pairing +- `url`: l’URL WebSocket del Gateway (`ws://...` o `wss://...`) +- `bootstrapToken`: un token bootstrap temporaneo per singolo dispositivo usato per l’handshake iniziale di associazione -Quel bootstrap token contiene il profilo bootstrap di pairing integrato: +Quel token bootstrap include il profilo bootstrap di associazione integrato: -- il token `node` primario trasferito resta `scopes: []` -- qualsiasi token `operator` trasferito resta vincolato all'allowlist bootstrap: +- il token `node` primario passato rimane `scopes: []` +- qualsiasi token `operator` passato rimane limitato alla bootstrap allowlist: `operator.approvals`, `operator.read`, `operator.talk.secrets`, `operator.write` -- i controlli degli scope bootstrap usano prefissi di ruolo, non un unico pool di scope: - le voci di scope operator soddisfano solo richieste operator, e i ruoli non operator - devono comunque richiedere scope sotto il proprio prefisso di ruolo +- i controlli degli ambiti bootstrap sono prefissati per ruolo, non un unico pool piatto di ambiti: + le voci di ambito operator soddisfano solo richieste operator, e i ruoli non-operator + devono comunque richiedere ambiti con il prefisso del proprio ruolo Tratta il codice di configurazione come una password finché è valido. -### Approvare un dispositivo nodo +### Approvare un dispositivo Node ```bash openclaw devices list @@ -103,34 +103,40 @@ openclaw devices approve openclaw devices reject ``` -Se lo stesso dispositivo ritenta con dettagli di autenticazione diversi (ad esempio -ruolo/scope/chiave pubblica diversi), la precedente richiesta in sospeso viene sostituita e viene creato un nuovo +Se lo stesso dispositivo riprova con dettagli di autenticazione diversi (ad esempio +ruolo/ambiti/chiave pubblica differenti), la precedente richiesta in sospeso viene sostituita e viene creato un nuovo `requestId`. -### Archiviazione dello stato di pairing del nodo +Importante: un dispositivo già associato non ottiene automaticamente un accesso più ampio. Se +si riconnette richiedendo più ambiti o un ruolo più esteso, OpenClaw mantiene +l’approvazione esistente così com’è e crea una nuova richiesta di aggiornamento in sospeso. Usa +`openclaw devices list` per confrontare l’accesso attualmente approvato con quello appena +richiesto prima di approvare. + +### Archiviazione dello stato di associazione del Node Memorizzato in `~/.openclaw/devices/`: -- `pending.json` (a breve durata; le richieste in sospeso scadono) -- `paired.json` (dispositivi abbinati + token) +- `pending.json` (temporaneo; le richieste in sospeso scadono) +- `paired.json` (dispositivi associati + token) ### Note -- L'API legacy `node.pair.*` (CLI: `openclaw nodes pending|approve|reject|rename`) è un - archivio di pairing separato di proprietà del gateway. I nodi WS richiedono comunque il pairing del dispositivo. -- Il record di pairing è la fonte di verità durevole per i ruoli approvati. I token attivi del - dispositivo restano vincolati a quell'insieme di ruoli approvati; una voce token isolata +- L’API legacy `node.pair.*` (CLI: `openclaw nodes pending|approve|reject|rename`) è un + archivio di associazione separato gestito dal gateway. I Node WS richiedono comunque l’associazione del dispositivo. +- Il record di associazione è la fonte di verità durevole per i ruoli approvati. I token del + dispositivo attivi restano limitati a quell’insieme di ruoli approvati; una voce token errata al di fuori dei ruoli approvati non crea nuovo accesso. ## Documenti correlati -- Modello di sicurezza + prompt injection: [Security](/gateway/security) -- Aggiornare in sicurezza (esegui doctor): [Updating](/install/updating) +- Modello di sicurezza + prompt injection: [Security](/it/gateway/security) +- Aggiornare in sicurezza (esegui doctor): [Updating](/it/install/updating) - Configurazioni dei canali: - - Telegram: [Telegram](/channels/telegram) - - WhatsApp: [WhatsApp](/channels/whatsapp) - - Signal: [Signal](/channels/signal) - - BlueBubbles (iMessage): [BlueBubbles](/channels/bluebubbles) - - iMessage (legacy): [iMessage](/channels/imessage) - - Discord: [Discord](/channels/discord) - - Slack: [Slack](/channels/slack) + - Telegram: [Telegram](/it/channels/telegram) + - WhatsApp: [WhatsApp](/it/channels/whatsapp) + - Signal: [Signal](/it/channels/signal) + - BlueBubbles (iMessage): [BlueBubbles](/it/channels/bluebubbles) + - iMessage (legacy): [iMessage](/it/channels/imessage) + - Discord: [Discord](/it/channels/discord) + - Slack: [Slack](/it/channels/slack) diff --git a/docs/it/channels/telegram.md b/docs/it/channels/telegram.md index 9eebe106c..767d65dac 100644 --- a/docs/it/channels/telegram.md +++ b/docs/it/channels/telegram.md @@ -1,30 +1,30 @@ --- read_when: - - Quando lavori su funzionalità Telegram o webhook + - Lavorare sulle funzionalità di Telegram o sui Webhook summary: Stato del supporto del bot Telegram, capacità e configurazione title: Telegram x-i18n: - generated_at: "2026-04-05T13:47:50Z" + generated_at: "2026-04-20T08:30:49Z" model: gpt-5.4 provider: openai - source_hash: 39fbf328375fbc5d08ec2e3eed58b19ee0afa102010ecbc02e074a310ced157e + source_hash: b9903fae98bca0c345aa86d5c29015539c375442524a34d26bd28181470b8477 source_path: channels/telegram.md workflow: 15 --- # Telegram (Bot API) -Stato: pronto per la produzione per DM bot + gruppi tramite grammY. Il long polling è la modalità predefinita; la modalità webhook è opzionale. +Stato: pronto per la produzione per DM bot + gruppi tramite grammY. Il long polling è la modalità predefinita; la modalità Webhook è facoltativa. - La policy DM predefinita per Telegram è l'abbinamento. + Il criterio DM predefinito per Telegram è l'abbinamento. - - Diagnostica cross-channel e playbook di riparazione. + + Diagnostica tra canali e procedure di ripristino. - - Modelli di configurazione completi del canale ed esempi. + + Modelli ed esempi completi di configurazione dei canali. @@ -32,13 +32,13 @@ Stato: pronto per la produzione per DM bot + gruppi tramite grammY. Il long poll - Apri Telegram e avvia una chat con **@BotFather** (conferma che l'handle sia esattamente `@BotFather`). + Apri Telegram e chatta con **@BotFather** (verifica che l'handle sia esattamente `@BotFather`). Esegui `/newbot`, segui le istruzioni e salva il token. - + ```json5 { @@ -54,7 +54,7 @@ Stato: pronto per la produzione per DM bot + gruppi tramite grammY. Il long poll ``` Fallback env: `TELEGRAM_BOT_TOKEN=...` (solo account predefinito). - Telegram **non** usa `openclaw channels login telegram`; configura il token in config/env, poi avvia il gateway. + Telegram **non** usa `openclaw channels login telegram`; configura il token nel config/env, quindi avvia il gateway. @@ -76,32 +76,32 @@ openclaw pairing approve telegram -L'ordine di risoluzione del token è sensibile all'account. In pratica, i valori della config hanno priorità rispetto al fallback env, e `TELEGRAM_BOT_TOKEN` si applica solo all'account predefinito. +L'ordine di risoluzione del token è sensibile all'account. In pratica, i valori del config hanno priorità sul fallback env e `TELEGRAM_BOT_TOKEN` si applica solo all'account predefinito. ## Impostazioni lato Telegram - I bot Telegram usano per impostazione predefinita la **Modalità privacy**, che limita i messaggi di gruppo che ricevono. + I bot Telegram usano per impostazione predefinita la **Modalità Privacy**, che limita i messaggi di gruppo che possono ricevere. Se il bot deve vedere tutti i messaggi del gruppo, puoi: - disabilitare la modalità privacy tramite `/setprivacy`, oppure - rendere il bot amministratore del gruppo. - Quando modifichi la modalità privacy, rimuovi e riaggiungi il bot in ogni gruppo affinché Telegram applichi la modifica. + Quando modifichi la modalità privacy, rimuovi e riaggiungi il bot in ogni gruppo in modo che Telegram applichi la modifica. - + Lo stato di amministratore è controllato nelle impostazioni del gruppo Telegram. - I bot amministratori ricevono tutti i messaggi del gruppo, il che è utile per un comportamento di gruppo sempre attivo. + I bot amministratori ricevono tutti i messaggi del gruppo, il che è utile per un comportamento sempre attivo nel gruppo. - + - `/setjoingroups` per consentire/negare l'aggiunta ai gruppi - `/setprivacy` per il comportamento di visibilità nei gruppi @@ -112,7 +112,7 @@ L'ordine di risoluzione del token è sensibile all'account. In pratica, i valori ## Controllo degli accessi e attivazione - + `channels.telegram.dmPolicy` controlla l'accesso ai messaggi diretti: - `pairing` (predefinito) @@ -121,20 +121,20 @@ L'ordine di risoluzione del token è sensibile all'account. In pratica, i valori - `disabled` `channels.telegram.allowFrom` accetta ID utente Telegram numerici. I prefissi `telegram:` / `tg:` sono accettati e normalizzati. - `dmPolicy: "allowlist"` con `allowFrom` vuoto blocca tutti i DM ed è rifiutato dalla validazione della config. - L'onboarding accetta input `@username` e lo risolve in ID numerici. - Se hai eseguito un aggiornamento e la tua config contiene voci allowlist `@username`, esegui `openclaw doctor --fix` per risolverle (best-effort; richiede un token bot Telegram). - Se in precedenza ti affidavi ai file allowlist del pairing-store, `openclaw doctor --fix` può recuperare le voci in `channels.telegram.allowFrom` nei flussi allowlist (per esempio quando `dmPolicy: "allowlist"` non ha ancora ID espliciti). + `dmPolicy: "allowlist"` con `allowFrom` vuoto blocca tutti i DM ed è rifiutato dalla validazione della configurazione. + La configurazione richiede solo ID utente numerici. + Se hai effettuato un aggiornamento e il tuo config contiene voci allowlist `@username`, esegui `openclaw doctor --fix` per risolverle (best-effort; richiede un token bot Telegram). + Se in precedenza facevi affidamento sui file allowlist del pairing-store, `openclaw doctor --fix` può recuperare le voci in `channels.telegram.allowFrom` nei flussi allowlist (ad esempio quando `dmPolicy: "allowlist"` non ha ancora ID espliciti). - Per bot con un solo proprietario, preferisci `dmPolicy: "allowlist"` con ID `allowFrom` numerici espliciti per mantenere durevole la policy di accesso nella config (invece di dipendere da precedenti approvazioni di abbinamento). + Per i bot con un solo proprietario, preferisci `dmPolicy: "allowlist"` con ID `allowFrom` numerici espliciti per mantenere duraturo il criterio di accesso nella configurazione (invece di dipendere da approvazioni di abbinamento precedenti). Confusione comune: l'approvazione dell'abbinamento DM non significa "questo mittente è autorizzato ovunque". - L'abbinamento concede solo l'accesso DM. L'autorizzazione del mittente nei gruppi deriva ancora da allowlist esplicite nella config. - Se vuoi "sono autorizzato una volta sola e funzionano sia i DM sia i comandi di gruppo", inserisci il tuo ID utente Telegram numerico in `channels.telegram.allowFrom`. + L'abbinamento concede solo l'accesso ai DM. L'autorizzazione del mittente nei gruppi continua invece a dipendere da allowlist esplicite nel config. + Se vuoi che "io sia autorizzato una volta sola e che funzionino sia i DM sia i comandi nei gruppi", inserisci il tuo ID utente Telegram numerico in `channels.telegram.allowFrom`. ### Trovare il tuo ID utente Telegram - Metodo più sicuro (senza bot di terze parti): + Più sicuro (nessun bot di terze parti): 1. Invia un DM al tuo bot. 2. Esegui `openclaw logs --follow`. @@ -150,13 +150,13 @@ curl "https://api.telegram.org/bot/getUpdates" - + Si applicano insieme due controlli: 1. **Quali gruppi sono consentiti** (`channels.telegram.groups`) - - nessuna config `groups`: - - con `groupPolicy: "open"`: qualsiasi gruppo può superare i controlli dell'ID gruppo - - con `groupPolicy: "allowlist"` (predefinito): i gruppi sono bloccati finché non aggiungi voci a `groups` (o `"*"`) + - nessun config `groups`: + - con `groupPolicy: "open"`: qualsiasi gruppo può superare i controlli sull'ID gruppo + - con `groupPolicy: "allowlist"` (predefinito): i gruppi sono bloccati finché non aggiungi voci in `groups` (o `"*"`) - `groups` configurato: agisce come allowlist (ID espliciti o `"*"`) 2. **Quali mittenti sono consentiti nei gruppi** (`channels.telegram.groupPolicy`) @@ -165,16 +165,16 @@ curl "https://api.telegram.org/bot/getUpdates" - `disabled` `groupAllowFrom` è usato per il filtro dei mittenti nei gruppi. Se non è impostato, Telegram usa `allowFrom` come fallback. - Le voci `groupAllowFrom` devono essere ID utente Telegram numerici (`telegram:` / `tg:` sono normalizzati). - Non inserire ID chat di gruppi o supergruppi Telegram in `groupAllowFrom`. Gli ID chat negativi vanno sotto `channels.telegram.groups`. - Le voci non numeriche vengono ignorate per l'autorizzazione del mittente. - Limite di sicurezza (`2026.2.25+`): l'autorizzazione del mittente nei gruppi **non** eredita le approvazioni DM del pairing-store. - L'abbinamento resta solo per i DM. Per i gruppi, imposta `groupAllowFrom` o `allowFrom` per gruppo/per topic. - Se `groupAllowFrom` non è impostato, Telegram usa come fallback `allowFrom` della config, non il pairing store. - Modello pratico per bot con un solo proprietario: imposta il tuo ID utente in `channels.telegram.allowFrom`, lascia `groupAllowFrom` non impostato e consenti i gruppi target sotto `channels.telegram.groups`. - Nota runtime: se `channels.telegram` manca completamente, i valori predefiniti di runtime sono fail-closed con `groupPolicy="allowlist"` a meno che `channels.defaults.groupPolicy` non sia impostato esplicitamente. + Le voci di `groupAllowFrom` devono essere ID utente Telegram numerici (i prefissi `telegram:` / `tg:` sono normalizzati). + Non inserire ID chat di gruppo o supergruppo Telegram in `groupAllowFrom`. Gli ID chat negativi appartengono a `channels.telegram.groups`. + Le voci non numeriche sono ignorate per l'autorizzazione del mittente. + Confine di sicurezza (`2026.2.25+`): l'autorizzazione dei mittenti nei gruppi **non** eredita le approvazioni del pairing-store dei DM. + L'abbinamento resta solo per i DM. Per i gruppi, imposta `groupAllowFrom` oppure `allowFrom` per gruppo/per topic. + Se `groupAllowFrom` non è impostato, Telegram usa come fallback `allowFrom` dal config, non il pairing store. + Modello pratico per bot con un solo proprietario: imposta il tuo ID utente in `channels.telegram.allowFrom`, lascia `groupAllowFrom` non impostato e consenti i gruppi di destinazione in `channels.telegram.groups`. + Nota di runtime: se `channels.telegram` manca completamente, i valori predefiniti di runtime sono fail-closed con `groupPolicy="allowlist"`, a meno che `channels.defaults.groupPolicy` non sia impostato esplicitamente. - Esempio: consenti qualsiasi membro in un gruppo specifico: + Esempio: consenti qualsiasi membro in uno specifico gruppo: ```json5 { @@ -191,7 +191,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Esempio: consenti solo utenti specifici in un gruppo specifico: + Esempio: consenti solo utenti specifici in uno specifico gruppo: ```json5 { @@ -211,31 +211,31 @@ curl "https://api.telegram.org/bot/getUpdates" Errore comune: `groupAllowFrom` non è una allowlist di gruppi Telegram. - - Inserisci gli ID negativi di gruppi o supergruppi Telegram come `-1001234567890` sotto `channels.telegram.groups`. - - Inserisci ID utente Telegram come `8734062810` sotto `groupAllowFrom` quando vuoi limitare quali persone all'interno di un gruppo consentito possono attivare il bot. + - Inserisci ID negativi di gruppi o supergruppi Telegram come `-1001234567890` sotto `channels.telegram.groups`. + - Inserisci ID utente Telegram come `8734062810` sotto `groupAllowFrom` quando vuoi limitare quali persone, all'interno di un gruppo consentito, possono attivare il bot. - Usa `groupAllowFrom: ["*"]` solo quando vuoi che qualsiasi membro di un gruppo consentito possa parlare con il bot. - Le risposte nei gruppi richiedono una menzione per impostazione predefinita. + Per impostazione predefinita, le risposte nei gruppi richiedono una menzione. - La menzione può arrivare da: + La menzione può provenire da: - menzione nativa `@botusername`, oppure - pattern di menzione in: - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` - Interruttori dei comandi a livello di sessione: + Attivazioni dei comandi a livello di sessione: - `/activation always` - `/activation mention` - Questi aggiornano solo lo stato della sessione. Usa la config per la persistenza. + Questi aggiornano solo lo stato della sessione. Usa il config per la persistenza. - Esempio di config persistente: + Esempio di configurazione persistente: ```json5 { @@ -249,29 +249,29 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Ottenere l'ID chat del gruppo: + Ottenere l'ID della chat di gruppo: - - inoltra un messaggio del gruppo a `@userinfobot` / `@getidsbot` + - inoltra un messaggio di gruppo a `@userinfobot` / `@getidsbot` - oppure leggi `chat.id` da `openclaw logs --follow` - - oppure ispeziona Bot API `getUpdates` + - oppure ispeziona `getUpdates` della Bot API -## Comportamento runtime +## Comportamento di runtime - Telegram è gestito dal processo gateway. - Il routing è deterministico: le risposte in ingresso da Telegram tornano su Telegram (il modello non sceglie i canali). -- I messaggi in ingresso vengono normalizzati nell'envelope condivisa del canale con metadati di risposta e segnaposto media. +- I messaggi in ingresso sono normalizzati nell'envelope condivisa del canale con metadati di risposta e segnaposto per i media. - Le sessioni di gruppo sono isolate per ID gruppo. I topic del forum aggiungono `:topic:` per mantenere i topic isolati. -- I messaggi DM possono includere `message_thread_id`; OpenClaw li instrada con chiavi di sessione sensibili al thread e preserva l'ID del thread per le risposte. -- Il long polling usa grammY runner con sequenziamento per chat/per thread. La concorrenza complessiva del runner sink usa `agents.defaults.maxConcurrent`. -- Telegram Bot API non supporta le conferme di lettura (`sendReadReceipts` non si applica). +- I messaggi DM possono includere `message_thread_id`; OpenClaw li instrada con chiavi di sessione sensibili al thread e preserva l'ID thread per le risposte. +- Il long polling usa il runner grammY con sequenziamento per chat/per thread. La concorrenza complessiva del runner sink usa `agents.defaults.maxConcurrent`. +- La Telegram Bot API non supporta le conferme di lettura (`sendReadReceipts` non si applica). -## Riferimento delle funzionalità +## Riferimento funzionalità - + OpenClaw può trasmettere risposte parziali in tempo reale: - chat dirette: messaggio di anteprima + `editMessageText` @@ -281,23 +281,23 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.streaming` è `off | partial | block | progress` (predefinito: `partial`) - `progress` corrisponde a `partial` su Telegram (compatibilità con la denominazione cross-channel) - - i valori legacy `channels.telegram.streamMode` e booleani `streaming` vengono mappati automaticamente + - i valori legacy `channels.telegram.streamMode` e booleani `streaming` sono mappati automaticamente Per risposte solo testo: - - DM: OpenClaw mantiene lo stesso messaggio di anteprima ed esegue una modifica finale in place (nessun secondo messaggio) - - gruppo/topic: OpenClaw mantiene lo stesso messaggio di anteprima ed esegue una modifica finale in place (nessun secondo messaggio) + - DM: OpenClaw mantiene lo stesso messaggio di anteprima ed esegue una modifica finale sul posto (nessun secondo messaggio) + - gruppo/topic: OpenClaw mantiene lo stesso messaggio di anteprima ed esegue una modifica finale sul posto (nessun secondo messaggio) - Per risposte complesse (per esempio payload media), OpenClaw torna alla normale consegna finale e poi rimuove il messaggio di anteprima. + Per risposte complesse (ad esempio payload media), OpenClaw usa come fallback la normale consegna finale e poi rimuove il messaggio di anteprima. - Lo streaming di anteprima è separato dallo streaming a blocchi. Quando lo streaming a blocchi è abilitato esplicitamente per Telegram, OpenClaw salta lo stream di anteprima per evitare il doppio streaming. + L'anteprima in streaming è separata dal block streaming. Quando il block streaming è esplicitamente abilitato per Telegram, OpenClaw salta l'anteprima in streaming per evitare uno streaming doppio. - Se il trasporto draft nativo non è disponibile/viene rifiutato, OpenClaw usa automaticamente `sendMessage` + `editMessageText` come fallback. + Se il trasporto bozza nativo non è disponibile/viene rifiutato, OpenClaw usa automaticamente come fallback `sendMessage` + `editMessageText`. - Stream di reasoning solo Telegram: + Flusso di ragionamento solo Telegram: - - `/reasoning stream` invia il reasoning all'anteprima live durante la generazione - - la risposta finale viene inviata senza testo di reasoning + - `/reasoning stream` invia il ragionamento all'anteprima live durante la generazione + - la risposta finale viene inviata senza testo di ragionamento @@ -305,7 +305,7 @@ curl "https://api.telegram.org/bot/getUpdates" Il testo in uscita usa Telegram `parse_mode: "HTML"`. - Il testo in stile Markdown viene renderizzato in HTML sicuro per Telegram. - - L'HTML grezzo del modello viene escapato per ridurre gli errori di parsing di Telegram. + - L'HTML grezzo del modello viene escaped per ridurre gli errori di parsing di Telegram. - Se Telegram rifiuta l'HTML parsato, OpenClaw ritenta come testo semplice. Le anteprime dei link sono abilitate per impostazione predefinita e possono essere disabilitate con `channels.telegram.linkPreview: false`. @@ -336,7 +336,7 @@ curl "https://api.telegram.org/bot/getUpdates" Regole: - - i nomi vengono normalizzati (rimozione di `/` iniziale, minuscolo) + - i nomi sono normalizzati (rimozione di `/` iniziale, minuscolo) - pattern valido: `a-z`, `0-9`, `_`, lunghezza `1..32` - i comandi personalizzati non possono sovrascrivere i comandi nativi - conflitti/duplicati vengono saltati e registrati nei log @@ -344,13 +344,13 @@ curl "https://api.telegram.org/bot/getUpdates" Note: - i comandi personalizzati sono solo voci di menu; non implementano automaticamente il comportamento - - i comandi plugin/Skills possono comunque funzionare se digitati, anche se non mostrati nel menu Telegram + - i comandi plugin/Skills possono comunque funzionare se digitati, anche se non sono mostrati nel menu Telegram - Se i comandi nativi sono disabilitati, i comandi built-in vengono rimossi. I comandi personalizzati/plugin possono comunque essere registrati se configurati. + Se i comandi nativi sono disabilitati, i built-in vengono rimossi. I comandi personalizzati/plugin possono comunque essere registrati se configurati. Errori comuni di configurazione: - - `setMyCommands failed` con `BOT_COMMANDS_TOO_MUCH` significa che il menu Telegram è ancora troppo pieno dopo il trimming; riduci plugin/Skills/comandi personalizzati o disabilita `channels.telegram.commands.native`. + - `setMyCommands failed` con `BOT_COMMANDS_TOO_MUCH` significa che il menu Telegram continua a essere troppo pieno dopo il trimming; riduci i comandi plugin/Skills/personalizzati o disabilita `channels.telegram.commands.native`. - `setMyCommands failed` con errori di rete/fetch di solito significa che il DNS/HTTPS in uscita verso `api.telegram.org` è bloccato. ### Comandi di abbinamento dispositivo (plugin `device-pair`) @@ -359,15 +359,15 @@ curl "https://api.telegram.org/bot/getUpdates" 1. `/pair` genera un codice di configurazione 2. incolla il codice nell'app iOS - 3. `/pair pending` elenca le richieste in attesa (inclusi ruolo/scopes) + 3. `/pair pending` elenca le richieste in sospeso (inclusi ruolo/scopes) 4. approva la richiesta: - - `/pair approve ` per approvazione esplicita - - `/pair approve` quando c'è una sola richiesta in attesa + - `/pair approve ` per l'approvazione esplicita + - `/pair approve` quando c'è una sola richiesta in sospeso - `/pair approve latest` per la più recente - Il codice di configurazione contiene un token bootstrap a vita breve. Il passaggio bootstrap built-in mantiene il token del nodo primario con `scopes: []`; qualsiasi token operatore passato resta limitato a `operator.approvals`, `operator.read`, `operator.talk.secrets` e `operator.write`. I controlli bootstrap degli scope usano prefissi di ruolo, quindi quella allowlist operatore soddisfa solo richieste operatore; i ruoli non operatore richiedono ancora scope sotto il proprio prefisso di ruolo. + Il codice di configurazione contiene un token bootstrap a breve durata. Il passaggio bootstrap integrato mantiene il token del Node primario con `scopes: []`; qualsiasi token operatore trasferito resta limitato a `operator.approvals`, `operator.read`, `operator.talk.secrets` e `operator.write`. I controlli degli scope bootstrap usano prefissi basati sul ruolo, quindi tale allowlist dell'operatore soddisfa solo le richieste dell'operatore; i ruoli non operatore richiedono comunque scopes sotto il proprio prefisso di ruolo. - Se un dispositivo riprova con dettagli auth cambiati (per esempio ruolo/scopes/chiave pubblica), la precedente richiesta in attesa viene sostituita e la nuova richiesta usa un `requestId` diverso. Esegui di nuovo `/pair pending` prima di approvare. + Se un dispositivo riprova con dettagli di autenticazione modificati (ad esempio ruolo/scopes/chiave pubblica), la precedente richiesta in sospeso viene sostituita e la nuova richiesta usa un `requestId` diverso. Esegui di nuovo `/pair pending` prima di approvare. Maggiori dettagli: [Abbinamento](/it/channels/pairing#pair-via-telegram-recommended-for-ios). @@ -406,7 +406,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Ambiti: + Scopes: - `off` - `dm` @@ -440,13 +440,13 @@ curl "https://api.telegram.org/bot/getUpdates" - Le azioni tool Telegram includono: + Le azioni strumento Telegram includono: - - `sendMessage` (`to`, `content`, opzionale `mediaUrl`, `replyToMessageId`, `messageThreadId`) + - `sendMessage` (`to`, `content`, facoltativi `mediaUrl`, `replyToMessageId`, `messageThreadId`) - `react` (`chatId`, `messageId`, `emoji`) - `deleteMessage` (`chatId`, `messageId`) - `editMessage` (`chatId`, `messageId`, `content`) - - `createForumTopic` (`chatId`, `name`, opzionale `iconColor`, `iconCustomEmojiId`) + - `createForumTopic` (`chatId`, `name`, facoltativi `iconColor`, `iconCustomEmojiId`) Le azioni messaggio del canale espongono alias ergonomici (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). @@ -458,9 +458,9 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.actions.sticker` (predefinito: disabilitato) Nota: `edit` e `topic-create` sono attualmente abilitati per impostazione predefinita e non hanno toggle `channels.telegram.actions.*` separati. - Gli invii runtime usano lo snapshot attivo di config/secrets (avvio/ricarica), quindi i percorsi azione non eseguono una nuova risoluzione ad hoc di SecretRef per ogni invio. + Gli invii a runtime usano l'istantanea attiva di config/segreti (avvio/ricarica), quindi i percorsi azione non eseguono una nuova risoluzione ad hoc di SecretRef per ogni invio. - Semantica di rimozione delle reazioni: [/tools/reactions](/tools/reactions) + Semantica della rimozione delle reazioni: [/tools/reactions](/it/tools/reactions) @@ -484,19 +484,19 @@ curl "https://api.telegram.org/bot/getUpdates" Supergruppi forum: - le chiavi di sessione del topic aggiungono `:topic:` - - le risposte e l'indicatore di digitazione puntano al thread del topic + - le risposte e la digitazione sono indirizzate al thread del topic - percorso config del topic: `channels.telegram.groups..topics.` Caso speciale del topic generale (`threadId=1`): - - l'invio dei messaggi omette `message_thread_id` (Telegram rifiuta `sendMessage(...thread_id=1)`) + - gli invii di messaggi omettono `message_thread_id` (Telegram rifiuta `sendMessage(...thread_id=1)`) - le azioni di digitazione includono comunque `message_thread_id` - Ereditarietà dei topic: le voci del topic ereditano le impostazioni del gruppo salvo override (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). - `agentId` è solo per topic e non eredita dai valori predefiniti del gruppo. + Ereditarietà dei topic: le voci topic ereditano le impostazioni del gruppo salvo override (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). + `agentId` è solo del topic e non viene ereditato dalle impostazioni predefinite del gruppo. - **Routing agente per topic**: ogni topic può instradare verso un agente diverso impostando `agentId` nella config del topic. Questo fornisce a ogni topic il proprio workspace, memoria e sessione isolati. Esempio: + **Instradamento agente per topic**: ogni topic può essere instradato a un agente diverso impostando `agentId` nel config del topic. Questo assegna a ogni topic il proprio workspace, memoria e sessione isolati. Esempio: ```json5 { @@ -506,7 +506,7 @@ curl "https://api.telegram.org/bot/getUpdates" "-1001234567890": { topics: { "1": { agentId: "main" }, // Topic generale → agente main - "3": { agentId: "zu" }, // Topic dev → agente zu + "3": { agentId: "zu" }, // Topic sviluppo → agente zu "5": { agentId: "coder" } // Revisione codice → agente coder } } @@ -569,13 +569,13 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Attualmente questo è limitato ai topic del forum in gruppi e supergruppi. + Questo è attualmente limitato ai topic del forum in gruppi e supergruppi. - **Avvio ACP vincolato al thread dalla chat**: + **Spawn ACP vincolato al thread dalla chat**: - `/acp spawn --thread here|auto` può associare il topic Telegram corrente a una nuova sessione ACP. - - I messaggi successivi nel topic vengono instradati direttamente alla sessione ACP associata (non è richiesto `/acp steer`). - - OpenClaw fissa il messaggio di conferma dell'avvio nel topic dopo un'associazione riuscita. + - I messaggi successivi nel topic vengono instradati direttamente alla sessione ACP associata (senza bisogno di `/acp steer`). + - OpenClaw fissa il messaggio di conferma dello spawn nel topic dopo un binding riuscito. - Richiede `channels.telegram.threadBindings.spawnAcpSessions=true`. Il contesto del template include: @@ -583,9 +583,9 @@ curl "https://api.telegram.org/bot/getUpdates" - `MessageThreadId` - `IsForum` - Comportamento del thread DM: + Comportamento thread nei DM: - - le chat private con `message_thread_id` mantengono il routing DM ma usano chiavi di sessione e target di risposta sensibili al thread. + - le chat private con `message_thread_id` mantengono l'instradamento DM ma usano chiavi di sessione e destinazioni di risposta sensibili al thread. @@ -625,7 +625,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Le video note non supportano didascalie; il testo del messaggio fornito viene inviato separatamente. + Le video note non supportano didascalie; l'eventuale testo del messaggio viene inviato separatamente. ### Sticker @@ -635,7 +635,7 @@ curl "https://api.telegram.org/bot/getUpdates" - TGS animato: ignorato - WEBM video: ignorato - Campi di contesto sticker: + Campi del contesto sticker: - `Sticker.emoji` - `Sticker.setName` @@ -647,7 +647,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `~/.openclaw/telegram/sticker-cache.json` - Gli sticker vengono descritti una volta (quando possibile) e memorizzati nella cache per ridurre chiamate ripetute alla vision. + Gli sticker vengono descritti una sola volta (quando possibile) e memorizzati in cache per ridurre le chiamate ripetute alla visione. Abilita le azioni sticker: @@ -663,7 +663,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Azione di invio sticker: + Azione per inviare uno sticker: ```json5 { @@ -674,7 +674,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Cerca sticker nella cache: + Cerca negli sticker in cache: ```json5 { @@ -692,7 +692,7 @@ curl "https://api.telegram.org/bot/getUpdates" Quando abilitato, OpenClaw mette in coda eventi di sistema come: - - `Telegram reaction added: 👍 by Alice (@alice) on msg 42` + - `Reazione Telegram aggiunta: 👍 da Alice (@alice) al msg 42` Config: @@ -701,40 +701,40 @@ curl "https://api.telegram.org/bot/getUpdates" Note: - - `own` significa solo reazioni utente ai messaggi inviati dal bot (best-effort tramite cache dei messaggi inviati). + - `own` significa solo reazioni dell'utente ai messaggi inviati dal bot (best-effort tramite cache dei messaggi inviati). - Gli eventi di reazione rispettano comunque i controlli di accesso Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); i mittenti non autorizzati vengono scartati. - Telegram non fornisce ID thread negli aggiornamenti di reazione. - i gruppi non forum vengono instradati alla sessione della chat di gruppo - - i gruppi forum vengono instradati alla sessione del topic generale del gruppo (`:topic:1`), non al topic di origine esatto + - i gruppi forum vengono instradati alla sessione del topic generale del gruppo (`:topic:1`), non all'esatto topic di origine - `allowed_updates` per polling/webhook include automaticamente `message_reaction`. + `allowed_updates` per polling/Webhook include automaticamente `message_reaction`. - - `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: - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - - fallback emoji identità agente (`agents.list[].identity.emoji`, altrimenti "👀") + - fallback all'emoji identità dell'agente (`agents.list[].identity.emoji`, altrimenti "👀") Note: - - Telegram si aspetta emoji unicode (per esempio "👀"). + - Telegram si aspetta emoji unicode (ad esempio "👀"). - Usa `""` per disabilitare la reazione per un canale o account. - - Le scritture della config del canale sono abilitate per impostazione predefinita (`configWrites !== false`). + + Le scritture della configurazione del canale sono abilitate per impostazione predefinita (`configWrites !== false`). Le scritture attivate da Telegram includono: - eventi di migrazione del gruppo (`migrate_to_chat_id`) per aggiornare `channels.telegram.groups` - - `/config set` e `/config unset` (richiede l'abilitazione del comando) + - `/config set` e `/config unset` (richiede l'abilitazione dei comandi) Disabilita: @@ -750,45 +750,45 @@ curl "https://api.telegram.org/bot/getUpdates" - + Predefinito: long polling. - Modalità webhook: + Modalità Webhook: - imposta `channels.telegram.webhookUrl` - - imposta `channels.telegram.webhookSecret` (obbligatorio quando è impostato l'URL webhook) - - opzionale `channels.telegram.webhookPath` (predefinito `/telegram-webhook`) - - opzionale `channels.telegram.webhookHost` (predefinito `127.0.0.1`) - - opzionale `channels.telegram.webhookPort` (predefinito `8787`) + - imposta `channels.telegram.webhookSecret` (obbligatorio quando è impostato l'URL Webhook) + - `channels.telegram.webhookPath` facoltativo (predefinito `/telegram-webhook`) + - `channels.telegram.webhookHost` facoltativo (predefinito `127.0.0.1`) + - `channels.telegram.webhookPort` facoltativo (predefinito `8787`) - Il listener locale predefinito per la modalità webhook si collega a `127.0.0.1:8787`. + Il listener locale predefinito per la modalità Webhook si associa a `127.0.0.1:8787`. Se il tuo endpoint pubblico è diverso, metti un reverse proxy davanti e punta `webhookUrl` all'URL pubblico. - Imposta `webhookHost` (per esempio `0.0.0.0`) quando hai intenzionalmente bisogno di ingress esterno. + Imposta `webhookHost` (ad esempio `0.0.0.0`) quando hai intenzionalmente bisogno di ingress esterno. - + - il valore predefinito di `channels.telegram.textChunkLimit` è 4000. - `channels.telegram.chunkMode="newline"` preferisce i confini dei paragrafi (righe vuote) prima della suddivisione per lunghezza. - - `channels.telegram.mediaMaxMb` (predefinito 100) limita la dimensione dei media Telegram in ingresso e in uscita. + - `channels.telegram.mediaMaxMb` (predefinito 100) impone un limite alla dimensione dei media Telegram in ingresso e in uscita. - `channels.telegram.timeoutSeconds` sovrascrive il timeout del client Telegram API (se non impostato, si applica il valore predefinito di grammY). - la cronologia del contesto di gruppo usa `channels.telegram.historyLimit` o `messages.groupChat.historyLimit` (predefinito 50); `0` la disabilita. - - il contesto supplementare di risposta/citazione/inoltro è attualmente passato così come ricevuto. - - le allowlist Telegram regolano principalmente chi può attivare l'agente, non un limite completo di redazione del contesto supplementare. - - controlli cronologia DM: + - il contesto supplementare di risposta/citazione/inoltro viene attualmente passato così come ricevuto. + - le allowlist Telegram limitano principalmente chi può attivare l'agente, non costituiscono un confine completo di redazione del contesto supplementare. + - controlli della cronologia DM: - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - la config `channels.telegram.retry` si applica agli helper di invio Telegram (CLI/tools/actions) per errori API in uscita recuperabili. + - la configurazione `channels.telegram.retry` si applica agli helper di invio Telegram (CLI/tools/actions) per gli errori recuperabili della API in uscita. - Il target di invio CLI può essere un ID chat numerico o un username: + La destinazione di invio CLI può essere un ID chat numerico o un username: ```bash openclaw message send --channel telegram --target 123456789 --message "hi" openclaw message send --channel telegram --target @name --message "hi" ``` - I sondaggi Telegram usano `openclaw message poll` e supportano i topic del forum: + I poll Telegram usano `openclaw message poll` e supportano i topic del forum: ```bash openclaw message poll --channel telegram --target 123456789 \ @@ -798,79 +798,79 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ --poll-duration-seconds 300 --poll-public ``` - Flag dei sondaggi solo Telegram: + Flag dei poll solo per Telegram: - `--poll-duration-seconds` (5-600) - `--poll-anonymous` - `--poll-public` - - `--thread-id` per i topic del forum (oppure usa un target `:topic:`) + - `--thread-id` per i topic del forum (oppure usa una destinazione `:topic:`) L'invio Telegram supporta anche: - `--buttons` per tastiere inline quando `channels.telegram.capabilities.inlineButtons` lo consente - - `--force-document` per inviare immagini e GIF in uscita come documenti invece che come foto compresse o upload di media animati + - `--force-document` per inviare immagini e GIF in uscita come documenti invece che come foto compresse o caricamenti di media animati Gating delle azioni: - - `channels.telegram.actions.sendMessage=false` disabilita i messaggi Telegram in uscita, inclusi i sondaggi - - `channels.telegram.actions.poll=false` disabilita la creazione di sondaggi Telegram lasciando abilitati i normali invii + - `channels.telegram.actions.sendMessage=false` disabilita i messaggi Telegram in uscita, inclusi i poll + - `channels.telegram.actions.poll=false` disabilita la creazione di poll Telegram lasciando abilitati i normali invii - Telegram supporta le approvazioni exec nei DM degli approvatori e può opzionalmente pubblicare i prompt di approvazione nella chat o nel topic di origine. + Telegram supporta le approvazioni exec nei DM degli approvatori e può facoltativamente pubblicare i prompt di approvazione nella chat o nel topic di origine. Percorso config: - `channels.telegram.execApprovals.enabled` - - `channels.telegram.execApprovals.approvers` (opzionale; usa come fallback gli ID proprietario numerici dedotti da `allowFrom` e `defaultTo` diretto quando possibile) + - `channels.telegram.execApprovals.approvers` (facoltativo; usa come fallback gli ID proprietario numerici dedotti da `allowFrom` e da `defaultTo` diretto quando possibile) - `channels.telegram.execApprovals.target` (`dm` | `channel` | `both`, predefinito: `dm`) - `agentFilter`, `sessionFilter` - Gli approvatori devono essere ID utente Telegram numerici. Telegram abilita automaticamente le approvazioni exec native quando `enabled` non è impostato o è `"auto"` e almeno un approvatore può essere risolto, o da `execApprovals.approvers` oppure dalla config numerica del proprietario dell'account (`allowFrom` e `defaultTo` dei messaggi diretti). Imposta `enabled: false` per disabilitare esplicitamente Telegram come client di approvazione nativo. Altrimenti le richieste di approvazione usano come fallback altre route di approvazione configurate o la policy di fallback per le approvazioni exec. + Gli approvatori devono essere ID utente Telegram numerici. Telegram abilita automaticamente le approvazioni exec native quando `enabled` non è impostato o è `"auto"` e può essere risolto almeno un approvatore, da `execApprovals.approvers` oppure dalla configurazione numerica del proprietario dell'account (`allowFrom` e `defaultTo` del messaggio diretto). Imposta `enabled: false` per disabilitare esplicitamente Telegram come client di approvazione nativo. In caso contrario, le richieste di approvazione usano come fallback altre route di approvazione configurate o il criterio di fallback delle approvazioni exec. - Telegram renderizza anche i pulsanti di approvazione condivisi usati dagli altri canali chat. L'adapter nativo Telegram aggiunge principalmente il routing ai DM degli approvatori, il fanout verso canali/topic e gli hint di digitazione prima della consegna. - Quando questi pulsanti sono presenti, rappresentano la UX di approvazione primaria; OpenClaw - dovrebbe includere un comando manuale `/approve` solo quando il risultato del tool indica - che le approvazioni in chat non sono disponibili o che l'approvazione manuale è l'unico percorso. + Telegram rende anche i pulsanti di approvazione condivisi usati dagli altri canali chat. L'adapter Telegram nativo aggiunge principalmente l'instradamento ai DM degli approvatori, il fanout verso canali/topic e gli indicatori di digitazione prima della consegna. + Quando questi pulsanti sono presenti, sono la UX di approvazione primaria; OpenClaw + dovrebbe includere un comando manuale `/approve` solo quando il risultato dello strumento indica + che le approvazioni via chat non sono disponibili o che l'approvazione manuale è l'unico percorso. Regole di consegna: - `target: "dm"` invia i prompt di approvazione solo ai DM degli approvatori risolti - - `target: "channel"` rimanda il prompt alla chat/topic Telegram di origine - - `target: "both"` invia ai DM degli approvatori e alla chat/topic Telegram di origine + - `target: "channel"` invia il prompt di nuovo alla chat/topic Telegram di origine + - `target: "both"` invia ai DM degli approvatori e alla chat/topic di origine Solo gli approvatori risolti possono approvare o negare. I non approvatori non possono usare `/approve` e non possono usare i pulsanti di approvazione Telegram. - Comportamento di risoluzione dell'approvazione: + Comportamento di risoluzione delle approvazioni: - - gli ID con prefisso `plugin:` vengono sempre risolti tramite approvazioni plugin. - - gli altri ID provano prima `exec.approval.resolve`. - - Se Telegram è autorizzato anche per approvazioni plugin e il gateway dice + - Gli ID con prefisso `plugin:` vengono sempre risolti tramite le approvazioni del plugin. + - Gli altri ID di approvazione provano prima `exec.approval.resolve`. + - Se Telegram è autorizzato anche per le approvazioni del plugin e il gateway dice che l'approvazione exec è sconosciuta/scaduta, Telegram ritenta una volta tramite `plugin.approval.resolve`. - - I rifiuti/errori reali delle approvazioni exec non ricadono silenziosamente sulla - risoluzione delle approvazioni plugin. + - I dinieghi/errori reali delle approvazioni exec non ricadono silenziosamente sulla + risoluzione delle approvazioni del plugin. - La consegna nel canale mostra il testo del comando nella chat, quindi abilita `channel` o `both` solo in gruppi/topic fidati. Quando il prompt arriva in un topic del forum, OpenClaw preserva il topic sia per il prompt di approvazione sia per il follow-up post-approvazione. Le approvazioni exec scadono per impostazione predefinita dopo 30 minuti. + La consegna nel canale mostra il testo del comando nella chat, quindi abilita `channel` o `both` solo in gruppi/topic fidati. Quando il prompt arriva in un topic del forum, OpenClaw preserva il topic sia per il prompt di approvazione sia per il follow-up post-approvazione. Le approvazioni exec scadono dopo 30 minuti per impostazione predefinita. - I pulsanti di approvazione inline dipendono anche dal fatto che `channels.telegram.capabilities.inlineButtons` consenta la superficie target (`dm`, `group` o `all`). + I pulsanti di approvazione inline dipendono anche dal fatto che `channels.telegram.capabilities.inlineButtons` consenta la superficie di destinazione (`dm`, `group` o `all`). - Documenti correlati: [Approvazioni exec](/tools/exec-approvals) + Documentazione correlata: [Approvazioni exec](/it/tools/exec-approvals) ## Controlli delle risposte di errore -Quando l'agente incontra un errore di consegna o del provider, Telegram può rispondere con il testo dell'errore oppure sopprimerlo. Due chiavi di config controllano questo comportamento: +Quando l'agente incontra un errore di consegna o del provider, Telegram può rispondere con il testo dell'errore oppure sopprimerlo. Due chiavi di configurazione controllano questo comportamento: | Key | Values | Default | Description | | ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- | -| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` invia un messaggio di errore amichevole alla chat. `silent` sopprime completamente le risposte di errore. | -| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Tempo minimo tra risposte di errore alla stessa chat. Previene spam di errori durante interruzioni del servizio. | +| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` invia un messaggio di errore amichevole nella chat. `silent` sopprime completamente le risposte di errore. | +| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Tempo minimo tra le risposte di errore nella stessa chat. Previene lo spam di errori durante le interruzioni. | -Sono supportati override per account, gruppo e topic (stessa ereditarietà delle altre chiavi di config Telegram). +Sono supportati override per account, per gruppo e per topic (stessa ereditarietà delle altre chiavi di configurazione Telegram). ```json5 { @@ -880,7 +880,7 @@ Sono supportati override per account, gruppo e topic (stessa ereditarietà delle errorCooldownMs: 120000, groups: { "-1001234567890": { - errorPolicy: "silent", // sopprimi errori in questo gruppo + errorPolicy: "silent", // sopprimi gli errori in questo gruppo }, }, }, @@ -895,34 +895,34 @@ Sono supportati override per account, gruppo e topic (stessa ereditarietà delle - Se `requireMention=false`, la modalità privacy di Telegram deve consentire piena visibilità. - BotFather: `/setprivacy` -> Disable - - poi rimuovi e riaggiungi il bot al gruppo - - `openclaw channels status` avvisa quando la config prevede messaggi di gruppo senza menzione. - - `openclaw channels status --probe` può controllare ID gruppo numerici espliciti; il carattere jolly `"*"` non può essere verificato come appartenenza. + - quindi rimuovi e riaggiungi il bot al gruppo + - `openclaw channels status` avvisa quando la configurazione prevede messaggi di gruppo senza menzione. + - `openclaw channels status --probe` può controllare ID di gruppo numerici espliciti; il carattere jolly `"*"` non può essere verificato come appartenenza. - test rapido della sessione: `/activation always`. - - quando `channels.telegram.groups` esiste, il gruppo deve essere elencato (oppure includere `"*"`) - - verifica l'appartenenza del bot al gruppo - - controlla i log: `openclaw logs --follow` per i motivi di skip + - quando esiste `channels.telegram.groups`, il gruppo deve essere elencato (oppure includere `"*"`) + - verifica che il bot sia membro del gruppo + - controlla i log: `openclaw logs --follow` per i motivi di esclusione - - autorizza l'identità del mittente (abbinamento e/o `allowFrom` numerico) - - l'autorizzazione dei comandi si applica comunque anche quando la policy di gruppo è `open` - - `setMyCommands failed` con `BOT_COMMANDS_TOO_MUCH` significa che il menu nativo ha troppe voci; riduci plugin/Skills/comandi personalizzati o disabilita i menu nativi + - autorizza la tua identità mittente (abbinamento e/o `allowFrom` numerico) + - l'autorizzazione dei comandi si applica comunque anche quando il criterio di gruppo è `open` + - `setMyCommands failed` con `BOT_COMMANDS_TOO_MUCH` significa che il menu nativo ha troppe voci; riduci i comandi plugin/Skills/personalizzati o disabilita i menu nativi - `setMyCommands failed` con errori di rete/fetch di solito indica problemi di raggiungibilità DNS/HTTPS verso `api.telegram.org` - - Node 22+ + fetch/proxy personalizzato può attivare un comportamento di abort immediato se i tipi AbortSignal non corrispondono. - - Alcuni host risolvono `api.telegram.org` prima in IPv6; un'uscita IPv6 difettosa può causare errori intermittenti delle API Telegram. + - Node 22+ + fetch/proxy personalizzato possono attivare un comportamento di abort immediato se i tipi AbortSignal non corrispondono. + - Alcuni host risolvono `api.telegram.org` prima in IPv6; un'uscita IPv6 difettosa può causare errori intermittenti della Telegram API. - Se i log includono `TypeError: fetch failed` o `Network request for 'getUpdates' failed!`, OpenClaw ora li ritenta come errori di rete recuperabili. - Su host VPS con uscita diretta/TLS instabile, instrada le chiamate Telegram API tramite `channels.telegram.proxy`: @@ -932,7 +932,7 @@ channels: proxy: socks5://:@proxy-host:1080 ``` - - Node 22+ usa come predefiniti `autoSelectFamily=true` (eccetto WSL2) e `dnsResultOrder=ipv4first`. + - Node 22+ usa per impostazione predefinita `autoSelectFamily=true` (eccetto WSL2) e `dnsResultOrder=ipv4first`. - Se il tuo host è WSL2 o funziona esplicitamente meglio con comportamento solo IPv4, forza la selezione della famiglia: ```yaml @@ -943,10 +943,10 @@ channels: ``` - Le risposte nell'intervallo benchmark RFC 2544 (`198.18.0.0/15`) sono già consentite - per i download dei media Telegram per impostazione predefinita. Se un fake-IP - fidato o un proxy trasparente riscrive `api.telegram.org` verso un altro - indirizzo privato/interno/special-use durante i download dei media, puoi scegliere - il bypass solo Telegram: + per impostazione predefinita per i download dei media Telegram. Se un fake-IP affidabile o un + proxy trasparente riscrive `api.telegram.org` verso un altro + indirizzo privato/interno/special-use durante i download dei media, puoi + attivare il bypass solo per Telegram: ```yaml channels: @@ -957,23 +957,19 @@ channels: - Lo stesso opt-in è disponibile per account in `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`. - - Se il tuo proxy risolve gli host media Telegram in `198.18.x.x`, lascia prima disattivato il flag - pericoloso. I media Telegram consentono già per impostazione predefinita l'intervallo benchmark RFC 2544. + - Se il tuo proxy risolve gli host media Telegram in `198.18.x.x`, lascia prima disattivato il + flag pericoloso. I media Telegram già consentono per impostazione predefinita l'intervallo + benchmark RFC 2544. - `channels.telegram.network.dangerouslyAllowPrivateNetwork` indebolisce le protezioni SSRF dei - media Telegram. Usalo solo in ambienti proxy fidati controllati - dall'operatore, come instradamento fake-IP di Clash, Mihomo o Surge, quando - sintetizzano risposte private o special-use fuori - dall'intervallo benchmark RFC 2544. Lascialo disattivato per il normale accesso - Telegram su internet pubblico. + `channels.telegram.network.dangerouslyAllowPrivateNetwork` indebolisce le protezioni SSRF dei media Telegram. Usalo solo per ambienti proxy affidabili controllati dall'operatore come Clash, Mihomo o routing fake-IP di Surge quando sintetizzano risposte private o special-use al di fuori dell'intervallo benchmark RFC 2544. Lascialo disattivato per il normale accesso Telegram su internet pubblico. - - Override di ambiente (temporanei): + - Override ambiente (temporanei): - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` - - Valida le risposte DNS: + - Convalida le risposte DNS: ```bash dig +short api.telegram.org A @@ -983,87 +979,87 @@ dig +short api.telegram.org AAAA -Altro aiuto: [Risoluzione dei problemi del canale](/channels/troubleshooting). +Altro aiuto: [Risoluzione dei problemi del canale](/it/channels/troubleshooting). -## Riferimenti della config Telegram +## Puntatori al riferimento della configurazione Telegram Riferimento principale: - `channels.telegram.enabled`: abilita/disabilita l'avvio del canale. - `channels.telegram.botToken`: token del bot (BotFather). -- `channels.telegram.tokenFile`: legge il token da un percorso di file regolare. I symlink sono rifiutati. +- `channels.telegram.tokenFile`: legge il token da un normale percorso file. I symlink vengono rifiutati. - `channels.telegram.dmPolicy`: `pairing | allowlist | open | disabled` (predefinito: pairing). -- `channels.telegram.allowFrom`: allowlist DM (ID utente Telegram numerici). `allowlist` richiede almeno un ID mittente. `open` richiede `"*"`. `openclaw doctor --fix` può risolvere voci legacy `@username` in ID e può recuperare voci allowlist dai file del pairing-store nei flussi di migrazione allowlist. -- `channels.telegram.actions.poll`: abilita o disabilita la creazione di sondaggi Telegram (predefinito: abilitato; richiede comunque `sendMessage`). -- `channels.telegram.defaultTo`: target Telegram predefinito usato dal CLI `--deliver` quando non viene fornito alcun `--reply-to` esplicito. +- `channels.telegram.allowFrom`: allowlist DM (ID utente Telegram numerici). `allowlist` richiede almeno un ID mittente. `open` richiede `"*"`. `openclaw doctor --fix` può risolvere le voci legacy `@username` in ID e può recuperare voci allowlist dai file pairing-store nei flussi di migrazione allowlist. +- `channels.telegram.actions.poll`: abilita o disabilita la creazione di poll Telegram (predefinito: abilitato; richiede comunque `sendMessage`). +- `channels.telegram.defaultTo`: destinazione Telegram predefinita usata da CLI `--deliver` quando non viene fornito alcun `--reply-to` esplicito. - `channels.telegram.groupPolicy`: `open | allowlist | disabled` (predefinito: allowlist). -- `channels.telegram.groupAllowFrom`: allowlist dei mittenti nei gruppi (ID utente Telegram numerici). `openclaw doctor --fix` può risolvere voci legacy `@username` in ID. Le voci non numeriche vengono ignorate in fase di auth. L'auth di gruppo non usa il fallback DM del pairing-store (`2026.2.25+`). +- `channels.telegram.groupAllowFrom`: allowlist dei mittenti nei gruppi (ID utente Telegram numerici). `openclaw doctor --fix` può risolvere le voci legacy `@username` in ID. Le voci non numeriche vengono ignorate al momento dell'autorizzazione. L'autorizzazione dei gruppi non usa il fallback del pairing-store DM (`2026.2.25+`). - Precedenza multi-account: - - Quando sono configurati due o più ID account, imposta `channels.telegram.defaultAccount` (oppure includi `channels.telegram.accounts.default`) per rendere esplicito il routing predefinito. - - Se nessuno dei due è impostato, OpenClaw usa come fallback il primo ID account normalizzato e `openclaw doctor` emette un avviso. + - Quando sono configurati due o più ID account, imposta `channels.telegram.defaultAccount` (oppure includi `channels.telegram.accounts.default`) per rendere esplicito l'instradamento predefinito. + - Se nessuno dei due è impostato, OpenClaw usa come fallback il primo ID account normalizzato e `openclaw doctor` mostra un avviso. - `channels.telegram.accounts.default.allowFrom` e `channels.telegram.accounts.default.groupAllowFrom` si applicano solo all'account `default`. - - Gli account nominati ereditano `channels.telegram.allowFrom` e `channels.telegram.groupAllowFrom` quando i valori a livello account non sono impostati. - - Gli account nominati non ereditano `channels.telegram.accounts.default.allowFrom` / `groupAllowFrom`. -- `channels.telegram.groups`: valori predefiniti per gruppo + allowlist (usa `"*"` per valori predefiniti globali). + - Gli account con nome ereditano `channels.telegram.allowFrom` e `channels.telegram.groupAllowFrom` quando i valori a livello di account non sono impostati. + - Gli account con nome non ereditano `channels.telegram.accounts.default.allowFrom` / `groupAllowFrom`. +- `channels.telegram.groups`: valori predefiniti per gruppo + allowlist (usa `"*"` per i valori predefiniti globali). - `channels.telegram.groups..groupPolicy`: override per gruppo di groupPolicy (`open | allowlist | disabled`). - - `channels.telegram.groups..requireMention`: gating delle menzioni predefinito. - - `channels.telegram.groups..skills`: filtro Skills (ometti = tutte le Skills, vuoto = nessuna). - - `channels.telegram.groups..allowFrom`: override per gruppo della allowlist mittenti. - - `channels.telegram.groups..systemPrompt`: prompt di sistema aggiuntivo per il gruppo. - - `channels.telegram.groups..enabled`: disabilita il gruppo quando `false`. - - `channels.telegram.groups..topics..*`: override per topic (campi di gruppo + `agentId` solo topic). - - `channels.telegram.groups..topics..agentId`: instrada questo topic a un agente specifico (sovrascrive il routing a livello di gruppo e binding). + - `channels.telegram.groups..requireMention`: valore predefinito del gating per menzione. + - `channels.telegram.groups..skills`: filtro Skills (omesso = tutte le Skills, vuoto = nessuna). + - `channels.telegram.groups..allowFrom`: override dell'allowlist dei mittenti per gruppo. + - `channels.telegram.groups..systemPrompt`: system prompt aggiuntivo per il gruppo. + - `channels.telegram.groups..enabled`: disabilita il gruppo quando è `false`. + - `channels.telegram.groups..topics..*`: override per topic (campi del gruppo + `agentId` solo-topic). + - `channels.telegram.groups..topics..agentId`: instrada questo topic a un agente specifico (sovrascrive l'instradamento a livello di gruppo e tramite binding). - `channels.telegram.groups..topics..groupPolicy`: override per topic di groupPolicy (`open | allowlist | disabled`). -- `channels.telegram.groups..topics..requireMention`: override per topic del gating delle menzioni. -- `bindings[]` di primo livello con `type: "acp"` e ID topic canonico `chatId:topic:topicId` in `match.peer.id`: campi del binding persistente del topic ACP (vedi [Agenti ACP](/tools/acp-agents#channel-specific-settings)). +- `channels.telegram.groups..topics..requireMention`: override per topic del gating per menzione. +- `bindings[]` di primo livello con `type: "acp"` e ID topic canonico `chatId:topic:topicId` in `match.peer.id`: campi di binding persistente del topic ACP (vedi [Agenti ACP](/it/tools/acp-agents#channel-specific-settings)). - `channels.telegram.direct..topics..agentId`: instrada i topic DM a un agente specifico (stesso comportamento dei topic del forum). - `channels.telegram.execApprovals.enabled`: abilita Telegram come client di approvazione exec basato su chat per questo account. -- `channels.telegram.execApprovals.approvers`: ID utente Telegram autorizzati ad approvare o negare richieste exec. Opzionale quando `channels.telegram.allowFrom` o un `channels.telegram.defaultTo` diretto identifica già il proprietario. +- `channels.telegram.execApprovals.approvers`: ID utente Telegram autorizzati ad approvare o negare richieste exec. Facoltativo quando `channels.telegram.allowFrom` o un `channels.telegram.defaultTo` diretto identifica già il proprietario. - `channels.telegram.execApprovals.target`: `dm | channel | both` (predefinito: `dm`). `channel` e `both` preservano il topic Telegram di origine quando presente. -- `channels.telegram.execApprovals.agentFilter`: filtro opzionale per ID agente per i prompt di approvazione inoltrati. -- `channels.telegram.execApprovals.sessionFilter`: filtro opzionale per chiave di sessione (substring o regex) per i prompt di approvazione inoltrati. -- `channels.telegram.accounts..execApprovals`: override per account del routing delle approvazioni exec Telegram e dell'autorizzazione degli approvatori. +- `channels.telegram.execApprovals.agentFilter`: filtro facoltativo per ID agente per i prompt di approvazione inoltrati. +- `channels.telegram.execApprovals.sessionFilter`: filtro facoltativo per chiave sessione (sottostringa o regex) per i prompt di approvazione inoltrati. +- `channels.telegram.accounts..execApprovals`: override per account dell'instradamento delle approvazioni exec Telegram e dell'autorizzazione degli approvatori. - `channels.telegram.capabilities.inlineButtons`: `off | dm | group | all | allowlist` (predefinito: allowlist). - `channels.telegram.accounts..capabilities.inlineButtons`: override per account. -- `channels.telegram.commands.nativeSkills`: abilita/disabilita i comandi Skills nativi di Telegram. +- `channels.telegram.commands.nativeSkills`: abilita/disabilita i comandi nativi Skills di Telegram. - `channels.telegram.replyToMode`: `off | first | all` (predefinito: `off`). -- `channels.telegram.textChunkLimit`: dimensione del chunk in uscita (caratteri). +- `channels.telegram.textChunkLimit`: dimensione dei chunk in uscita (caratteri). - `channels.telegram.chunkMode`: `length` (predefinito) oppure `newline` per dividere sulle righe vuote (confini di paragrafo) prima del chunking per lunghezza. -- `channels.telegram.linkPreview`: attiva/disattiva le anteprime link per i messaggi in uscita (predefinito: true). -- `channels.telegram.streaming`: `off | partial | block | progress` (anteprima live dello stream; predefinito: `partial`; `progress` corrisponde a `partial`; `block` è compatibilità legacy della modalità anteprima). Lo streaming di anteprima Telegram usa un singolo messaggio di anteprima modificato in place. -- `channels.telegram.mediaMaxMb`: limite media Telegram in ingresso/uscita (MB, predefinito: 100). -- `channels.telegram.retry`: policy di retry per gli helper di invio Telegram (CLI/tools/actions) su errori API in uscita recuperabili (attempts, minDelayMs, maxDelayMs, jitter). -- `channels.telegram.network.autoSelectFamily`: override di Node autoSelectFamily (true=abilita, false=disabilita). Per impostazione predefinita è abilitato su Node 22+, con WSL2 impostato come predefinito su disabilitato. -- `channels.telegram.network.dnsResultOrder`: override dell'ordine dei risultati DNS (`ipv4first` o `verbatim`). Il valore predefinito su Node 22+ è `ipv4first`. -- `channels.telegram.network.dangerouslyAllowPrivateNetwork`: opt-in pericoloso per ambienti fidati con fake-IP o proxy trasparenti in cui i download dei media Telegram risolvono `api.telegram.org` verso indirizzi privati/interni/special-use fuori dall'intervallo benchmark RFC 2544 consentito per impostazione predefinita. -- `channels.telegram.proxy`: URL proxy per chiamate Bot API (SOCKS/HTTP). -- `channels.telegram.webhookUrl`: abilita la modalità webhook (richiede `channels.telegram.webhookSecret`). -- `channels.telegram.webhookSecret`: secret webhook (obbligatorio quando è impostato webhookUrl). -- `channels.telegram.webhookPath`: percorso webhook locale (predefinito `/telegram-webhook`). -- `channels.telegram.webhookHost`: host di bind webhook locale (predefinito `127.0.0.1`). -- `channels.telegram.webhookPort`: porta di bind webhook locale (predefinito `8787`). -- `channels.telegram.actions.reactions`: gating delle reazioni tool Telegram. -- `channels.telegram.actions.sendMessage`: gating degli invii di messaggi tool Telegram. -- `channels.telegram.actions.deleteMessage`: gating delle eliminazioni di messaggi tool Telegram. +- `channels.telegram.linkPreview`: attiva/disattiva le anteprime dei link per i messaggi in uscita (predefinito: true). +- `channels.telegram.streaming`: `off | partial | block | progress` (anteprima del flusso live; predefinito: `partial`; `progress` corrisponde a `partial`; `block` è compatibilità legacy con la modalità anteprima). Lo streaming di anteprima Telegram usa un singolo messaggio di anteprima che viene modificato sul posto. +- `channels.telegram.mediaMaxMb`: limite dei media Telegram in ingresso/uscita (MB, predefinito: 100). +- `channels.telegram.retry`: criterio di retry per gli helper di invio Telegram (CLI/tools/actions) sugli errori recuperabili della API in uscita (tentativi, minDelayMs, maxDelayMs, jitter). +- `channels.telegram.network.autoSelectFamily`: sovrascrive Node autoSelectFamily (true=abilita, false=disabilita). Per impostazione predefinita è abilitato su Node 22+, mentre su WSL2 è disabilitato per impostazione predefinita. +- `channels.telegram.network.dnsResultOrder`: sovrascrive l'ordine dei risultati DNS (`ipv4first` o `verbatim`). Per impostazione predefinita è `ipv4first` su Node 22+. +- `channels.telegram.network.dangerouslyAllowPrivateNetwork`: opt-in pericoloso per ambienti fidati fake-IP o transparent-proxy in cui i download dei media Telegram risolvono `api.telegram.org` verso indirizzi privati/interni/special-use al di fuori dell'intervallo benchmark RFC 2544 consentito per impostazione predefinita. +- `channels.telegram.proxy`: URL proxy per le chiamate Bot API (SOCKS/HTTP). +- `channels.telegram.webhookUrl`: abilita la modalità Webhook (richiede `channels.telegram.webhookSecret`). +- `channels.telegram.webhookSecret`: segreto Webhook (obbligatorio quando è impostato `webhookUrl`). +- `channels.telegram.webhookPath`: percorso Webhook locale (predefinito `/telegram-webhook`). +- `channels.telegram.webhookHost`: host di bind del Webhook locale (predefinito `127.0.0.1`). +- `channels.telegram.webhookPort`: porta di bind del Webhook locale (predefinito `8787`). +- `channels.telegram.actions.reactions`: gating delle reazioni dello strumento Telegram. +- `channels.telegram.actions.sendMessage`: gating degli invii di messaggi dello strumento Telegram. +- `channels.telegram.actions.deleteMessage`: gating delle eliminazioni di messaggi dello strumento Telegram. - `channels.telegram.actions.sticker`: gating delle azioni sticker Telegram — invio e ricerca (predefinito: false). -- `channels.telegram.reactionNotifications`: `off | own | all` — controlla quali reazioni attivano eventi di sistema (predefinito: `own` quando non impostato). -- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` — controlla la capacità di reazione dell'agente (predefinito: `minimal` quando non impostato). -- `channels.telegram.errorPolicy`: `reply | silent` — controlla il comportamento delle risposte di errore (predefinito: `reply`). Supporta override per account/gruppo/topic. -- `channels.telegram.errorCooldownMs`: ms minimi tra risposte di errore alla stessa chat (predefinito: `60000`). Previene spam di errori durante interruzioni del servizio. +- `channels.telegram.reactionNotifications`: `off | own | all` — controlla quali reazioni attivano eventi di sistema (predefinito: `own` se non impostato). +- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` — controlla la capacità di reazione dell'agente (predefinito: `minimal` se non impostato). +- `channels.telegram.errorPolicy`: `reply | silent` — controlla il comportamento delle risposte di errore (predefinito: `reply`). Sono supportati override per account/gruppo/topic. +- `channels.telegram.errorCooldownMs`: ms minimi tra risposte di errore nella stessa chat (predefinito: `60000`). Previene lo spam di errori durante le interruzioni. -- [Riferimento configurazione - Telegram](/gateway/configuration-reference#telegram) +- [Riferimento configurazione - Telegram](/it/gateway/configuration-reference#telegram) Campi Telegram specifici ad alto segnale: -- avvio/auth: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` deve puntare a un file regolare; i symlink sono rifiutati) +- avvio/autenticazione: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` deve puntare a un file normale; i symlink vengono rifiutati) - controllo accessi: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` di primo livello (`type: "acp"`) - approvazioni exec: `execApprovals`, `accounts.*.execApprovals` -- comando/menu: `commands.native`, `commands.nativeSkills`, `customCommands` +- comandi/menu: `commands.native`, `commands.nativeSkills`, `customCommands` - threading/risposte: `replyToMode` - streaming: `streaming` (anteprima), `blockStreaming` - formattazione/consegna: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` - media/rete: `mediaMaxMb`, `timeoutSeconds`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` -- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` +- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` - azioni/capacità: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` - reazioni: `reactionNotifications`, `reactionLevel` - errori: `errorPolicy`, `errorCooldownMs` @@ -1073,7 +1069,7 @@ Campi Telegram specifici ad alto segnale: - [Abbinamento](/it/channels/pairing) - [Gruppi](/it/channels/groups) -- [Sicurezza](/gateway/security) +- [Sicurezza](/it/gateway/security) - [Instradamento dei canali](/it/channels/channel-routing) -- [Instradamento multi-agent](/concepts/multi-agent) -- [Risoluzione dei problemi](/channels/troubleshooting) +- [Instradamento multi-agente](/it/concepts/multi-agent) +- [Risoluzione dei problemi](/it/channels/troubleshooting) diff --git a/docs/it/channels/troubleshooting.md b/docs/it/channels/troubleshooting.md index 5e7b0e956..45f6d0245 100644 --- a/docs/it/channels/troubleshooting.md +++ b/docs/it/channels/troubleshooting.md @@ -1,25 +1,25 @@ --- read_when: - - Il trasporto del canale risulta connesso ma le risposte non funzionano - - Hai bisogno di controlli specifici per il canale prima di consultare la documentazione approfondita del provider -summary: Risoluzione rapida dei problemi a livello di canale con firme di errore e correzioni per ciascun canale -title: Risoluzione dei problemi dei canali + - Il trasporto del canale risulta connesso ma le risposte non vengono inviate + - Sono necessari controlli specifici del canale prima di passare alla documentazione approfondita del provider +summary: Risoluzione rapida dei problemi a livello di canale con firme di errore e correzioni specifiche per canale +title: Risoluzione dei problemi del canale x-i18n: - generated_at: "2026-04-05T13:45:47Z" + generated_at: "2026-04-20T08:30:51Z" model: gpt-5.4 provider: openai - source_hash: d45d8220505ea420d970b20bc66e65216c2d7024b5736db1936421ffc0676e1f + source_hash: 0aef31742cd5cc4af3fa3d3ea1acba51875ad4a1423c0e8c87372c3df31b0528 source_path: channels/troubleshooting.md workflow: 15 --- -# Risoluzione dei problemi dei canali +# Risoluzione dei problemi del canale Usa questa pagina quando un canale si connette ma il comportamento non è corretto. ## Sequenza di comandi -Esegui prima questi, in questo ordine: +Esegui prima questi comandi, in questo ordine: ```bash openclaw status @@ -32,68 +32,69 @@ openclaw channels status --probe Baseline sana: - `Runtime: running` -- `RPC probe: ok` -- La probe del canale mostra il trasporto connesso e, dove supportato, `works` o `audit ok` +- `Connectivity probe: ok` +- `Capability: read-only`, `write-capable` oppure `admin-capable` +- Il probe del canale mostra il trasporto connesso e, dove supportato, `works` oppure `audit ok` ## WhatsApp ### Firme di errore di WhatsApp -| Sintomo | Controllo più rapido | Correzione | -| ------------------------------ | ---------------------------------------------------- | ------------------------------------------------------------ | -| Connesso ma nessuna risposta DM | `openclaw pairing list whatsapp` | Approva il mittente o cambia la policy/allowlist dei DM. | -| Messaggi di gruppo ignorati | Controlla `requireMention` + i pattern di menzione nella config | Menziona il bot o allenta la policy di menzione per quel gruppo. | -| Disconnessioni casuali/cicli di nuovo login | `openclaw channels status --probe` + log | Effettua di nuovo il login e verifica che la directory delle credenziali sia integra. | +| Sintomo | Controllo più rapido | Correzione | +| ------------------------------- | --------------------------------------------------- | ----------------------------------------------------------- | +| Connesso ma nessuna risposta nei DM | `openclaw pairing list whatsapp` | Approva il mittente oppure cambia il criterio DM/allowlist. | +| I messaggi di gruppo vengono ignorati | Controlla `requireMention` + i pattern di menzione nella config | Menziona il bot oppure allenta il criterio di menzione per quel gruppo. | +| Disconnessioni casuali/cicli di nuovo login | `openclaw channels status --probe` + log | Esegui di nuovo il login e verifica che la directory delle credenziali sia integra. | -Risoluzione completa dei problemi: [/channels/whatsapp#troubleshooting](/channels/whatsapp#troubleshooting) +Risoluzione completa dei problemi: [/channels/whatsapp#troubleshooting](/it/channels/whatsapp#troubleshooting) ## Telegram ### Firme di errore di Telegram -| Sintomo | Controllo più rapido | Correzione | -| ---------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------- | -| `/start` ma nessun flusso di risposta utilizzabile | `openclaw pairing list telegram` | Approva l'associazione o modifica la policy dei DM. | -| Bot online ma il gruppo resta silenzioso | Verifica il requisito di menzione e la modalità privacy del bot | Disabilita la modalità privacy per la visibilità nel gruppo oppure menziona il bot. | -| Errori di invio con errori di rete | Ispeziona i log per i fallimenti delle chiamate API di Telegram | Correggi il routing DNS/IPv6/proxy verso `api.telegram.org`. | -| `setMyCommands` rifiutato all'avvio | Ispeziona i log per `BOT_COMMANDS_TOO_MUCH` | Riduci i comandi Telegram di plugin/Skills/personalizzati oppure disabilita i menu nativi. | -| Hai effettuato un upgrade e l'allowlist ti blocca | `openclaw security audit` e le allowlist della config | Esegui `openclaw doctor --fix` oppure sostituisci `@username` con ID numerici del mittente. | +| Sintomo | Controllo più rapido | Correzione | +| ----------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------- | +| `/start` ma nessun flusso di risposta utilizzabile | `openclaw pairing list telegram` | Approva l'associazione oppure cambia il criterio DM. | +| Bot online ma il gruppo resta silenzioso | Verifica il requisito di menzione e la modalità privacy del bot | Disattiva la modalità privacy per la visibilità nel gruppo oppure menziona il bot. | +| Invii che falliscono con errori di rete | Ispeziona i log per gli errori delle chiamate API di Telegram | Correggi il routing DNS/IPv6/proxy verso `api.telegram.org`. | +| `setMyCommands` rifiutato all'avvio | Ispeziona i log per `BOT_COMMANDS_TOO_MUCH` | Riduci i comandi Telegram di plugin/Skills/personalizzati oppure disabilita i menu nativi. | +| Hai aggiornato e l'allowlist ti blocca | `openclaw security audit` e le allowlist nella config | Esegui `openclaw doctor --fix` oppure sostituisci `@username` con ID numerici del mittente. | -Risoluzione completa dei problemi: [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting) +Risoluzione completa dei problemi: [/channels/telegram#troubleshooting](/it/channels/telegram#troubleshooting) ## Discord ### Firme di errore di Discord -| Sintomo | Controllo più rapido | Correzione | -| ------------------------------ | ------------------------------------- | ------------------------------------------------------------- | -| Bot online ma nessuna risposta nel server | `openclaw channels status --probe` | Consenti server/canale e verifica l'intento del contenuto dei messaggi. | -| Messaggi di gruppo ignorati | Controlla nei log i blocchi dovuti alla regola di menzione | Menziona il bot o imposta `requireMention: false` per server/canale. | -| Risposte DM mancanti | `openclaw pairing list discord` | Approva l'associazione DM o regola la policy dei DM. | +| Sintomo | Controllo più rapido | Correzione | +| ------------------------------- | ----------------------------------------- | ------------------------------------------------------------- | +| Bot online ma nessuna risposta nel server | `openclaw channels status --probe` | Consenti il server/canale e verifica l'intento message content. | +| I messaggi di gruppo vengono ignorati | Controlla nei log gli scarti dovuti al filtro per menzione | Menziona il bot oppure imposta `requireMention: false` per server/canale. | +| Risposte DM mancanti | `openclaw pairing list discord` | Approva l'associazione DM oppure regola il criterio DM. | -Risoluzione completa dei problemi: [/channels/discord#troubleshooting](/channels/discord#troubleshooting) +Risoluzione completa dei problemi: [/channels/discord#troubleshooting](/it/channels/discord#troubleshooting) ## Slack ### Firme di errore di Slack -| Sintomo | Controllo più rapido | Correzione | -| ------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Sintomo | Controllo più rapido | Correzione | +| -------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | Socket mode connessa ma nessuna risposta | `openclaw channels status --probe` | Verifica app token + bot token e gli scope richiesti; controlla `botTokenStatus` / `appTokenStatus = configured_unavailable` nelle configurazioni basate su SecretRef. | -| DM bloccati | `openclaw pairing list slack` | Approva l'associazione o allenta la policy dei DM. | -| Messaggio del canale ignorato | Controlla `groupPolicy` e l'allowlist del canale | Consenti il canale o cambia la policy in `open`. | +| DM bloccati | `openclaw pairing list slack` | Approva l'associazione oppure allenta il criterio DM. | +| Messaggio del canale ignorato | Controlla `groupPolicy` e l'allowlist del canale | Consenti il canale oppure cambia il criterio in `open`. | -Risoluzione completa dei problemi: [/channels/slack#troubleshooting](/channels/slack#troubleshooting) +Risoluzione completa dei problemi: [/channels/slack#troubleshooting](/it/channels/slack#troubleshooting) ## iMessage e BlueBubbles ### Firme di errore di iMessage e BlueBubbles -| Sintomo | Controllo più rapido | Correzione | -| ------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------- | -| Nessun evento in ingresso | Verifica la raggiungibilità del webhook/server e i permessi dell'app | Correggi l'URL del webhook o lo stato del server BlueBubbles. | -| Può inviare ma non ricevere su macOS | Controlla i permessi privacy di macOS per l'automazione di Messages | Concedi di nuovo i permessi TCC e riavvia il processo del canale. | -| Mittente DM bloccato | `openclaw pairing list imessage` o `openclaw pairing list bluebubbles` | Approva l'associazione o aggiorna l'allowlist. | +| Sintomo | Controllo più rapido | Correzione | +| -------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------- | +| Nessun evento in ingresso | Verifica la raggiungibilità del webhook/server e i permessi dell'app | Correggi l'URL del webhook o lo stato del server BlueBubbles. | +| Può inviare ma non riceve su macOS | Controlla i permessi privacy di macOS per l'automazione di Messaggi | Concedi di nuovo i permessi TCC e riavvia il processo del canale. | +| Mittente DM bloccato | `openclaw pairing list imessage` o `openclaw pairing list bluebubbles` | Approva l'associazione oppure aggiorna l'allowlist. | Risoluzione completa dei problemi: @@ -104,11 +105,11 @@ Risoluzione completa dei problemi: ### Firme di errore di Signal -| Sintomo | Controllo più rapido | Correzione | -| ------------------------------ | ------------------------------------------ | ------------------------------------------------------- | -| Demone raggiungibile ma bot silenzioso | `openclaw channels status --probe` | Verifica URL/account del demone `signal-cli` e la modalità di ricezione. | -| DM bloccato | `openclaw pairing list signal` | Approva il mittente o regola la policy dei DM. | -| Le risposte nei gruppi non si attivano | Controlla l'allowlist del gruppo e i pattern di menzione | Aggiungi mittente/gruppo o allenta il gating. | +| Sintomo | Controllo più rapido | Correzione | +| ------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------- | +| Demone raggiungibile ma bot silenzioso | `openclaw channels status --probe` | Verifica l'URL/account del demone `signal-cli` e la modalità di ricezione. | +| DM bloccato | `openclaw pairing list signal` | Approva il mittente oppure regola il criterio DM. | +| Le risposte nei gruppi non si attivano | Controlla l'allowlist dei gruppi e i pattern di menzione | Aggiungi mittente/gruppo oppure allenta il filtro. | Risoluzione completa dei problemi: [/channels/signal#troubleshooting](/it/channels/signal#troubleshooting) @@ -116,12 +117,12 @@ Risoluzione completa dei problemi: [/channels/signal#troubleshooting](/it/channe ### Firme di errore di QQ Bot -| Sintomo | Controllo più rapido | Correzione | -| ------------------------------ | -------------------------------------------- | ------------------------------------------------------------------- | -| Il bot risponde "gone to Mars" | Verifica `appId` e `clientSecret` nella config | Imposta le credenziali o riavvia il gateway. | -| Nessun messaggio in ingresso | `openclaw channels status --probe` | Verifica le credenziali sulla QQ Open Platform. | -| Voce non trascritta | Controlla la config del provider STT | Configura `channels.qqbot.stt` o `tools.media.audio`. | -| I messaggi proattivi non arrivano | Controlla i requisiti di interazione della piattaforma QQ | QQ può bloccare i messaggi avviati dal bot senza un'interazione recente. | +| Sintomo | Controllo più rapido | Correzione | +| ------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------ | +| Il bot risponde "gone to Mars" | Verifica `appId` e `clientSecret` nella config | Imposta le credenziali oppure riavvia il Gateway. | +| Nessun messaggio in ingresso | `openclaw channels status --probe` | Verifica le credenziali sulla QQ Open Platform. | +| La voce non viene trascritta | Controlla la config del provider STT | Configura `channels.qqbot.stt` oppure `tools.media.audio`. | +| I messaggi proattivi non arrivano | Controlla i requisiti di interazione della piattaforma QQ | QQ può bloccare i messaggi avviati dal bot senza una recente interazione. | Risoluzione completa dei problemi: [/channels/qqbot#troubleshooting](/it/channels/qqbot#troubleshooting) @@ -129,12 +130,12 @@ Risoluzione completa dei problemi: [/channels/qqbot#troubleshooting](/it/channel ### Firme di errore di Matrix -| Sintomo | Controllo più rapido | Correzione | -| ---------------------------------- | --------------------------------------- | ------------------------------------------------------------------------- | -| Accesso eseguito ma i messaggi della stanza vengono ignorati | `openclaw channels status --probe` | Controlla `groupPolicy`, l'allowlist delle stanze e il gating delle menzioni. | -| I DM non vengono elaborati | `openclaw pairing list matrix` | Approva il mittente o regola la policy dei DM. | -| Le stanze crittografate non funzionano | `openclaw matrix verify status` | Verifica di nuovo il dispositivo, poi controlla `openclaw matrix verify backup status`. | -| Il ripristino del backup è in sospeso/non funziona | `openclaw matrix verify backup status` | Esegui `openclaw matrix verify backup restore` o ripeti l'operazione con una chiave di recupero. | -| Cross-signing/bootstrap sembra errato | `openclaw matrix verify bootstrap` | Ripara secret storage, cross-signing e stato del backup in un solo passaggio. | +| Sintomo | Controllo più rapido | Correzione | +| ----------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------- | +| Ha eseguito il login ma ignora i messaggi nella stanza | `openclaw channels status --probe` | Controlla `groupPolicy`, l'allowlist della stanza e il filtro per menzione. | +| I DM non vengono elaborati | `openclaw pairing list matrix` | Approva il mittente oppure regola il criterio DM. | +| Le stanze cifrate falliscono | `openclaw matrix verify status` | Verifica di nuovo il dispositivo, poi controlla `openclaw matrix verify backup status`. | +| Il ripristino del backup è in attesa/non funziona | `openclaw matrix verify backup status` | Esegui `openclaw matrix verify backup restore` oppure riesegui con una chiave di recupero. | +| Il bootstrap/cross-signing sembra errato | `openclaw matrix verify bootstrap` | Ripara in un solo passaggio l'archiviazione dei segreti, il cross-signing e lo stato del backup. | -Configurazione e setup completi: [Matrix](/channels/matrix) +Configurazione e impostazione complete: [Matrix](/it/channels/matrix) diff --git a/docs/it/concepts/qa-e2e-automation.md b/docs/it/concepts/qa-e2e-automation.md index 34e59102b..a041890b8 100644 --- a/docs/it/concepts/qa-e2e-automation.md +++ b/docs/it/concepts/qa-e2e-automation.md @@ -1,31 +1,31 @@ --- read_when: - - Estensione di qa-lab o qa-channel + - Estendere qa-lab o qa-channel - Aggiunta di scenari QA supportati dal repository - - Creazione di un'automazione QA a maggiore realismo attorno alla dashboard del Gateway + - Creazione di automazione QA a maggiore realismo attorno alla dashboard del Gateway summary: Forma dell'automazione QA privata per qa-lab, qa-channel, scenari con seed e report di protocollo -title: Automazione QA E2E +title: Automazione QA end-to-end x-i18n: - generated_at: "2026-04-18T08:05:14Z" + generated_at: "2026-04-20T08:30:54Z" model: gpt-5.4 provider: openai - source_hash: adf8c5f74e8fabdc8e9fd7ecd41afce8b60354c7dd24d92ac926d3c527927cd4 + source_hash: 34245ce871356caeab0d9e0eeeaa9fb4e408920a4a97ad27567fa365d8db17c7 source_path: concepts/qa-e2e-automation.md workflow: 15 --- -# Automazione QA E2E +# Automazione QA end-to-end -Lo stack QA privato è pensato per esercitare OpenClaw in modo più realistico, -con una forma simile a quella di un canale, rispetto a quanto possa fare un singolo test unitario. +Lo stack QA privato è pensato per esercitare OpenClaw in un modo più realistico, +con una forma simile ai canali, rispetto a quanto possa fare un singolo test unitario. Componenti attuali: -- `extensions/qa-channel`: canale di messaggi sintetico con superfici DM, canale, thread, - reazione, modifica ed eliminazione. -- `extensions/qa-lab`: interfaccia utente di debug e bus QA per osservare la trascrizione, +- `extensions/qa-channel`: canale di messaggistica sintetico con superfici per messaggi diretti, canale, thread, + reazioni, modifiche ed eliminazioni. +- `extensions/qa-lab`: interfaccia debugger e bus QA per osservare la trascrizione, iniettare messaggi in ingresso ed esportare un report Markdown. -- `qa/`: asset seed supportati dal repository per l'attività iniziale e gli scenari QA +- `qa/`: risorse seed supportate dal repository per il task iniziale e gli scenari QA di base. L'attuale flusso operativo QA è un sito QA a due pannelli: @@ -39,13 +39,13 @@ Eseguilo con: pnpm qa:lab:up ``` -Questo compila il sito QA, avvia la lane del gateway supportata da Docker ed espone la -pagina QA Lab dove un operatore o un loop di automazione può assegnare all'agente una -missione QA, osservare il comportamento reale del canale e registrare ciò che ha funzionato, -ciò che è fallito o ciò che è rimasto bloccato. +Questo compila il sito QA, avvia la corsia gateway supportata da Docker ed espone la +pagina QA Lab dove un operatore o un ciclo di automazione può assegnare all'agente una +missione QA, osservare il comportamento reale del canale e registrare cosa ha funzionato, cosa è fallito o +cosa è rimasto bloccato. -Per un'iterazione più rapida dell'interfaccia di QA Lab senza ricompilare ogni volta l'immagine Docker, -avvia lo stack con un bundle QA Lab montato in bind: +Per iterazioni più rapide dell'interfaccia di QA Lab senza ricompilare ogni volta l'immagine Docker, +avvia lo stack con un bundle QA Lab montato tramite bind: ```bash pnpm openclaw qa docker-build-image @@ -54,54 +54,57 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` mantiene i servizi Docker su un'immagine precompilata e monta in bind +`qa:lab:up:fast` mantiene i servizi Docker su un'immagine precompilata e monta tramite bind `extensions/qa-lab/web/dist` nel container `qa-lab`. `qa:lab:watch` -ricompila quel bundle quando cambia, e il browser si ricarica automaticamente quando cambia l'hash -degli asset di QA Lab. +ricompila quel bundle a ogni modifica e il browser si ricarica automaticamente quando cambia l'hash +delle risorse di QA Lab. -Per una lane smoke Matrix con trasporto reale, esegui: +Per una corsia smoke Matrix con trasporto reale, esegui: ```bash pnpm openclaw qa matrix ``` -Questa lane effettua il provisioning di un homeserver Tuwunel temporaneo in Docker, registra -utenti temporanei driver, SUT e osservatore, crea una stanza privata, quindi esegue il vero Plugin Matrix all'interno di un processo figlio del gateway QA. La lane con trasporto live mantiene -la configurazione del processo figlio limitata al trasporto in test, quindi Matrix viene eseguito senza -`qa-channel` nella configurazione del processo figlio. Scrive gli artifact del report strutturato e +Questa corsia effettua il provisioning di un homeserver Tuwunel usa e getta in Docker, registra +utenti temporanei driver, SUT e observer, crea una stanza privata, quindi esegue +il vero plugin Matrix all'interno di un processo figlio QA del gateway. La corsia con trasporto live mantiene +la configurazione figlia limitata al trasporto in test, così Matrix viene eseguito senza +`qa-channel` nella configurazione figlia. Scrive gli artefatti di report strutturati e un log combinato stdout/stderr nella directory di output Matrix QA selezionata. Per acquisire anche l'output esterno di build/launcher di `scripts/run-node.mjs`, imposta `OPENCLAW_RUN_NODE_OUTPUT_LOG=` su un file di log locale al repository. -Per una lane smoke Telegram con trasporto reale, esegui: +Per una corsia smoke Telegram con trasporto reale, esegui: ```bash pnpm openclaw qa telegram ``` -Questa lane usa come destinazione un vero gruppo privato Telegram invece di effettuare il provisioning di -un server temporaneo. Richiede `OPENCLAW_QA_TELEGRAM_GROUP_ID`, +Questa corsia punta a un gruppo privato Telegram reale invece di effettuare il provisioning di un +server usa e getta. Richiede `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` e `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, oltre a due bot distinti nello stesso -gruppo privato. Il bot SUT deve avere un nome utente Telegram e l'osservazione bot-to-bot -funziona al meglio quando entrambi i bot hanno Bot-to-Bot Communication Mode +gruppo privato. Il bot SUT deve avere un nome utente Telegram, e l'osservazione tra bot +funziona al meglio quando entrambi i bot hanno la modalità di comunicazione Bot-to-Bot abilitata in `@BotFather`. +Il comando termina con codice diverso da zero quando uno scenario fallisce. Usa `--allow-failures` quando +vuoi ottenere gli artefatti senza un codice di uscita di errore. -Le lane con trasporto live ora condividono un unico contratto più piccolo invece di definire -ognuna una propria forma dell'elenco di scenari. +Le corsie live di trasporto ora condividono un contratto più piccolo invece di inventare +ognuna una propria forma per l'elenco degli scenari: -`qa-channel` resta la suite ampia di comportamento sintetico del prodotto e non fa parte +`qa-channel` rimane la suite ampia di comportamento di prodotto sintetico e non fa parte della matrice di copertura del trasporto live. -| Lane | Canary | Gating delle menzioni | Blocco allowlist | Risposta di primo livello | Ripresa dopo riavvio | Follow-up nel thread | Isolamento del thread | Osservazione delle reazioni | Comando help | -| -------- | ------ | --------------------- | ---------------- | ------------------------- | -------------------- | ------------------- | --------------------- | --------------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Corsia | Canary | Blocco menzioni | Blocco allowlist | Risposta di primo livello | Ripresa dopo riavvio | Follow-up del thread | Isolamento del thread | Osservazione reazioni | Comando help | +| -------- | ------ | --------------- | ---------------- | ------------------------- | -------------------- | ------------------- | --------------------- | --------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | Questo mantiene `qa-channel` come suite ampia di comportamento del prodotto, mentre Matrix, Telegram e i futuri trasporti live condividono una checklist esplicita di contratto di trasporto. -Per una lane VM Linux temporanea senza portare Docker nel percorso QA, esegui: +Per una corsia VM Linux usa e getta senza portare Docker nel percorso QA, esegui: ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline @@ -109,92 +112,93 @@ pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline Questo avvia un guest Multipass pulito, installa le dipendenze, compila OpenClaw all'interno del guest, esegue `qa suite`, quindi copia il normale report QA e il -riepilogo in `.artifacts/qa-e2e/...` sull'host. +riepilogo di nuovo in `.artifacts/qa-e2e/...` sull'host. Riutilizza lo stesso comportamento di selezione degli scenari di `qa suite` sull'host. -Le esecuzioni host e Multipass della suite eseguono più scenari selezionati in parallelo -con worker del gateway isolati per impostazione predefinita, fino a 64 worker o al numero -di scenari selezionati. Usa `--concurrency ` per regolare il numero di worker, oppure -`--concurrency 1` per l'esecuzione seriale. +Le esecuzioni host e Multipass della suite eseguono in parallelo per impostazione predefinita +più scenari selezionati con worker gateway isolati. `qa-channel` usa come valore predefinito la concorrenza +4, limitata dal numero di scenari selezionati. Usa `--concurrency ` per regolare +il numero di worker, oppure `--concurrency 1` per l'esecuzione seriale. +Il comando termina con codice diverso da zero quando uno scenario fallisce. Usa `--allow-failures` quando +vuoi ottenere gli artefatti senza un codice di uscita di errore. Le esecuzioni live inoltrano gli input di autenticazione QA supportati che sono pratici per il -guest: chiavi provider basate su env, percorso della configurazione del provider live QA e +guest: chiavi provider basate su variabili d'ambiente, il percorso di configurazione del provider live QA e `CODEX_HOME` quando presente. Mantieni `--output-dir` sotto la root del repository in modo che il guest -possa scrivere di nuovo attraverso il workspace montato. +possa scrivere di ritorno attraverso il workspace montato. ## Seed supportati dal repository -Gli asset seed si trovano in `qa/`: +Le risorse seed si trovano in `qa/`: - `qa/scenarios/index.md` - `qa/scenarios//*.md` -Sono intenzionalmente in git così che il piano QA sia visibile sia agli esseri umani sia +Queste sono intenzionalmente in git così che il piano QA sia visibile sia agli esseri umani sia all'agente. -`qa-lab` dovrebbe restare un esecutore Markdown generico. Ogni file Markdown di scenario è +`qa-lab` dovrebbe rimanere un runner Markdown generico. Ogni file Markdown di scenario è la fonte di verità per una singola esecuzione di test e dovrebbe definire: - metadati dello scenario -- metadati opzionali di categoria, capacità, lane e rischio +- metadati facoltativi di categoria, capacità, corsia e rischio - riferimenti a documentazione e codice -- requisiti opzionali del Plugin -- patch opzionale di configurazione del gateway +- requisiti facoltativi dei plugin +- patch facoltativa della configurazione Gateway - il `qa-flow` eseguibile -La superficie runtime riutilizzabile che supporta `qa-flow` può restare generica +La superficie runtime riutilizzabile che supporta `qa-flow` può rimanere generica e trasversale. Ad esempio, gli scenari Markdown possono combinare helper lato trasporto -con helper lato browser che pilotano la Control UI incorporata tramite la seam -`browser.request` del Gateway senza aggiungere un runner con casi speciali. +con helper lato browser che guidano la Control UI incorporata tramite la seam +Gateway `browser.request` senza aggiungere un runner con casi speciali. -I file di scenario dovrebbero essere raggruppati per capacità del prodotto anziché per cartella -dell'albero sorgente. Mantieni stabili gli ID degli scenari quando i file vengono spostati; usa -`docsRefs` e `codeRefs` per la tracciabilità dell'implementazione. +I file di scenario dovrebbero essere raggruppati per capacità del prodotto invece che per cartella +dell'albero sorgente. Mantieni stabili gli ID degli scenari quando i file vengono spostati; usa `docsRefs` e `codeRefs` +per la tracciabilità dell'implementazione. -L'elenco di base dovrebbe restare abbastanza ampio da coprire: +L'elenco di base dovrebbe rimanere abbastanza ampio da coprire: -- chat DM e di canale +- chat in DM e canale - comportamento dei thread - ciclo di vita delle azioni sui messaggi - callback Cron - richiamo della memoria - cambio modello -- handoff al sottoagente +- handoff ai subagenti - lettura del repository e della documentazione -- una piccola attività di build come Lobster Invaders +- un piccolo task di build come Lobster Invaders -## Lane mock del provider +## Corsie mock del provider -`qa suite` ha due lane mock locali del provider: +`qa suite` ha due corsie mock locali del provider: -- `mock-openai` è il mock OpenClaw consapevole dello scenario. Resta la lane mock - deterministica predefinita per il QA supportato dal repository e per i gate di parità. -- `aimock` avvia un server provider supportato da AIMock per copertura sperimentale di protocollo, - fixture, record/replay e chaos. È aggiuntivo e non sostituisce il dispatcher di scenari `mock-openai`. +- `mock-openai` è il mock OpenClaw consapevole dello scenario. Rimane la corsia mock deterministica + predefinita per la QA supportata dal repository e per i gate di parità. +- `aimock` avvia un server provider basato su AIMock per copertura sperimentale di protocollo, + fixture, record/replay e chaos. È aggiuntivo e non sostituisce il dispatcher + di scenari `mock-openai`. -L'implementazione della lane del provider si trova in `extensions/qa-lab/src/providers/`. +L'implementazione della corsia provider si trova in `extensions/qa-lab/src/providers/`. Ogni provider possiede i propri valori predefiniti, l'avvio del server locale, la configurazione -del modello gateway, le esigenze di staging del profilo auth e i flag di capacità live/mock. Il codice condiviso -di suite e gateway dovrebbe instradare attraverso il registro dei provider invece di ramificarsi in base ai -nomi dei provider. +del modello gateway, le esigenze di staging del profilo auth e i flag di capacità live/mock. Il codice condiviso della suite e del gateway dovrebbe instradare attraverso il registro dei provider invece di ramificare sui nomi dei provider. -## Adapter di trasporto +## Adattatori di trasporto -`qa-lab` possiede una seam di trasporto generica per scenari QA Markdown. -`qa-channel` è il primo adapter su questa seam, ma l'obiettivo del design è più ampio: -i futuri canali reali o sintetici dovrebbero collegarsi alla stessa suite runner -invece di aggiungere un runner QA specifico per trasporto. +`qa-lab` possiede una seam di trasporto generica per gli scenari QA Markdown. +`qa-channel` è il primo adattatore su quella seam, ma l'obiettivo di progettazione è più ampio: +i futuri canali reali o sintetici dovrebbero collegarsi allo stesso runner di suite +invece di aggiungere un runner QA specifico per il trasporto. -A livello architetturale, la suddivisione è la seguente: +A livello di architettura, la suddivisione è: -- `qa-lab` possiede l'esecuzione generica degli scenari, la concorrenza dei worker, la scrittura degli artifact e il reporting. -- l'adapter di trasporto possiede la configurazione del gateway, la readiness, l'osservazione in ingresso e in uscita, le azioni di trasporto e lo stato di trasporto normalizzato. -- i file di scenario Markdown in `qa/scenarios/` definiscono l'esecuzione del test; `qa-lab` fornisce la superficie runtime riutilizzabile che li esegue. +- `qa-lab` possiede l'esecuzione generica degli scenari, la concorrenza dei worker, la scrittura degli artefatti e la reportistica. +- l'adattatore di trasporto possiede la configurazione gateway, la readiness, l'osservazione in ingresso e in uscita, le azioni di trasporto e lo stato di trasporto normalizzato. +- i file di scenario Markdown sotto `qa/scenarios/` definiscono l'esecuzione di test; `qa-lab` fornisce la superficie runtime riutilizzabile che li esegue. -La guida all'adozione, rivolta ai maintainer, per i nuovi adapter di canale si trova in +Le linee guida di adozione rivolte ai maintainer per i nuovi adattatori di canale si trovano in [Testing](/it/help/testing#adding-a-channel-to-qa). ## Reportistica -`qa-lab` esporta un report di protocollo Markdown dalla timeline osservata del bus. +`qa-lab` esporta un report di protocollo Markdown dalla timeline del bus osservata. Il report dovrebbe rispondere a: - Cosa ha funzionato @@ -202,7 +206,7 @@ Il report dovrebbe rispondere a: - Cosa è rimasto bloccato - Quali scenari di follow-up vale la pena aggiungere -Per i controlli su carattere e stile, esegui lo stesso scenario su più riferimenti live del modello +Per i controlli di carattere e stile, esegui lo stesso scenario su più riferimenti di modelli live e scrivi un report Markdown valutato: ```bash @@ -222,31 +226,31 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -Il comando esegue processi figli locali del gateway QA, non Docker. Gli scenari di character eval +Il comando esegue processi figli locali del gateway QA, non Docker. Gli scenari di valutazione del carattere dovrebbero impostare la persona tramite `SOUL.md`, quindi eseguire normali turni utente -come chat, aiuto workspace e piccole attività sui file. Al modello candidato non -dovrebbe essere detto che è in fase di valutazione. Il comando conserva ogni trascrizione -completa, registra statistiche di base dell'esecuzione, quindi chiede ai modelli giudice in modalità fast con -ragionamento `xhigh` di classificare le esecuzioni per naturalezza, vibe e umorismo. +come chat, aiuto nel workspace e piccoli task sui file. Al modello candidato +non dovrebbe essere detto che sta venendo valutato. Il comando conserva ogni trascrizione +completa, registra statistiche di base dell'esecuzione, quindi chiede ai modelli giudici in modalità fast con +ragionamento `xhigh` di classificare le esecuzioni per naturalezza, atmosfera e umorismo. Usa `--blind-judge-models` quando confronti provider: il prompt del giudice riceve comunque ogni trascrizione e stato di esecuzione, ma i riferimenti candidati vengono sostituiti con etichette neutre come `candidate-01`; il report rimappa le classifiche ai riferimenti reali dopo il parsing. -Le esecuzioni candidate usano per impostazione predefinita il thinking `high`, con `xhigh` per i modelli OpenAI che +Le esecuzioni dei candidati usano per impostazione predefinita il thinking `high`, con `xhigh` per i modelli OpenAI che lo supportano. Sostituisci un candidato specifico inline con -`--model provider/model,thinking=`. `--thinking ` imposta comunque un fallback -globale, e la vecchia forma `--model-thinking ` viene +`--model provider/model,thinking=`. `--thinking ` imposta comunque +un fallback globale, e la vecchia forma `--model-thinking ` viene mantenuta per compatibilità. -I riferimenti candidati OpenAI usano per impostazione predefinita la modalità fast, così da usare l'elaborazione prioritaria dove +I riferimenti candidati OpenAI usano per impostazione predefinita la modalità fast così da usare l'elaborazione prioritaria dove il provider la supporta. Aggiungi `,fast`, `,no-fast` o `,fast=false` inline quando un singolo candidato o giudice necessita di un override. Passa `--fast` solo quando vuoi -forzare la modalità fast per ogni modello candidato. Le durate di candidati e giudici sono -registrate nel report per l'analisi dei benchmark, ma i prompt dei giudici specificano esplicitamente di -non classificare in base alla velocità. -Le esecuzioni dei modelli candidati e giudici usano entrambe per impostazione predefinita una concorrenza di 16. -Riduci `--concurrency` o `--judge-concurrency` quando i limiti del provider o la pressione -sul gateway locale rendono un'esecuzione troppo rumorosa. -Quando non viene passato alcun candidato `--model`, character eval usa per impostazione predefinita +forzare la modalità fast per ogni modello candidato. Le durate di candidati e giudici vengono +registrate nel report per l'analisi comparativa, ma i prompt dei giudici specificano esplicitamente +di non classificare in base alla velocità. +Le esecuzioni sia dei modelli candidati sia di quelli giudici usano entrambe per impostazione predefinita la concorrenza 16. Riduci +`--concurrency` o `--judge-concurrency` quando i limiti del provider o la pressione sul gateway locale +rendono un'esecuzione troppo rumorosa. +Quando non viene passato alcun `--model` candidato, la valutazione del carattere usa per impostazione predefinita `openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, `moonshot/kimi-k2.5` e diff --git a/docs/it/gateway/configuration-reference.md b/docs/it/gateway/configuration-reference.md index 72d94f612..c41e270c4 100644 --- a/docs/it/gateway/configuration-reference.md +++ b/docs/it/gateway/configuration-reference.md @@ -1,14 +1,14 @@ --- read_when: - - Hai bisogno della semantica esatta della configurazione a livello di campo o dei valori predefiniti. - - Stai convalidando blocchi di configurazione di canale, modello, Gateway o strumento. + - Hai bisogno della semantica esatta dei campi di configurazione o dei valori predefiniti + - Stai convalidando blocchi di configurazione di canali, modelli, Gateway o strumenti summary: Riferimento della configurazione del Gateway per le chiavi principali di OpenClaw, i valori predefiniti e i link ai riferimenti dedicati dei sottosistemi title: Riferimento della configurazione x-i18n: - generated_at: "2026-04-18T08:05:10Z" + generated_at: "2026-04-20T08:30:50Z" model: gpt-5.4 provider: openai - source_hash: 4b504c9c6b47d7a327a0acf6934561c9b2606c01cc8ebe5526ccde73033d759f + source_hash: 22b10f1f133374cd29ef4a5ec4fb9c9938eb51184ad82e1aa2e5f6f7af58585e source_path: gateway/configuration-reference.md workflow: 15 --- @@ -17,54 +17,54 @@ x-i18n: Riferimento della configurazione principale per `~/.openclaw/openclaw.json`. Per una panoramica orientata alle attività, vedi [Configurazione](/it/gateway/configuration). -Questa pagina copre le principali superfici di configurazione di OpenClaw e rimanda altrove quando un sottosistema ha un proprio riferimento più approfondito. **Non** cerca di incorporare in linea ogni catalogo di comandi di canali/plugin o ogni impostazione dettagliata di memoria/QMD in un'unica pagina. +Questa pagina copre le principali superfici di configurazione di OpenClaw e rimanda ad altre pagine quando un sottosistema ha un proprio riferimento più approfondito. **Non** cerca di includere in linea ogni catalogo di comandi posseduto da canali/plugin né ogni parametro avanzato di memoria/QMD in un'unica pagina. -Fonte autorevole del codice: +Fonte del codice: -- `openclaw config schema` stampa lo JSON Schema live usato per la convalida e per la UI di controllo, con i metadati bundled/plugin/channel uniti quando disponibili -- `config.schema.lookup` restituisce un nodo di schema con ambito su un singolo percorso per gli strumenti di drill-down -- `pnpm config:docs:check` / `pnpm config:docs:gen` convalidano l'hash baseline della documentazione di configurazione rispetto alla superficie di schema corrente +- `openclaw config schema` stampa lo Schema JSON live usato per la convalida e la Control UI, con i metadati di bundle/plugin/canale uniti quando disponibili +- `config.schema.lookup` restituisce un nodo dello schema delimitato a un percorso per gli strumenti di analisi dettagliata +- `pnpm config:docs:check` / `pnpm config:docs:gen` convalidano l'hash di base della documentazione di configurazione rispetto alla superficie corrente dello schema Riferimenti approfonditi dedicati: -- [Riferimento della configurazione della memoria](/it/reference/memory-config) per `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` e la configurazione di dreaming sotto `plugins.entries.memory-core.config.dreaming` -- [Comandi slash](/it/tools/slash-commands) per il catalogo di comandi integrato + bundled attuale -- le pagine del canale/plugin proprietario per le superfici di comando specifiche del canale +- [Riferimento della configurazione della memoria](/it/reference/memory-config) per `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` e la configurazione di Dreaming in `plugins.entries.memory-core.config.dreaming` +- [Comandi slash](/it/tools/slash-commands) per il catalogo corrente dei comandi integrati + bundled +- pagine del canale/plugin proprietario per le superfici di comandi specifiche del canale -Il formato di configurazione è **JSON5** (commenti + virgole finali consentiti). Tutti i campi sono facoltativi: OpenClaw usa valori predefiniti sicuri quando vengono omessi. +Il formato della configurazione è **JSON5** (commenti + virgole finali consentiti). Tutti i campi sono facoltativi: OpenClaw usa valori predefiniti sicuri quando vengono omessi. --- ## Canali -Ogni canale si avvia automaticamente quando la sua sezione di configurazione esiste (a meno che `enabled: false`). +Ogni canale si avvia automaticamente quando esiste la sua sezione di configurazione (a meno che `enabled: false`). -### Accesso DM e di gruppo +### 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` (predefinito) | I mittenti sconosciuti ricevono un codice di pairing monouso; il proprietario deve approvare | -| `allowlist` | Solo i mittenti in `allowFrom` (o nello store allow paired) | -| `open` | Consenti tutti i DM in ingresso (richiede `allowFrom: ["*"]`) | -| `disabled` | Ignora tutti i DM in ingresso | +| Criterio DM | Comportamento | +| -------------------- | -------------------------------------------------------------- | +| `pairing` (default) | I mittenti sconosciuti ricevono un codice di pairing monouso; il proprietario deve approvare | +| `allowlist` | Solo i mittenti in `allowFrom` (o nell'archivio di autorizzazione accoppiato) | +| `open` | Consenti tutti i DM in ingresso (richiede `allowFrom: ["*"]`) | +| `disabled` | Ignora tutti i DM in ingresso | -| Criterio di gruppo | Comportamento | -| --------------------- | ---------------------------------------------------- | -| `allowlist` (predefinito) | Solo i gruppi che corrispondono alla allowlist configurata | -| `open` | Bypassa le allowlist di gruppo (il mention-gating continua ad applicarsi) | -| `disabled` | Blocca tutti i messaggi di gruppo/stanza | +| Criterio di gruppo | Comportamento | +| ---------------------- | ----------------------------------------------------- | +| `allowlist` (default) | Solo i gruppi che corrispondono all'elenco consentito configurato | +| `open` | Ignora gli elenchi consentiti dei gruppi (resta comunque attivo il gating per menzioni) | +| `disabled` | Blocca tutti i messaggi di gruppo/stanza | `channels.defaults.groupPolicy` imposta il valore predefinito quando `groupPolicy` di un provider non è impostato. I codici di pairing scadono dopo 1 ora. Le richieste di pairing DM in sospeso sono limitate a **3 per canale**. -Se un blocco provider manca completamente (`channels.` assente), il criterio di gruppo a runtime torna a `allowlist` (fail-closed) con un avviso all'avvio. +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 di canali specifici a un modello. I valori accettano `provider/model` o alias di modello configurati. La mappatura del canale si applica quando una sessione non ha già un override del modello (per esempio impostato tramite `/model`). +Usa `channels.modelByChannel` per fissare ID di canali specifici a un modello. I valori accettano `provider/model` o alias di modello configurati. La mappatura del canale si applica quando una sessione non ha già un override del modello (ad esempio, impostato tramite `/model`). ```json5 { @@ -85,9 +85,9 @@ Usa `channels.modelByChannel` per fissare ID di canali specifici a un modello. I } ``` -### Valori predefiniti del canale e Heartbeat +### Valori predefiniti dei canali e Heartbeat -Usa `channels.defaults` per il comportamento condiviso di criterio di gruppo e Heartbeat tra i provider: +Usa `channels.defaults` per il comportamento condiviso di criteri di gruppo e Heartbeat tra i provider: ```json5 { @@ -106,14 +106,14 @@ Usa `channels.defaults` per il comportamento condiviso di criterio di gruppo e H ``` - `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 dai mittenti nella allowlist), `allowlist_quote` (uguale ad allowlist ma mantiene il contesto esplicito di citazione/risposta). Override per canale: `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk`: include gli stati dei canali sani nell'output Heartbeat. -- `channels.defaults.heartbeat.showAlerts`: include gli stati degradati/di errore nell'output Heartbeat. -- `channels.defaults.heartbeat.useIndicator`: visualizza 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 di citazioni/thread/crono­logia), `allowlist` (include solo il contesto di mittenti presenti nell'elenco consentito), `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 di Heartbeat. +- `channels.defaults.heartbeat.showAlerts`: include gli stati degradati/di errore nell'output di Heartbeat. +- `channels.defaults.heartbeat.useIndicator`: visualizza un output di Heartbeat compatto in stile indicatore. ### WhatsApp -WhatsApp viene eseguito tramite il canale web del Gateway (Baileys Web). Si avvia automaticamente quando esiste una sessione collegata. +WhatsApp funziona tramite il canale web del Gateway (Baileys Web). Si avvia automaticamente quando esiste una sessione collegata. ```json5 { @@ -124,7 +124,7 @@ WhatsApp viene eseguito tramite il canale web del Gateway (Baileys Web). Si avvi textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // spunte blu (false in modalità self-chat) + sendReadReceipts: true, // spunte blu (false in modalità chat con sé stessi) groups: { "*": { requireMention: true }, }, @@ -165,8 +165,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). -- L'opzionale `channels.whatsapp.defaultAccount` sovrascrive quella selezione predefinita dell'account di fallback quando corrisponde a un ID account configurato. -- La directory di autenticazione legacy single-account Baileys viene migrata da `openclaw doctor` in `whatsapp/default`. +- L'opzionale `channels.whatsapp.defaultAccount` sostituisce quella selezione predefinita di fallback dell'account quando corrisponde a un ID account configurato. +- La directory di autenticazione legacy Baileys a account singolo viene migrata da `openclaw doctor` in `whatsapp/default`. - Override per account: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -202,7 +202,7 @@ WhatsApp viene eseguito tramite il canale web del Gateway (Baileys Web). Si avvi historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits) + streaming: "partial", // off | partial | block | progress (default: off; attivalo esplicitamente per evitare i limiti di frequenza delle modifiche alle anteprime) actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -225,12 +225,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 vengono rifiutati), con `TELEGRAM_BOT_TOKEN` come fallback per l'account predefinito. -- L'opzionale `channels.telegram.defaultAccount` sovrascrive la selezione predefinita dell'account quando corrisponde a un ID account configurato. +- Token del bot: `channels.telegram.botToken` oppure `channels.telegram.tokenFile` (solo file regolare; i symlink sono rifiutati), con `TELEGRAM_BOT_TOKEN` come fallback per l'account predefinito. +- L'opzionale `channels.telegram.defaultAccount` sostituisce 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 questo manca o non è valido. -- `configWrites: false` blocca le scritture di configurazione avviate da Telegram (migrazioni dell'ID del supergruppo, `/config set|unset`). -- Le voci `bindings[]` di livello superiore con `type: "acp"` configurano binding ACP persistenti per i topic del forum (usa il canonico `chatId:topic:topicId` in `match.peer.id`). La semantica dei campi è condivisa in [Agenti ACP](/it/tools/acp-agents#channel-specific-settings). -- Le anteprime di streaming di Telegram usano `sendMessage` + `editMessageText` (funziona in chat dirette e di gruppo). +- `configWrites: false` blocca le scritture di configurazione avviate da Telegram (migrazioni degli ID dei supergruppi, `/config set|unset`). +- Le voci `bindings[]` di primo livello con `type: "acp"` configurano binding ACP persistenti per i topic del forum (usa il formato canonico `chatId:topic:topicId` in `match.peer.id`). La semantica dei campi è condivisa in [Agenti ACP](/it/tools/acp-agents#channel-specific-settings). +- Le anteprime di streaming di Telegram usano `sendMessage` + `editMessageText` (funziona nelle chat dirette e di gruppo). - Criterio di retry: vedi [Criterio di retry](/it/concepts/retry). ### Discord @@ -286,7 +286,7 @@ WhatsApp viene eseguito tramite il canale web del Gateway (Baileys Web). Si avvi historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress (progress viene mappato a partial su Discord) + streaming: "off", // off | partial | block | progress (progress corrisponde a partial su Discord) maxLinesPerMessage: 17, ui: { components: { @@ -334,33 +334,33 @@ 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 continuano comunque a provenire dall'account selezionato nello snapshot runtime attivo. -- L'opzionale `channels.discord.defaultAccount` sovrascrive la selezione predefinita dell'account quando corrisponde a un ID account configurato. -- Usa `user:` (DM) o `channel:` (canale guild) per i target di consegna; gli ID numerici non qualificati vengono rifiutati. -- Gli slug delle guild sono in minuscolo con gli spazi sostituiti da `-`; le chiavi dei canali usano il nome in forma slug (senza `#`). Preferisci gli ID delle guild. -- I messaggi creati dal bot vengono ignorati per impostazione predefinita. `allowBots: true` li abilita; usa `allowBots: "mentions"` per accettare solo i messaggi dei bot che menzionano il bot (i messaggi propri restano comunque filtrati). -- `channels.discord.guilds..ignoreOtherMentions` (e gli override di canale) elimina i messaggi che menzionano un altro utente o ruolo ma non il bot (escludendo @everyone/@here). -- `maxLinesPerMessage` (predefinito 17) divide i messaggi alti anche quando sono sotto i 2000 caratteri. -- `channels.discord.threadBindings` controlla il routing associato ai thread Discord: - - `enabled`: override Discord per le funzionalità di sessione associate ai thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` e consegna/routing associati) - - `idleHours`: override Discord per l'auto-unfocus dovuto a inattività in ore (`0` lo disabilita) +- Le chiamate dirette in uscita che forniscono un `token` Discord esplicito usano quel token per la chiamata; le impostazioni di retry/criteri dell'account continuano comunque a provenire dall'account selezionato nello snapshot runtime attivo. +- L'opzionale `channels.discord.defaultAccount` sostituisce la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- Usa `user:` (DM) oppure `channel:` (canale guild) per i target di consegna; gli ID numerici non qualificati vengono rifiutati. +- Gli slug delle guild sono in minuscolo con gli spazi sostituiti da `-`; le chiavi dei canali usano il nome trasformato in slug (senza `#`). Preferisci gli ID delle guild. +- I messaggi scritti dal bot vengono ignorati per impostazione predefinita. `allowBots: true` li abilita; usa `allowBots: "mentions"` per accettare solo i messaggi dei bot che menzionano il bot (i propri messaggi restano comunque filtrati). +- `channels.discord.guilds..ignoreOtherMentions` (e gli override a livello di canale) scarta i messaggi che menzionano un altro utente o ruolo ma non il bot (escludendo @everyone/@here). +- `maxLinesPerMessage` (predefinito 17) divide i messaggi molto alti anche quando restano sotto i 2000 caratteri. +- `channels.discord.threadBindings` controlla il routing vincolato ai thread di Discord: + - `enabled`: override Discord per le funzionalità di sessione vincolate ai thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` e consegna/routing vincolati) + - `idleHours`: override Discord per il disaccoppiamento automatico per inattività in ore (`0` lo disabilita) - `maxAgeHours`: override Discord per l'età massima rigida in ore (`0` lo disabilita) - - `spawnSubagentSessions`: switch opt-in per la creazione/associazione automatica di thread con `sessions_spawn({ thread: true })` -- Le voci `bindings[]` di livello superiore con `type: "acp"` configurano binding ACP persistenti per canali e thread (usa l'id del canale/thread in `match.peer.id`). La semantica dei campi è condivisa in [Agenti ACP](/it/tools/acp-agents#channel-specific-settings). -- `channels.discord.ui.components.accentColor` imposta il colore di accento per i container Discord components v2. -- `channels.discord.voice` abilita le conversazioni nei canali vocali Discord e gli override opzionali di auto-join + TTS. -- `channels.discord.voice.daveEncryption` e `channels.discord.voice.decryptionFailureTolerance` vengono passati a `@discordjs/voice` come opzioni DAVE (rispettivamente `true` e `24` per impostazione predefinita). + - `spawnSubagentSessions`: interruttore opt-in per la creazione/associazione automatica dei 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 del canale/thread in `match.peer.id`). La semantica dei campi è condivisa in [Agenti ACP](/it/tools/acp-agents#channel-specific-settings). +- `channels.discord.ui.components.accentColor` imposta il colore di accento per i contenitori dei componenti Discord v2. +- `channels.discord.voice` abilita le conversazioni nei canali vocali Discord e gli override facoltativi per auto-join + TTS. +- `channels.discord.voice.daveEncryption` e `channels.discord.voice.decryptionFailureTolerance` vengono passati a `@discordjs/voice` come opzioni DAVE (`true` e `24` per impostazione predefinita). - OpenClaw tenta inoltre il recupero della ricezione vocale uscendo e rientrando in una sessione vocale dopo ripetuti errori di decrittazione. -- `channels.discord.streaming` è la chiave canonica della modalità di streaming. I valori legacy `streamMode` e booleani `streaming` vengono migrati automaticamente. -- `channels.discord.autoPresence` mappa la disponibilità runtime sulla presence del bot (healthy => online, degraded => idle, exhausted => dnd) e consente override facoltativi del testo di stato. -- `channels.discord.dangerouslyAllowNameMatching` riabilita la corrispondenza per nome/tag mutabile (modalità di compatibilità break-glass). +- `channels.discord.streaming` è la chiave canonica per la modalità di streaming. I valori legacy `streamMode` e booleani `streaming` vengono migrati automaticamente. +- `channels.discord.autoPresence` mappa la disponibilità del runtime alla presenza del bot (healthy => online, degraded => idle, exhausted => dnd) e consente override facoltativi del testo di stato. +- `channels.discord.dangerouslyAllowNameMatching` riabilita la corrispondenza per nome/tag mutabili (modalità di compatibilità break-glass). - `channels.discord.execApprovals`: consegna nativa Discord delle approvazioni exec e autorizzazione degli approvatori. - - `enabled`: `true`, `false` o `"auto"` (predefinito). In modalità auto, le approvazioni exec si attivano quando gli approvatori possono essere risolti da `approvers` o `commands.ownerAllowFrom`. + - `enabled`: `true`, `false` oppure `"auto"` (predefinito). In modalità auto, le approvazioni exec si attivano quando gli approvatori possono essere risolti da `approvers` oppure `commands.ownerAllowFrom`. - `approvers`: ID utente Discord autorizzati ad approvare richieste exec. Se omesso, usa `commands.ownerAllowFrom` come fallback. - - `agentFilter`: allowlist facoltativa di ID agente. Omettilo per inoltrare approvazioni per tutti gli agenti. - - `sessionFilter`: pattern facoltativi di chiave sessione (sottostringa o regex). - - `target`: dove inviare i prompt di approvazione. `"dm"` (predefinito) li invia ai DM degli approvatori, `"channel"` li invia al canale di origine, `"both"` li invia a entrambi. Quando il target include `"channel"`, i pulsanti sono utilizzabili solo dagli approvatori risolti. - - `cleanupAfterResolve`: quando `true`, elimina i DM di approvazione dopo approvazione, rifiuto o timeout. + - `agentFilter`: allowlist facoltativa di ID agente. Ometti per inoltrare le approvazioni per tutti gli agenti. + - `sessionFilter`: pattern facoltativi per chiavi di sessione (sottostringa o regex). + - `target`: dove inviare le richieste di approvazione. `"dm"` (predefinito) le invia ai DM degli approvatori, `"channel"` le invia al canale di origine, `"both"` le invia a entrambi. Quando il target include `"channel"`, i pulsanti possono essere usati solo dagli approvatori risolti. + - `cleanupAfterResolve`: quando è `true`, elimina i DM di approvazione dopo approvazione, rifiuto o timeout. **Modalità di notifica delle reazioni:** `off` (nessuna), `own` (messaggi del bot, predefinito), `all` (tutti i messaggi), `allowlist` (da `guilds..users` su tutti i messaggi). @@ -393,11 +393,11 @@ WhatsApp viene eseguito tramite il canale web del Gateway (Baileys Web). Si avvi } ``` -- JSON dell'account di servizio: inline (`serviceAccount`) o basato su file (`serviceAccountFile`). -- È supportato anche SecretRef dell'account di servizio (`serviceAccountRef`). -- Fallback env: `GOOGLE_CHAT_SERVICE_ACCOUNT` o `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. -- Usa `spaces/` o `users/` per i target di consegna. -- `channels.googlechat.dangerouslyAllowNameMatching` riabilita la corrispondenza mutabile del principal email (modalità di compatibilità break-glass). +- JSON dell'account di servizio: inline (`serviceAccount`) oppure basato su file (`serviceAccountFile`). +- È supportato anche SecretRef per l'account di servizio (`serviceAccountRef`). +- Fallback env: `GOOGLE_CHAT_SERVICE_ACCOUNT` oppure `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. +- Usa `spaces/` oppure `users/` per i target di consegna. +- `channels.googlechat.dangerouslyAllowNameMatching` riabilita la corrispondenza con principal email mutabili (modalità di compatibilità break-glass). ### Slack @@ -449,7 +449,7 @@ WhatsApp viene eseguito tramite il canale web del Gateway (Baileys Web). Si avvi chunkMode: "length", streaming: { mode: "partial", // off | partial | block | progress - nativeTransport: true, // use Slack native streaming API when mode=partial + nativeTransport: true, // usa l'API di streaming nativa di Slack quando mode=partial }, mediaMaxMb: 20, execApprovals: { @@ -466,27 +466,27 @@ 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. +- `botToken`, `appToken`, `signingSecret` e `userToken` accettano stringhe in chiaro oppure oggetti SecretRef. - Gli snapshot degli 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 di comando/runtime corrente non ha potuto risolvere il valore del segreto. - `configWrites: false` blocca le scritture di configurazione avviate da Slack. -- L'opzionale `channels.slack.defaultAccount` sovrascrive la selezione predefinita dell'account quando corrisponde a un ID account configurato. -- `channels.slack.streaming.mode` è la chiave canonica della modalità di streaming Slack. `channels.slack.streaming.nativeTransport` controlla il trasporto di streaming nativo di Slack. I valori legacy `streamMode`, booleani `streaming` e `nativeStreaming` vengono migrati automaticamente. -- Usa `user:` (DM) o `channel:` per i target di consegna. +- L'opzionale `channels.slack.defaultAccount` sostituisce la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- `channels.slack.streaming.mode` è la chiave canonica per la modalità di streaming Slack. `channels.slack.streaming.nativeTransport` controlla il trasporto di streaming nativo di Slack. I valori legacy `streamMode`, booleani `streaming` e `nativeStreaming` vengono migrati automaticamente. +- Usa `user:` (DM) oppure `channel:` per i target di consegna. **Modalità di notifica delle reazioni:** `off`, `own` (predefinito), `all`, `allowlist` (da `reactionAllowlist`). -**Isolamento della sessione del thread:** `thread.historyScope` è per thread (predefinito) o condiviso nel canale. `thread.inheritParent` copia la trascrizione del canale padre nei nuovi thread. +**Isolamento delle sessioni thread:** `thread.historyScope` è per-thread (predefinito) oppure condiviso tra il canale. `thread.inheritParent` copia la trascrizione del canale padre nei nuovi thread. -- Lo streaming nativo Slack e lo stato del thread Slack in stile assistant "is typing..." richiedono un target di risposta in un thread. I DM di livello superiore restano fuori thread per impostazione predefinita, quindi usano `typingReaction` o la consegna normale invece dell'anteprima in stile thread. +- Lo streaming nativo di Slack più lo stato del thread in stile assistente Slack "is typing..." richiedono un target di risposta nel thread. I DM di primo livello restano per impostazione predefinita fuori dal thread, quindi usano `typingReaction` o la consegna normale invece dell'anteprima in stile thread. - `typingReaction` aggiunge una reazione temporanea al messaggio Slack in ingresso mentre una risposta è in esecuzione, poi la rimuove al completamento. Usa uno shortcode emoji Slack come `"hourglass_flowing_sand"`. -- `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"`). +- `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"` oppure `"both"`). -| Gruppo di azioni | Predefinito | Note | -| ---------------- | ----------- | ------------------------ | -| reactions | abilitato | Reagire + elencare reazioni | -| messages | abilitato | Leggere/inviare/modificare/eliminare | -| pins | abilitato | Fissare/rimuovere/elencare | -| memberInfo | abilitato | Informazioni membro | +| Gruppo di azioni | Predefinito | Note | +| ---------------- | ----------- | ---------------------- | +| reactions | abilitato | Reagisci + elenca reazioni | +| messages | abilitato | Leggi/invia/modifica/elimina | +| pins | abilitato | Fissa/rimuovi/elenca | +| memberInfo | abilitato | Informazioni membro | | emojiList | abilitato | Elenco emoji personalizzate | ### Mattermost @@ -511,7 +511,7 @@ Mattermost viene distribuito come Plugin: `openclaw plugins install @openclaw/ma native: true, // opt-in nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // Optional explicit URL for reverse-proxy/public deployments + // URL esplicito facoltativo per deployment dietro reverse proxy/pubblici callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -521,18 +521,18 @@ Mattermost viene distribuito come Plugin: `openclaw plugins install @openclaw/ma } ``` -Modalità chat: `oncall` (risponde a @-mention, predefinito), `onmessage` (ogni messaggio), `onchar` (messaggi che iniziano con il prefisso trigger). +Modalità chat: `oncall` (risponde a @-mention, predefinito), `onmessage` (ogni messaggio), `onchar` (messaggi che iniziano con un prefisso trigger). -Quando i comandi nativi di Mattermost sono abilitati: +Quando i comandi nativi Mattermost sono abilitati: -- `commands.callbackPath` deve essere un percorso (per esempio `/api/channels/mattermost/command`), non un URL completo. +- `commands.callbackPath` deve essere un percorso (ad esempio `/api/channels/mattermost/command`), non un URL completo. - `commands.callbackUrl` deve risolversi all'endpoint Gateway di OpenClaw ed essere raggiungibile dal server Mattermost. -- Le callback slash native vengono 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 può richiedere che `ServiceSettings.AllowedUntrustedInternalConnections` includa l'host/dominio di callback. Usa valori host/dominio, non URL completi. +- I callback slash nativi sono autenticati con i token per comando restituiti da Mattermost durante la registrazione dei comandi slash. Se la registrazione fallisce o non viene attivato alcun comando, OpenClaw rifiuta i callback con `Unauthorized: invalid command token.` +- Per host di callback privati/tailnet/interni, Mattermost potrebbe richiedere che `ServiceSettings.AllowedUntrustedInternalConnections` includa l'host/dominio di 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 mention-gating (`"*"` per il predefinito). -- L'opzionale `channels.mattermost.defaultAccount` sovrascrive la selezione predefinita dell'account quando corrisponde a un ID account configurato. +- `channels.mattermost.groups..requireMention`: override per canale del gating per menzione (`"*"` per il valore predefinito). +- L'opzionale `channels.mattermost.defaultAccount` sostituisce la selezione dell'account predefinito quando corrisponde a un ID account configurato. ### Signal @@ -555,13 +555,13 @@ Quando i comandi nativi di Mattermost sono abilitati: **Modalità di notifica delle reazioni:** `off`, `own` (predefinito), `all`, `allowlist` (da `reactionAllowlist`). -- `channels.signal.account`: vincola l'avvio del canale a una specifica identità account Signal. +- `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. -- L'opzionale `channels.signal.defaultAccount` sovrascrive la selezione predefinita dell'account quando corrisponde a un ID account configurato. +- L'opzionale `channels.signal.defaultAccount` sostituisce la selezione dell'account predefinito quando corrisponde a un ID account configurato. ### BlueBubbles -BlueBubbles è il percorso iMessage consigliato (supportato da Plugin, configurato sotto `channels.bluebubbles`). +BlueBubbles è il percorso iMessage consigliato (supportato da Plugin, configurato in `channels.bluebubbles`). ```json5 { @@ -569,21 +569,21 @@ BlueBubbles è il percorso iMessage consigliato (supportato da Plugin, configura bluebubbles: { enabled: true, dmPolicy: "pairing", - // serverUrl, password, webhookPath, group controls, and advanced actions: - // see /channels/bluebubbles + // serverUrl, password, webhookPath, controlli di gruppo e azioni avanzate: + // vedi /channels/bluebubbles }, }, } ``` -- Percorsi chiave core trattati qui: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- L'opzionale `channels.bluebubbles.defaultAccount` sovrascrive la selezione predefinita dell'account quando corrisponde a un ID account configurato. -- Le voci `bindings[]` di livello superiore con `type: "acp"` possono associare conversazioni BlueBubbles a sessioni ACP persistenti. Usa un handle BlueBubbles o una stringa target (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) in `match.peer.id`. Semantica condivisa dei campi: [Agenti ACP](/it/tools/acp-agents#channel-specific-settings). +- Percorsi chiave principali trattati qui: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. +- L'opzionale `channels.bluebubbles.defaultAccount` sostituisce la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- Le voci `bindings[]` di primo livello con `type: "acp"` possono associare conversazioni BlueBubbles a sessioni ACP persistenti. Usa un handle BlueBubbles o una stringa target (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) in `match.peer.id`. Semantica condivisa dei campi: [Agenti ACP](/it/tools/acp-agents#channel-specific-settings). - La configurazione completa del canale BlueBubbles è documentata in [BlueBubbles](/it/channels/bluebubbles). ### iMessage -OpenClaw avvia `imsg rpc` (JSON-RPC su stdio). Non è richiesto alcun daemon o porta. +OpenClaw avvia `imsg rpc` (JSON-RPC su stdio). Non sono richiesti daemon né porta. ```json5 { @@ -607,17 +607,17 @@ OpenClaw avvia `imsg rpc` (JSON-RPC su stdio). Non è richiesto alcun daemon o p } ``` -- L'opzionale `channels.imessage.defaultAccount` sovrascrive la selezione predefinita dell'account quando corrisponde a un ID account configurato. +- L'opzionale `channels.imessage.defaultAccount` sostituisce la selezione dell'account predefinito quando corrisponde a un ID account configurato. -- Richiede Full Disk Access al DB di Messages. +- Richiede l'accesso completo al disco per il DB di Messages. - Preferisci target `chat_id:`. Usa `imsg chats --limit 20` per elencare le chat. -- `cliPath` può puntare a un wrapper SSH; imposta `remoteHost` (`host` o `user@host`) per il recupero degli allegati via SCP. +- `cliPath` può puntare a un wrapper SSH; imposta `remoteHost` (`host` o `user@host`) per il recupero degli allegati tramite SCP. - `attachmentRoots` e `remoteAttachmentRoots` limitano i percorsi degli allegati in ingresso (predefinito: `/Users/*/Library/Messages/Attachments`). -- SCP usa un controllo rigoroso della chiave host, quindi assicurati che la chiave dell'host relay esista già in `~/.ssh/known_hosts`. +- SCP usa la verifica rigorosa della chiave host, quindi assicurati che la chiave host del relay esista già in `~/.ssh/known_hosts`. - `channels.imessage.configWrites`: consente o nega le scritture di configurazione avviate da iMessage. -- Le voci `bindings[]` di livello superiore con `type: "acp"` possono associare conversazioni iMessage a sessioni ACP persistenti. Usa un handle normalizzato o un target chat esplicito (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) in `match.peer.id`. Semantica condivisa dei campi: [Agenti ACP](/it/tools/acp-agents#channel-specific-settings). +- Le voci `bindings[]` di primo livello con `type: "acp"` possono associare conversazioni iMessage a sessioni ACP persistenti. Usa un handle normalizzato o un target chat esplicito (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) in `match.peer.id`. Semantica condivisa dei campi: [Agenti ACP](/it/tools/acp-agents#channel-specific-settings). - + ```bash #!/usr/bin/env bash @@ -628,7 +628,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix è supportato da estensione ed è configurato sotto `channels.matrix`. +Matrix è supportato da estensione ed è configurato in `channels.matrix`. ```json5 { @@ -659,24 +659,24 @@ Matrix è supportato da estensione ed è configurato sotto `channels.matrix`. ``` - L'autenticazione con token usa `accessToken`; l'autenticazione con password usa `userId` + `password`. -- `channels.matrix.proxy` instrada il traffico HTTP di Matrix attraverso un proxy HTTP(S) esplicito. Gli account nominati possono sovrascriverlo con `channels.matrix.accounts..proxy`. +- `channels.matrix.proxy` instrada il traffico HTTP Matrix attraverso un proxy HTTP(S) esplicito. Gli account nominati possono sovrascriverlo con `channels.matrix.accounts..proxy`. - `channels.matrix.network.dangerouslyAllowPrivateNetwork` consente homeserver privati/interni. `proxy` e questo opt-in di rete sono controlli indipendenti. - `channels.matrix.defaultAccount` seleziona l'account preferito nelle configurazioni multi-account. -- `channels.matrix.autoJoin` è `off` per impostazione predefinita, quindi le stanze invitate e i nuovi inviti in stile DM vengono ignorati finché non imposti `autoJoin: "allowlist"` con `autoJoinAllowlist` o `autoJoin: "always"`. +- `channels.matrix.autoJoin` ha come predefinito `off`, quindi le stanze invitate e i nuovi inviti in stile DM vengono ignorati finché non imposti `autoJoin: "allowlist"` con `autoJoinAllowlist` oppure `autoJoin: "always"`. - `channels.matrix.execApprovals`: consegna nativa Matrix delle approvazioni exec e autorizzazione degli approvatori. - - `enabled`: `true`, `false` o `"auto"` (predefinito). In modalità auto, le approvazioni exec si attivano quando gli approvatori possono essere risolti da `approvers` o `commands.ownerAllowFrom`. + - `enabled`: `true`, `false` oppure `"auto"` (predefinito). In modalità auto, le approvazioni exec si attivano quando gli approvatori possono essere risolti da `approvers` oppure `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 approvazioni per tutti gli agenti. - - `sessionFilter`: pattern facoltativi di chiave sessione (sottostringa o regex). - - `target`: dove inviare i prompt di approvazione. `"dm"` (predefinito), `"channel"` (stanza di origine) o `"both"`. + - `agentFilter`: allowlist facoltativa di ID agente. Ometti per inoltrare le approvazioni per tutti gli agenti. + - `sessionFilter`: pattern facoltativi per chiavi di sessione (sottostringa o regex). + - `target`: dove inviare le richieste di approvazione. `"dm"` (predefinito), `"channel"` (stanza di origine) oppure `"both"`. - Override per account: `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope` controlla come i DM Matrix vengono raggruppati in sessioni: `per-user` (predefinito) condivisione per peer instradato, mentre `per-room` isola ogni stanza DM. -- I probe di stato Matrix e le ricerche live della directory usano lo stesso criterio proxy del traffico runtime. -- La configurazione completa di Matrix, le regole di targeting e gli esempi di setup sono documentati in [Matrix](/it/channels/matrix). +- `channels.matrix.dm.sessionScope` controlla il modo in cui i DM Matrix vengono raggruppati in sessioni: `per-user` (predefinito) condivide per peer instradato, mentre `per-room` isola ogni stanza DM. +- I probe di stato Matrix e le ricerche live nella directory usano lo stesso criterio di proxy del traffico runtime. +- La configurazione completa di Matrix, le regole di targeting e gli esempi di configurazione sono documentati in [Matrix](/it/channels/matrix). ### Microsoft Teams -Microsoft Teams è supportato da estensione ed è configurato sotto `channels.msteams`. +Microsoft Teams è supportato da estensione ed è configurato in `channels.msteams`. ```json5 { @@ -684,19 +684,19 @@ Microsoft Teams è supportato da estensione ed è configurato sotto `channels.ms msteams: { enabled: true, configWrites: true, - // appId, appPassword, tenantId, webhook, team/channel policies: - // see /channels/msteams + // appId, appPassword, tenantId, webhook, criteri di team/canale: + // vedi /channels/msteams }, }, } ``` -- Percorsi chiave core trattati 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). +- Percorsi chiave principali trattati qui: `channels.msteams`, `channels.msteams.configWrites`. +- La configurazione completa di Teams (credenziali, webhook, criteri DM/gruppo, override per team/per canale) è documentata in [Microsoft Teams](/it/channels/msteams). ### IRC -IRC è supportato da estensione ed è configurato sotto `channels.irc`. +IRC è supportato da estensione ed è configurato in `channels.irc`. ```json5 { @@ -717,13 +717,13 @@ IRC è supportato da estensione ed è configurato sotto `channels.irc`. } ``` -- Percorsi chiave core trattati qui: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- L'opzionale `channels.irc.defaultAccount` sovrascrive la selezione predefinita dell'account quando corrisponde a un ID account configurato. -- La configurazione completa del canale IRC (host/porta/TLS/canali/allowlist/mention gating) è documentata in [IRC](/it/channels/irc). +- Percorsi chiave principali trattati qui: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. +- L'opzionale `channels.irc.defaultAccount` sostituisce la selezione dell'account predefinito quando corrisponde a un ID account configurato. +- La configurazione completa del canale IRC (host/porta/TLS/canali/allowlist/gating per menzione) è documentata in [IRC](/it/channels/irc). ### 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 { @@ -746,26 +746,26 @@ Esegui più account per canale (ciascuno con il proprio `accountId`): - `default` viene usato quando `accountId` è omesso (CLI + routing). - I token env si applicano solo all'account **default**. -- Le impostazioni base del canale si applicano a tutti gli account, salvo override per account. +- Le impostazioni di base del canale si applicano a tutti gli account salvo override per account. - Usa `bindings[].match.accountId` per instradare ciascun account a un agente diverso. -- Se aggiungi un account non predefinito tramite `openclaw channels add` (o onboarding del canale) mentre sei ancora in una configurazione di canale top-level single-account, OpenClaw promuove prima i valori single-account top-level 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/default esistente corrispondente. -- I binding esistenti solo di canale (senza `accountId`) continuano a corrispondere all'account predefinito; i binding con ambito account restano facoltativi. -- Anche `openclaw doctor --fix` ripara le shape miste spostando i valori single-account top-level con ambito account nell'account promosso scelto per quel canale. La maggior parte dei canali usa `accounts.default`; Matrix può invece preservare un target nominato/default esistente corrispondente. +- Se aggiungi un account non predefinito tramite `openclaw channels add` (o onboarding del canale) mentre sei ancora su una configurazione di canale di primo livello a account singolo, OpenClaw promuove prima i valori di primo livello 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 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 di primo livello a account singolo con ambito account nell'account promosso scelto per quel canale. La maggior parte dei canali usa `accounts.default`; Matrix può invece preservare un target nominato/predefinito esistente corrispondente. ### Altri canali di estensione -Molti canali di estensione sono configurati come `channels.` e documentati nelle loro pagine canale dedicate (per esempio Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat e Twitch). +Molti canali di estensione sono configurati come `channels.` e documentati nelle rispettive pagine dedicate del canale (ad esempio Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat e Twitch). Vedi l'indice completo dei canali: [Canali](/it/channels). -### Mention gating nelle chat di gruppo +### Gating per menzione nelle chat di gruppo -Per impostazione predefinita, i messaggi di gruppo **richiedono una mention** (mention nei metadati o pattern regex sicuri). Si applica a chat di gruppo WhatsApp, Telegram, Discord, Google Chat e iMessage. +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. -**Tipi di mention:** +**Tipi di menzione:** -- **Mention nei metadati**: @-mention native della piattaforma. Ignorate in modalità self-chat di WhatsApp. +- **Menzioni nei metadati**: @-mention native della piattaforma. Ignorate nella modalità chat con sé stessi di WhatsApp. - **Pattern di testo**: pattern regex sicuri in `agents.list[].groupChat.mentionPatterns`. I pattern non validi e le ripetizioni annidate non sicure vengono ignorati. -- Il mention gating viene applicato solo quando il rilevamento è possibile (mention native o almeno un pattern). +- Il gating per menzione viene applicato solo quando il rilevamento è possibile (menzioni native o almeno un pattern). ```json5 { @@ -795,13 +795,13 @@ Per impostazione predefinita, i messaggi di gruppo **richiedono una mention** (m } ``` -Risoluzione: override per-DM → predefinito provider → nessun limite (tutto mantenuto). +Risoluzione: override per DM → predefinito del provider → nessun limite (tutto mantenuto). Supportati: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. -#### Modalità self-chat +#### Modalità chat con sé stessi -Includi il tuo numero in `allowFrom` per abilitare la modalità self-chat (ignora le @-mention native, risponde solo ai pattern di testo): +Includi il tuo numero in `allowFrom` per abilitare la modalità chat con sé stessi (ignora le @-mention native, risponde solo ai pattern di testo): ```json5 { @@ -822,21 +822,21 @@ Includi il tuo numero in `allowFrom` per abilitare la modalità self-chat (ignor } ``` -### Comandi (gestione dei comandi chat) +### Comandi (gestione dei comandi in chat) ```json5 { commands: { - native: "auto", // register native commands when supported - nativeSkills: "auto", // register native skill commands when supported - text: true, // parse /commands in chat messages - bash: false, // allow ! (alias: /bash) + native: "auto", // registra i comandi nativi quando supportati + nativeSkills: "auto", // registra i comandi nativi delle Skills quando supportati + text: true, // analizza i /comandi nei messaggi di chat + bash: false, // consenti ! (alias: /bash) bashForegroundMs: 2000, - config: false, // allow /config - mcp: false, // allow /mcp - plugins: false, // allow /plugins - debug: false, // allow /debug - restart: true, // allow /restart + gateway restart tool + config: false, // consenti /config + mcp: false, // consenti /mcp + plugins: false, // consenti /plugins + debug: false, // consenti /debug + restart: true, // consenti /restart + strumento di riavvio del gateway ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -851,38 +851,38 @@ Includi il tuo numero in `allowFrom` per abilitare la modalità self-chat (ignor -- Questo blocco configura le superfici di comando. Per il catalogo di comandi integrato + bundled attuale, vedi [Comandi slash](/it/tools/slash-commands). -- Questa pagina è un **riferimento delle chiavi di configurazione**, non il catalogo completo dei comandi. I comandi gestiti da canali/plugin come QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` e Talk `/voice` sono documentati nelle rispettive pagine di canale/plugin oltre che in [Comandi slash](/it/tools/slash-commands). -- I comandi di testo devono essere messaggi **standalone** con `/` iniziale. -- `native: "auto"` attiva i comandi nativi per Discord/Telegram e lascia Slack disattivato. -- `nativeSkills: "auto"` attiva i comandi nativi delle Skills per Discord/Telegram e lascia Slack disattivato. -- Override per canale: `channels.discord.commands.native` (bool o `"auto"`). `false` cancella i comandi registrati in precedenza. +- Questo blocco configura le superfici dei comandi. Per il catalogo corrente dei comandi integrati + bundled, vedi [Comandi slash](/it/tools/slash-commands). +- Questa pagina è un **riferimento delle chiavi di configurazione**, non il catalogo completo dei comandi. I comandi posseduti da canali/plugin come QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` e Talk `/voice` sono documentati nelle rispettive pagine del canale/plugin e in [Comandi slash](/it/tools/slash-commands). +- I comandi testuali devono essere messaggi **autonomi** con `/` iniziale. +- `native: "auto"` attiva i comandi nativi per Discord/Telegram, lascia Slack disattivato. +- `nativeSkills: "auto"` attiva i comandi nativi delle Skills per Discord/Telegram, lascia Slack disattivato. +- Override per canale: `channels.discord.commands.native` (bool oppure `"auto"`). `false` cancella i comandi registrati in precedenza. - Sovrascrivi la registrazione nativa delle Skills per canale con `channels..commands.nativeSkills`. - `channels.telegram.customCommands` aggiunge voci extra al menu del bot Telegram. -- `bash: true` abilita `! ` per la shell host. Richiede `tools.elevated.enabled` e il mittente in `tools.elevated.allowFrom.`. -- `config: true` abilita `/config` (legge/scrive `openclaw.json`). Per i client `chat.send` del Gateway, le scritture persistenti `/config set|unset` richiedono anche `operator.admin`; il comando di sola lettura `/config show` resta disponibile ai normali client operatore con ambito di scrittura. -- `mcp: true` abilita `/mcp` per la configurazione del server MCP gestita da OpenClaw sotto `mcp.servers`. -- `plugins: true` abilita `/plugins` per discovery dei Plugin, installazione e controlli di abilitazione/disabilitazione. -- `channels..configWrites` controlla le mutazioni della configurazione per canale (predefinito: true). -- Per i canali multi-account, `channels..accounts..configWrites` controlla anche le scritture che hanno come target quell'account (per esempio `/allowlist --config --account ` o `/config set channels..accounts....`). -- `restart: false` disabilita `/restart` e le azioni dello strumento di riavvio del Gateway. Predefinito: `true`. -- `ownerAllowFrom` è l'allowlist esplicita del proprietario per comandi/strumenti riservati al proprietario. È separata da `allowFrom`. -- `ownerDisplay: "hash"` esegue l'hash degli ID proprietario nel prompt di sistema. Imposta `ownerDisplaySecret` per controllare l'hashing. -- `allowFrom` è per-provider. Quando è impostato, è l'**unica** fonte di autorizzazione (le allowlist/pairing del canale e `useAccessGroups` vengono ignorati). +- `bash: true` abilita `! ` per la shell host. Richiede `tools.elevated.enabled` e mittente in `tools.elevated.allowFrom.`. +- `config: true` abilita `/config` (legge/scrive `openclaw.json`). Per i client `chat.send` del gateway, le scritture persistenti `/config set|unset` richiedono anche `operator.admin`; `/config show` in sola lettura resta disponibile ai normali client operatore con ambito di scrittura. +- `mcp: true` abilita `/mcp` per la configurazione del server MCP gestito da OpenClaw in `mcp.servers`. +- `plugins: true` abilita `/plugins` per il rilevamento dei plugin, l'installazione e i controlli di abilitazione/disabilitazione. +- `channels..configWrites` regola le mutazioni di configurazione per canale (predefinito: true). +- Per i canali multi-account, `channels..accounts..configWrites` regola anche le scritture che hanno come destinazione quell'account (ad esempio `/allowlist --config --account ` o `/config set channels..accounts....`). +- `restart: false` disabilita `/restart` e le azioni dello strumento di riavvio del gateway. Predefinito: `true`. +- `ownerAllowFrom` è l'allowlist esplicita del proprietario per i comandi/strumenti riservati al proprietario. È separata da `allowFrom`. +- `ownerDisplay: "hash"` applica l'hash agli ID del proprietario nel prompt di sistema. Imposta `ownerDisplaySecret` per controllare l'hash. +- `allowFrom` è per provider. Quando è impostato, è l'**unica** fonte di autorizzazione (le allowlist/pairing del canale e `useAccessGroups` vengono ignorati). - `useAccessGroups: false` consente ai comandi di bypassare i criteri dei gruppi di accesso quando `allowFrom` non è impostato. - Mappa della documentazione dei comandi: - catalogo integrato + bundled: [Comandi slash](/it/tools/slash-commands) - - superfici di comando specifiche del canale: [Canali](/it/channels) + - superfici dei comandi specifiche del canale: [Canali](/it/channels) - comandi QQ Bot: [QQ Bot](/it/channels/qqbot) - comandi di pairing: [Pairing](/it/channels/pairing) - - comando card di LINE: [LINE](/it/channels/line) + - comando scheda LINE: [LINE](/it/channels/line) - dreaming della memoria: [Dreaming](/it/concepts/dreaming) --- -## Valori predefiniti degli agenti +## Valori predefiniti dell'agente ### `agents.defaults.workspace` @@ -914,17 +914,17 @@ Allowlist predefinita facoltativa delle Skills per gli agenti che non impostano agents: { defaults: { skills: ["github", "weather"] }, list: [ - { id: "writer" }, // inherits github, weather - { id: "docs", skills: ["docs-search"] }, // replaces defaults - { id: "locked-down", skills: [] }, // no skills + { id: "writer" }, // eredita github, weather + { id: "docs", skills: ["docs-search"] }, // sostituisce i valori predefiniti + { id: "locked-down", skills: [] }, // nessuna Skills ], }, } ``` -- Ometti `agents.defaults.skills` per avere Skills non limitate 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. +- Imposta `agents.list[].skills: []` per nessuna Skills. - Un elenco non vuoto `agents.list[].skills` è l'insieme finale per quell'agente; non viene unito ai valori predefiniti. @@ -942,7 +942,7 @@ Disabilita la creazione automatica dei file bootstrap della workspace (`AGENTS.m Controlla quando i file bootstrap della workspace vengono iniettati nel prompt di sistema. Predefinito: `"always"`. -- `"continuation-skip"`: i turni di continuazione sicuri (dopo una risposta completata dell'assistente) saltano la re-iniezione del bootstrap della workspace, riducendo la dimensione del prompt. Le esecuzioni Heartbeat e i retry post-Compaction ricostruiscono comunque il contesto. +- `"continuation-skip"`: i turni di continuazione sicura (dopo una risposta dell'assistente completata) saltano la reiniezione del bootstrap della workspace, riducendo la dimensione del prompt. Le esecuzioni di Heartbeat e i retry dopo Compaction ricostruiscono comunque il contesto. ```json5 { @@ -977,7 +977,7 @@ Predefinito: `"once"`. - `"off"`: non iniettare mai il testo di avviso nel prompt di sistema. - `"once"`: inietta l'avviso una volta per ogni firma di troncamento univoca (consigliato). -- `"always"`: inietta l'avviso a ogni esecuzione quando è presente un troncamento. +- `"always"`: inietta l'avviso a ogni esecuzione quando esiste un troncamento. ```json5 { @@ -987,22 +987,22 @@ Predefinito: `"once"`. ### Mappa di proprietà del budget di contesto -OpenClaw ha più budget di prompt/contesto ad alto volume, e sono -intenzionalmente suddivisi per sottosistema invece di confluire tutti in -un'unica impostazione generica. +OpenClaw ha più budget di prompt/contesto ad alto volume e sono +intenzionalmente suddivisi per sottosistema invece di fluire tutti attraverso un +unico parametro generico. - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: normale iniezione bootstrap della workspace. - `agents.defaults.startupContext.*`: - preludio di avvio one-shot di `/new` e `/reset`, inclusi i file recenti - `memory/*.md`. + preludio di avvio one-shot per `/new` e `/reset`, inclusi i recenti file + giornalieri `memory/*.md`. - `skills.limits.*`: l'elenco compatto delle Skills iniettato nel prompt di sistema. - `agents.defaults.contextLimits.*`: - estratti runtime delimitati e blocchi iniettati di proprietà del runtime. + estratti runtime delimitati e blocchi posseduti dal runtime iniettati. - `memory.qmd.limits.*`: - dimensionamento di snippet di ricerca in memoria indicizzata e della loro iniezione. + dimensionamento degli snippet di ricerca nella memoria indicizzata e dell'iniezione. Usa l'override per agente corrispondente solo quando un agente necessita di un budget diverso: @@ -1012,8 +1012,8 @@ budget diverso: #### `agents.defaults.startupContext` -Controlla il preludio di avvio del primo turno iniettato nelle esecuzioni -di `/new` e `/reset` senza altri argomenti. +Controlla il preludio di avvio del primo turno iniettato nelle esecuzioni `/new` e `/reset` +senza altri parametri. ```json5 { @@ -1055,14 +1055,14 @@ Valori predefiniti condivisi per le superfici di contesto runtime delimitate. metadati di troncamento e avviso di continuazione. - `memoryGetDefaultLines`: finestra di righe predefinita di `memory_get` quando `lines` viene omesso. -- `toolResultMaxChars`: limite live del risultato degli strumenti usato per risultati persistiti e - recupero dell'overflow. -- `postCompactionMaxChars`: limite dell'estratto AGENTS.md usato durante l'iniezione di refresh +- `toolResultMaxChars`: limite live del risultato dello strumento usato per risultati persistiti e + recupero da overflow. +- `postCompactionMaxChars`: limite dell'estratto di AGENTS.md usato durante l'iniezione di aggiornamento post-Compaction. #### `agents.list[].contextLimits` -Override per agente delle impostazioni condivise `contextLimits`. I campi omessi ereditano +Override per agente dei parametri condivisi di `contextLimits`. I campi omessi ereditano da `agents.defaults.contextLimits`. ```json5 @@ -1123,10 +1123,10 @@ Override per agente del budget del prompt delle Skills. ### `agents.defaults.imageMaxDimensionPx` -Dimensione massima in pixel del lato più lungo dell'immagine nei blocchi immagine del transcript/strumenti prima delle chiamate al provider. +Dimensione massima in pixel del lato più lungo dell'immagine nei blocchi immagine di trascrizione/strumento prima delle chiamate al provider. Predefinito: `1200`. -Valori più bassi di solito riducono l'uso di vision token e la dimensione del payload della richiesta nelle esecuzioni con molti screenshot. +Valori più bassi in genere riducono l'uso di vision token e la dimensione del payload della richiesta nelle esecuzioni ricche di screenshot. Valori più alti preservano più dettaglio visivo. ```json5 @@ -1137,7 +1137,7 @@ Valori più alti preservano più dettaglio visivo. ### `agents.defaults.userTimezone` -Fuso orario per il contesto del prompt di sistema (non per i timestamp dei messaggi). Se non impostato, usa il fuso orario dell'host. +Fuso orario per il contesto del prompt di sistema (non i timestamp dei messaggi). Usa come fallback il fuso orario dell'host. ```json5 { @@ -1185,9 +1185,9 @@ Formato dell'ora nel prompt di sistema. Predefinito: `auto` (preferenza del sist primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // global default provider params + params: { cacheRetention: "long" }, // parametri globali predefiniti del provider embeddedHarness: { - runtime: "auto", // auto | pi | registered harness id, e.g. codex + runtime: "auto", // auto | pi | id harness registrato, ad es. codex fallback: "pi", // pi | none }, pdfMaxBytesMb: 10, @@ -1208,44 +1208,44 @@ Formato dell'ora nel prompt di sistema. Predefinito: `auto` (preferenza del sist - La forma stringa imposta solo il modello primario. - La forma oggetto imposta il primario più i modelli di failover ordinati. - `imageModel`: accetta una stringa (`"provider/model"`) oppure un oggetto (`{ primary, fallbacks }`). - - Usato dal percorso dello strumento `image` come configurazione del suo modello vision. + - Usato dal percorso dello strumento `image` come configurazione del modello di visione. - Usato anche come routing di fallback quando il modello selezionato/predefinito non può accettare input immagine. - `imageGenerationModel`: accetta una stringa (`"provider/model"`) oppure un oggetto (`{ primary, fallbacks }`). - - Usato dalla capacità condivisa di generazione immagini e da qualsiasi futura superficie di strumenti/plugin che generi immagini. - - Valori tipici: `google/gemini-3.1-flash-image-preview` per la generazione nativa di immagini Gemini, `fal/fal-ai/flux/dev` per fal, oppure `openai/gpt-image-1` per OpenAI Images. - - Se selezioni direttamente un provider/modello, configura anche l'autenticazione/API key del provider corrispondente (per esempio `GEMINI_API_KEY` o `GOOGLE_API_KEY` per `google/*`, `OPENAI_API_KEY` per `openai/*`, `FAL_KEY` per `fal/*`). - - Se omesso, `image_generate` può comunque dedurre un provider predefinito supportato dall'autenticazione. Prova prima il provider predefinito corrente, poi i restanti provider di generazione immagini registrati in ordine di provider-id. + - Usato dalla funzionalità condivisa di generazione immagini e da qualsiasi futura superficie di strumenti/plugin che generi immagini. + - Valori tipici: `google/gemini-3.1-flash-image-preview` per la generazione immagini nativa di Gemini, `fal/fal-ai/flux/dev` per fal, oppure `openai/gpt-image-1` per OpenAI Images. + - Se selezioni direttamente un provider/modello, configura anche l'autenticazione/la chiave API del provider corrispondente (ad esempio `GEMINI_API_KEY` o `GOOGLE_API_KEY` per `google/*`, `OPENAI_API_KEY` per `openai/*`, `FAL_KEY` per `fal/*`). + - Se omesso, `image_generate` può comunque dedurre un valore predefinito del provider supportato da autenticazione. Prova prima il provider predefinito corrente, poi i restanti provider di generazione immagini registrati in ordine di ID provider. - `musicGenerationModel`: accetta una stringa (`"provider/model"`) oppure un oggetto (`{ primary, fallbacks }`). - - Usato dalla capacità condivisa di generazione musicale e dallo strumento integrato `music_generate`. + - Usato dalla funzionalità condivisa di generazione musicale e dallo strumento integrato `music_generate`. - Valori tipici: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` oppure `minimax/music-2.5+`. - - Se omesso, `music_generate` può comunque dedurre un provider predefinito supportato dall'autenticazione. Prova prima il provider predefinito corrente, poi i restanti provider di generazione musicale registrati in ordine di provider-id. - - Se selezioni direttamente un provider/modello, configura anche l'autenticazione/API key del provider corrispondente. + - Se omesso, `music_generate` può comunque dedurre un valore predefinito del provider supportato da autenticazione. Prova prima il provider predefinito corrente, poi i restanti provider di generazione musicale registrati in ordine di ID provider. + - Se selezioni direttamente un provider/modello, configura anche l'autenticazione/la chiave API del provider corrispondente. - `videoGenerationModel`: accetta una stringa (`"provider/model"`) oppure un oggetto (`{ primary, fallbacks }`). - - Usato dalla capacità condivisa di generazione video e dallo strumento integrato `video_generate`. + - Usato dalla funzionalità condivisa di generazione video e dallo strumento integrato `video_generate`. - Valori tipici: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` oppure `qwen/wan2.7-r2v`. - - Se omesso, `video_generate` può comunque dedurre un provider predefinito supportato dall'autenticazione. Prova prima il provider predefinito corrente, poi i restanti provider di generazione video registrati in ordine di provider-id. - - Se selezioni direttamente un provider/modello, configura anche l'autenticazione/API key del provider corrispondente. - - Il provider bundled di generazione video Qwen supporta fino a 1 video in output, 1 immagine in input, 4 video in input, durata di 10 secondi e opzioni a livello provider `size`, `aspectRatio`, `resolution`, `audio` e `watermark`. + - Se omesso, `video_generate` può comunque dedurre un valore predefinito del provider supportato da autenticazione. Prova prima il provider predefinito corrente, poi i restanti provider di generazione video registrati in ordine di ID provider. + - Se selezioni direttamente un provider/modello, configura anche l'autenticazione/la chiave API del provider corrispondente. + - Il provider bundled di generazione video Qwen supporta fino a 1 video 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 torna a `imageModel`, poi al modello risolto della sessione/predefinito. + - Se omesso, lo strumento PDF usa come fallback `imageModel`, poi il modello risolto della sessione/predefinito. - `pdfMaxBytesMb`: limite di dimensione PDF predefinito per lo strumento `pdf` quando `maxBytesMb` non viene passato al momento della chiamata. -- `pdfMaxPages`: numero massimo di pagine considerato in modalità fallback di estrazione nello strumento `pdf`. +- `pdfMaxPages`: numero massimo di pagine 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 di provider configurato per quell'esatto model id, e solo dopo torna al provider predefinito configurato (comportamento di compatibilità deprecato, quindi preferisci `provider/model` esplicito). Se quel provider non espone più il modello predefinito configurato, OpenClaw torna al primo provider/modello configurato invece di esporre un predefinito obsoleto di un provider rimosso. -- `models`: il catalogo e la allowlist dei modelli configurati per `/model`. Ogni voce può includere `alias` (scorciatoia) e `params` (specifici del provider, per esempio `temperature`, `maxTokens`, `cacheRetention`, `context1m`). -- `params`: parametri predefiniti globali del provider applicati a tutti i modelli. Impostali in `agents.defaults.params` (ad es. `{ cacheRetention: "long" }`). -- Precedenza di merge di `params` (config): `agents.defaults.params` (base globale) viene sovrascritto da `agents.defaults.models["provider/model"].params` (per modello), poi `agents.list[].params` (ID agente corrispondente) sovrascrive per chiave. Vedi [Prompt Caching](/it/reference/prompt-caching) per i dettagli. -- `embeddedHarness`: criterio predefinito del runtime embedded a basso livello per agenti. Usa `runtime: "auto"` per lasciare che gli harness dei plugin registrati prendano in carico i modelli supportati, `runtime: "pi"` per forzare l'harness PI integrato, oppure un id di harness registrato come `runtime: "codex"`. Imposta `fallback: "none"` per disabilitare il fallback automatico a Pi. -- I writer di configurazione che modificano questi campi (per esempio `/models set`, `/models set-image` e i comandi add/remove dei fallback) salvano la forma oggetto canonica e preservano gli elenchi di fallback esistenti quando possibile. +- `model.primary`: formato `provider/model` (ad es. `openai/gpt-5.4`). Se ometti il provider, OpenClaw prova prima un alias, poi una corrispondenza univoca del provider configurato per quell'esatto ID modello e solo dopo torna al provider predefinito configurato (comportamento di compatibilità deprecato, quindi preferisci `provider/model` esplicito). Se quel provider non espone più il modello predefinito configurato, OpenClaw usa come fallback il primo provider/modello configurato invece di mostrare un valore predefinito obsoleto di un provider rimosso. +- `models`: il catalogo e l'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. Imposta in `agents.defaults.params` (ad es. `{ cacheRetention: "long" }`). +- Precedenza di merge di `params` (config): `agents.defaults.params` (base globale) viene sovrascritto da `agents.defaults.models["provider/model"].params` (per modello), poi `agents.list[].params` (ID agente corrispondente) sovrascrive per chiave. Vedi [Caching dei prompt](/it/reference/prompt-caching) per i dettagli. +- `embeddedHarness`: criterio predefinito di basso livello per il runtime dell'agente incorporato. Usa `runtime: "auto"` per lasciare che gli harness dei plugin registrati rivendichino i modelli supportati, `runtime: "pi"` per forzare l'harness PI integrato, oppure un ID harness registrato come `runtime: "codex"`. Imposta `fallback: "none"` per disabilitare il fallback automatico a PI. +- Gli strumenti di scrittura della configurazione che modificano questi campi (ad esempio `/models set`, `/models set-image` e i comandi di aggiunta/rimozione fallback) salvano la forma oggetto canonica e preservano gli elenchi fallback esistenti quando possibile. - `maxConcurrent`: massimo numero di esecuzioni parallele degli agenti tra le sessioni (ogni sessione resta comunque serializzata). Predefinito: 4. ### `agents.defaults.embeddedHarness` -`embeddedHarness` controlla quale esecutore di basso livello esegue i turni degli agenti embedded. +`embeddedHarness` controlla quale esecutore di basso livello esegue i turni degli agenti incorporati. La maggior parte dei deployment dovrebbe mantenere il valore predefinito `{ runtime: "auto", fallback: "pi" }`. -Usalo quando un Plugin attendibile fornisce un harness nativo, come l'harness +Usalo quando un plugin affidabile fornisce un harness nativo, come l'harness bundled del server app Codex. ```json5 @@ -1262,11 +1262,11 @@ bundled del server app Codex. } ``` -- `runtime`: `"auto"`, `"pi"` o un id di harness di Plugin registrato. Il Plugin bundled Codex registra `codex`. -- `fallback`: `"pi"` oppure `"none"`. `"pi"` mantiene l'harness PI integrato come fallback di compatibilità. `"none"` fa fallire la selezione dell'harness di Plugin mancante o non supportato invece di usare silenziosamente Pi. -- Override tramite ambiente: `OPENCLAW_AGENT_RUNTIME=` sovrascrive `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` disabilita il fallback a Pi per quel processo. -- Per deployment solo-Codex, imposta `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` e `embeddedHarness.fallback: "none"`. -- Questo controlla solo l'harness chat embedded. Generazione media, vision, PDF, musica, video e TTS continuano a usare le rispettive impostazioni provider/modello. +- `runtime`: `"auto"`, `"pi"` oppure un ID harness plugin registrato. Il plugin bundled Codex registra `codex`. +- `fallback`: `"pi"` oppure `"none"`. `"pi"` mantiene l'harness PI integrato come fallback di compatibilità. `"none"` fa fallire la selezione di un harness plugin mancante o non supportato invece di usare silenziosamente PI. +- Override tramite ambiente: `OPENCLAW_AGENT_RUNTIME=` sovrascrive `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` disabilita il fallback a PI per quel processo. +- Per deployment solo Codex, imposta `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` e `embeddedHarness.fallback: "none"`. +- Questo controlla solo l'harness di chat incorporato. Generazione media, visione, PDF, musica, video e TTS usano comunque le rispettive impostazioni provider/modello. **Scorciatoie alias integrate** (si applicano solo quando il modello è in `agents.defaults.models`): @@ -1281,15 +1281,15 @@ bundled del server app Codex. | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -I tuoi alias configurati hanno sempre la precedenza sui valori predefiniti. +Gli alias che configuri hanno sempre precedenza sui valori predefiniti. I modelli Z.AI GLM-4.x abilitano automaticamente la modalità thinking a meno che tu non imposti `--thinking off` o definisca tu stesso `agents.defaults.models["zai/"].params.thinking`. I modelli Z.AI abilitano `tool_stream` per impostazione predefinita per lo streaming delle chiamate agli strumenti. Imposta `agents.defaults.models["zai/"].params.tool_stream` su `false` per disabilitarlo. -I modelli Anthropic Claude 4.6 usano per impostazione predefinita thinking `adaptive` quando non è impostato un livello di thinking esplicito. +I modelli Anthropic Claude 4.6 usano `adaptive` thinking per impostazione predefinita quando non è impostato alcun livello di thinking esplicito. ### `agents.defaults.cliBackends` -CLI backend facoltativi per esecuzioni di fallback solo testo (senza chiamate a strumenti). Utili come backup quando i provider API falliscono. +CLI backend facoltativi per esecuzioni di fallback solo testo (senza chiamate agli strumenti). Utile come backup quando i provider API falliscono. ```json5 { @@ -1317,13 +1317,13 @@ CLI backend facoltativi per esecuzioni di fallback solo testo (senza chiamate a } ``` -- I CLI backend sono orientati al testo; gli strumenti sono sempre disabilitati. +- I CLI backend sono pensati prima di tutto per il testo; gli strumenti sono sempre disabilitati. - Le sessioni sono supportate quando `sessionArg` è impostato. -- Il pass-through delle immagini è supportato quando `imageArg` accetta percorsi file. +- Il pass-through delle immagini è supportato quando `imageArg` accetta percorsi di file. ### `agents.defaults.systemPromptOverride` -Sostituisce l'intero prompt di sistema assemblato da OpenClaw con una stringa fissa. Impostalo a livello predefinito (`agents.defaults.systemPromptOverride`) o per agente (`agents.list[].systemPromptOverride`). I valori per agente hanno la precedenza; un valore vuoto o composto solo da spazi viene ignorato. Utile per esperimenti controllati sul prompt. +Sostituisce l'intero prompt di sistema assemblato da OpenClaw con una stringa fissa. Imposta a livello predefinito (`agents.defaults.systemPromptOverride`) oppure per agente (`agents.list[].systemPromptOverride`). I valori per agente hanno la precedenza; un valore vuoto o composto solo da spazi viene ignorato. Utile per esperimenti controllati sul prompt. ```json5 { @@ -1344,16 +1344,16 @@ Esecuzioni periodiche di Heartbeat. agents: { defaults: { heartbeat: { - every: "30m", // 0m disables + every: "30m", // 0m disabilita model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt - lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files - isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) + includeSystemPromptSection: true, // predefinito: true; false omette la sezione Heartbeat dal prompt di sistema + lightContext: false, // predefinito: false; true mantiene solo HEARTBEAT.md dai file bootstrap della workspace + isolatedSession: false, // predefinito: false; true esegue ogni heartbeat in una sessione nuova (nessuna cronologia della conversazione) session: "main", to: "+15555550123", - directPolicy: "allow", // allow (default) | block - target: "none", // default: none | options: last | whatsapp | telegram | discord | ... + directPolicy: "allow", // allow (predefinito) | block + target: "none", // predefinito: none | opzioni: last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, @@ -1364,14 +1364,14 @@ Esecuzioni periodiche di Heartbeat. } ``` -- `every`: stringa di durata (ms/s/m/h). Predefinito: `30m` (autenticazione con API key) oppure `1h` (autenticazione OAuth). Imposta `0m` per disabilitare. +- `every`: stringa di durata (ms/s/m/h). Predefinito: `30m` (autenticazione con chiave API) oppure `1h` (autenticazione OAuth). Imposta `0m` per disabilitare. - `includeSystemPromptSection`: quando è false, omette la sezione Heartbeat dal prompt di sistema e salta l'iniezione di `HEARTBEAT.md` nel contesto bootstrap. Predefinito: `true`. -- `suppressToolErrorWarnings`: quando è true, sopprime i payload di avviso di errore degli strumenti durante le esecuzioni Heartbeat. +- `suppressToolErrorWarnings`: quando è true, sopprime i payload di avviso di errore degli strumenti durante le esecuzioni di Heartbeat. - `timeoutSeconds`: tempo massimo in secondi consentito per un turno agente Heartbeat prima che venga interrotto. Lascialo non impostato per usare `agents.defaults.timeoutSeconds`. -- `directPolicy`: criterio di consegna diretta/DM. `allow` (predefinito) consente la consegna a target diretto. `block` sopprime la consegna a target diretto ed emette `reason=dm-blocked`. -- `lightContext`: quando è true, le esecuzioni Heartbeat usano un contesto bootstrap leggero e mantengono solo `HEARTBEAT.md` tra i file bootstrap della workspace. -- `isolatedSession`: quando è true, ogni esecuzione Heartbeat avviene in una sessione nuova senza cronologia di conversazione precedente. Stesso schema di isolamento di Cron `sessionTarget: "isolated"`. Riduce il costo in token per Heartbeat da ~100K a ~2-5K token. -- Per agente: imposta `agents.list[].heartbeat`. Quando un agente definisce `heartbeat`, **solo quegli agenti** eseguono Heartbeat. +- `directPolicy`: criterio di consegna diretta/DM. `allow` (predefinito) consente la consegna diretta al target. `block` sopprime la consegna diretta al target ed emette `reason=dm-blocked`. +- `lightContext`: quando è true, le esecuzioni di Heartbeat usano un contesto bootstrap leggero e mantengono solo `HEARTBEAT.md` dai file bootstrap della workspace. +- `isolatedSession`: quando è true, ogni esecuzione di Heartbeat viene eseguita in una sessione nuova senza cronologia conversazionale precedente. Stesso schema di isolamento di Cron `sessionTarget: "isolated"`. Riduce il costo in token per Heartbeat da circa 100K a circa 2-5K token. +- Per agente: imposta `agents.list[].heartbeat`. Quando un qualsiasi agente definisce `heartbeat`, **solo quegli agenti** eseguono Heartbeat. - Gli Heartbeat eseguono turni completi dell'agente: intervalli più brevi consumano più token. ### `agents.defaults.compaction` @@ -1382,14 +1382,14 @@ Esecuzioni periodiche di Heartbeat. defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // id of a registered compaction provider plugin (optional) + provider: "my-provider", // id di un plugin provider di Compaction registrato (facoltativo) 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 - model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override - notifyUser: true, // send a brief notice when compaction starts (default: false) + identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // usato quando identifierPolicy=custom + postCompactionSections: ["Session Startup", "Red Lines"], // [] disabilita la reiniezione + model: "openrouter/anthropic/claude-sonnet-4-6", // override facoltativo del modello solo per Compaction + notifyUser: true, // invia una breve notifica quando inizia Compaction (predefinito: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -1402,19 +1402,19 @@ Esecuzioni periodiche di Heartbeat. } ``` -- `mode`: `default` oppure `safeguard` (riepilogo a blocchi per cronologie lunghe). Vedi [Compaction](/it/concepts/compaction). -- `provider`: id di un Plugin provider di Compaction registrato. Quando è impostato, viene chiamato `summarize()` del provider al posto del riepilogo LLM integrato. In caso di errore torna al comportamento integrato. L'impostazione di un provider forza `mode: "safeguard"`. Vedi [Compaction](/it/concepts/compaction). +- `mode`: `default` oppure `safeguard` (riepilogo suddiviso in blocchi per cronologie lunghe). Vedi [Compaction](/it/concepts/compaction). +- `provider`: id di un plugin provider di Compaction registrato. Quando è impostato, viene chiamato `summarize()` del provider invece del riepilogo LLM integrato. In caso di errore torna al comportamento integrato. Impostare un provider forza `mode: "safeguard"`. Vedi [Compaction](/it/concepts/compaction). - `timeoutSeconds`: numero massimo di secondi consentiti per una singola operazione di Compaction prima che OpenClaw la interrompa. Predefinito: `900`. -- `identifierPolicy`: `strict` (predefinito), `off` oppure `custom`. `strict` antepone linee guida integrate per la conservazione degli identificatori opachi durante il riepilogo di Compaction. -- `identifierInstructions`: testo personalizzato facoltativo per la conservazione degli identificatori usato quando `identifierPolicy=custom`. -- `postCompactionSections`: nomi facoltativi di sezioni H2/H3 di AGENTS.md da reiniettare dopo la Compaction. Il valore predefinito è `["Session Startup", "Red Lines"]`; imposta `[]` per disabilitare la reiniezione. Quando non è impostato o viene impostato esplicitamente a quella coppia predefinita, vengono accettate anche le intestazioni legacy `Every Session`/`Safety` come fallback legacy. -- `model`: override facoltativo `provider/model-id` solo per il riepilogo di Compaction. Usalo quando la sessione principale deve mantenere un modello ma i riepiloghi di Compaction devono essere eseguiti con un altro; se non impostato, la Compaction usa il modello primario della sessione. -- `notifyUser`: quando `true`, invia una breve notifica all'utente quando inizia la Compaction (per esempio, "Compacting context..."). Disabilitato per impostazione predefinita per mantenere la Compaction silenziosa. -- `memoryFlush`: turno agentico silenzioso prima dell'auto-Compaction per memorizzare ricordi durevoli. Viene saltato quando la workspace è in sola lettura. +- `identifierPolicy`: `strict` (predefinito), `off` oppure `custom`. `strict` antepone linee guida integrate per la conservazione di identificatori opachi durante il riepilogo di Compaction. +- `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 Compaction. Il valore predefinito è `["Session Startup", "Red Lines"]`; imposta `[]` per disabilitare la reiniezione. Quando non è impostato oppure è impostato esplicitamente su quella coppia predefinita, come fallback legacy vengono accettate anche le vecchie intestazioni `Every Session`/`Safety`. +- `model`: override facoltativo `provider/model-id` solo per il riepilogo di Compaction. Usalo quando la sessione principale deve mantenere un modello ma i riepiloghi di Compaction devono essere eseguiti con un altro; se non impostato, Compaction usa il modello primario della sessione. +- `notifyUser`: quando è `true`, invia una breve notifica all'utente quando inizia Compaction (ad esempio, "Compacting context..."). Disabilitato per impostazione predefinita per mantenere silenziosa Compaction. +- `memoryFlush`: turno agentico silenzioso prima della Compaction automatica per memorizzare memorie durevoli. Saltato quando la workspace è in sola lettura. ### `agents.defaults.contextPruning` -Esegue il pruning dei **vecchi risultati degli strumenti** dal contesto in memoria prima dell'invio all'LLM. **Non** modifica la cronologia della sessione su disco. +Rimuove **vecchi risultati degli strumenti** dal contesto in memoria prima dell'invio all'LLM. **Non** modifica la cronologia della sessione su disco. ```json5 { @@ -1422,7 +1422,7 @@ Esegue il pruning dei **vecchi risultati degli strumenti** dal contesto in memor defaults: { contextPruning: { mode: "cache-ttl", // off | cache-ttl - ttl: "1h", // duration (ms/s/m/h), default unit: minutes + ttl: "1h", // durata (ms/s/m/h), unità predefinita: minuti keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5, @@ -1438,19 +1438,19 @@ Esegue il pruning dei **vecchi risultati degli strumenti** dal contesto in memor -- `mode: "cache-ttl"` abilita i passaggi di pruning. -- `ttl` controlla la frequenza con cui il pruning può essere eseguito di nuovo (dopo l'ultimo tocco della cache). -- Il pruning prima riduce parzialmente i risultati degli strumenti troppo grandi, poi svuota completamente i risultati più vecchi se necessario. +- `mode: "cache-ttl"` abilita i passaggi di rimozione. +- `ttl` controlla la frequenza con cui la rimozione può essere eseguita di nuovo (dopo l'ultimo aggiornamento della cache). +- La rimozione riduce prima in modo soft i risultati degli strumenti troppo grandi, poi svuota in modo hard i risultati degli strumenti più vecchi se necessario. -**Soft-trim** mantiene inizio + fine e inserisce `...` al centro. +**Soft-trim** mantiene l'inizio + la fine e inserisce `...` nel mezzo. -**Hard-clear** sostituisce l'intero risultato dello strumento con il placeholder. +**Hard-clear** sostituisce l'intero risultato dello strumento con il segnaposto. Note: - I blocchi immagine non vengono mai ridotti o svuotati. - I rapporti sono basati sui caratteri (approssimativi), non su conteggi esatti di token. -- Se esistono meno di `keepLastAssistants` messaggi assistant, il pruning viene saltato. +- Se esistono meno di `keepLastAssistants` messaggi dell'assistente, la rimozione viene saltata. @@ -1466,17 +1466,17 @@ Vedi [Session Pruning](/it/concepts/session-pruning) per i dettagli sul comporta blockStreamingBreak: "text_end", // text_end | message_end blockStreamingChunk: { minChars: 800, maxChars: 1200 }, blockStreamingCoalesce: { idleMs: 1000 }, - humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs) + humanDelay: { mode: "natural" }, // off | natural | custom (usa minMs/maxMs) }, }, } ``` -- I canali non-Telegram richiedono `*.blockStreaming: true` esplicito per abilitare le risposte a blocchi. -- Override di canale: `channels..blockStreamingCoalesce` (e varianti per account). Signal/Slack/Discord/Google Chat usano per impostazione predefinita `minChars: 1500`. -- `humanDelay`: pausa casuale tra le risposte a blocchi. `natural` = 800–2500ms. Override per agente: `agents.list[].humanDelay`. +- I canali non Telegram richiedono `*.blockStreaming: true` esplicito per abilitare le risposte a blocchi. +- Override per canale: `channels..blockStreamingCoalesce` (e varianti per account). Signal/Slack/Discord/Google Chat usano come predefinito `minChars: 1500`. +- `humanDelay`: pausa casuale tra risposte a blocchi. `natural` = 800–2500 ms. Override per agente: `agents.list[].humanDelay`. -Vedi [Streaming](/it/concepts/streaming) per dettagli su comportamento + chunking. +Vedi [Streaming](/it/concepts/streaming) per dettagli su comportamento e suddivisione in blocchi. ### Indicatori di digitazione @@ -1491,7 +1491,7 @@ Vedi [Streaming](/it/concepts/streaming) per dettagli su comportamento + chunkin } ``` -- Valori predefiniti: `instant` per chat dirette/mention, `message` per chat di gruppo senza mention. +- Valori predefiniti: `instant` per chat dirette/menzioni, `message` per chat di gruppo senza menzione. - Override per sessione: `session.typingMode`, `session.typingIntervalSeconds`. Vedi [Indicatori di digitazione](/it/concepts/typing-indicators). @@ -1500,7 +1500,7 @@ Vedi [Indicatori di digitazione](/it/concepts/typing-indicators). ### `agents.defaults.sandbox` -Sandbox facoltativa per l'agente embedded. Vedi [Sandboxing](/it/gateway/sandboxing) per la guida completa. +Sandbox facoltativo per l'agente incorporato. Vedi [Sandboxing](/it/gateway/sandboxing) per la guida completa. ```json5 { @@ -1546,7 +1546,7 @@ Sandbox facoltativa per l'agente embedded. Vedi [Sandboxing](/it/gateway/sandbox identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // SecretRefs / inline contents also supported: + // Sono supportati anche SecretRef / contenuti inline: // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -1595,7 +1595,7 @@ Sandbox facoltativa per l'agente embedded. Vedi [Sandboxing](/it/gateway/sandbox } ``` - + **Backend:** @@ -1603,46 +1603,46 @@ Sandbox facoltativa per l'agente embedded. Vedi [Sandboxing](/it/gateway/sandbox - `ssh`: runtime remoto generico supportato da SSH - `openshell`: runtime OpenShell -Quando viene selezionato `backend: "openshell"`, le impostazioni specifiche del runtime vengono spostate in +Quando è selezionato `backend: "openshell"`, le impostazioni specifiche del runtime si spostano in `plugins.entries.openshell.config`. **Configurazione backend SSH:** - `target`: target SSH nel formato `user@host[:port]` -- `command`: comando del client SSH (predefinito: `ssh`) -- `workspaceRoot`: root remota assoluta usata per le workspace per-scope +- `command`: comando client SSH (predefinito: `ssh`) +- `workspaceRoot`: radice remota assoluta usata per workspace per ambito - `identityFile` / `certificateFile` / `knownHostsFile`: file locali esistenti passati a OpenSSH - `identityData` / `certificateData` / `knownHostsData`: contenuti inline o SecretRef che OpenClaw materializza in file temporanei a runtime -- `strictHostKeyChecking` / `updateHostKeys`: impostazioni del criterio della chiave host di OpenSSH +- `strictHostKeyChecking` / `updateHostKeys`: parametri del criterio di chiave host OpenSSH -**Precedenza dell'autenticazione SSH:** +**Precedenza di autenticazione SSH:** -- `identityData` ha la precedenza su `identityFile` -- `certificateData` ha la precedenza su `certificateFile` -- `knownHostsData` ha la precedenza su `knownHostsFile` -- I valori `*Data` supportati da SecretRef vengono risolti dallo snapshot runtime attivo dei segreti prima dell'avvio della sessione sandbox +- `identityData` ha precedenza su `identityFile` +- `certificateData` ha precedenza su `certificateFile` +- `knownHostsData` ha precedenza su `knownHostsFile` +- I valori `*Data` supportati da SecretRef vengono risolti dallo snapshot runtime attivo dei secret prima dell'avvio della sessione sandbox **Comportamento del backend SSH:** - inizializza la workspace remota una volta dopo la creazione o ricreazione - poi mantiene canonica la workspace SSH remota - instrada `exec`, gli strumenti sui file e i percorsi media tramite SSH -- non sincronizza automaticamente le modifiche remote verso l'host -- non supporta container browser sandbox +- non sincronizza automaticamente le modifiche remote all'host +- non supporta contenitori browser del sandbox **Accesso alla workspace:** -- `none`: workspace sandbox per-scope sotto `~/.openclaw/sandboxes` +- `none`: workspace sandbox per ambito in `~/.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:** +**Ambito:** -- `session`: container + workspace per sessione -- `agent`: un container + workspace per agente (predefinito) -- `shared`: container e workspace condivisi (nessun isolamento tra sessioni) +- `session`: contenitore + workspace per sessione +- `agent`: un contenitore + workspace per agente (predefinito) +- `shared`: contenitore e workspace condivisi (nessun isolamento tra sessioni) -**Configurazione del Plugin OpenShell:** +**Configurazione plugin OpenShell:** ```json5 { @@ -1655,10 +1655,10 @@ Quando viene selezionato `backend: "openshell"`, le impostazioni specifiche del from: "openclaw", remoteWorkspaceDir: "/sandbox", remoteAgentWorkspaceDir: "/agent", - gateway: "lab", // optional - gatewayEndpoint: "https://lab.example", // optional - policy: "strict", // optional OpenShell policy id - providers: ["openai"], // optional + gateway: "lab", // facoltativo + gatewayEndpoint: "https://lab.example", // facoltativo + policy: "strict", // id criterio OpenShell facoltativo + providers: ["openai"], // facoltativo autoProviders: true, timeoutSeconds: 120, }, @@ -1670,29 +1670,29 @@ Quando viene selezionato `backend: "openshell"`, le impostazioni specifiche del **Modalità OpenShell:** -- `mirror`: inizializza il remoto dal locale prima di `exec`, sincronizza indietro dopo `exec`; la workspace locale resta canonica -- `remote`: inizializza il remoto una volta quando la sandbox viene creata, poi mantiene canonica la workspace remota +- `mirror`: inizializza il remoto dal locale prima di exec, sincronizza indietro dopo exec; la workspace locale resta canonica +- `remote`: inizializza il remoto una volta quando il sandbox viene creato, poi mantiene canonica la workspace remota -In modalità `remote`, le modifiche locali sull'host effettuate fuori da OpenClaw non vengono sincronizzate automaticamente nella sandbox dopo il passaggio iniziale di seed. -Il trasporto avviene via SSH verso la sandbox OpenShell, ma il Plugin gestisce il ciclo di vita della sandbox e l'eventuale sincronizzazione mirror. +In modalità `remote`, le modifiche locali sull'host fatte fuori da OpenClaw non vengono sincronizzate automaticamente nel sandbox dopo il passaggio di inizializzazione. +Il trasporto avviene tramite SSH nel sandbox OpenShell, ma il plugin possiede il ciclo di vita del sandbox e l'eventuale sincronizzazione mirror. -**`setupCommand`** viene eseguito una volta dopo la creazione del container (tramite `sh -lc`). Richiede uscita di rete, root scrivibile e utente root. +**`setupCommand`** viene eseguito una volta dopo la creazione del contenitore (tramite `sh -lc`). Richiede uscita di rete, root scrivibile e utente root. -**Per impostazione predefinita i container usano `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 a meno che tu non imposti esplicitamente +**I contenitori usano come predefinito `network: "none"`** — imposta `"bridge"` (o una rete bridge personalizzata) se l'agente necessita di accesso in uscita. +`"host"` è bloccato. `"container:"` è bloccato per impostazione predefinita a meno che non imposti esplicitamente `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (break-glass). -**Gli allegati in ingresso** vengono preparati in `media/inbound/*` nella workspace attiva. +**Gli allegati in ingresso** vengono predisposti in `media/inbound/*` nella workspace attiva. -**`docker.binds`** monta directory host aggiuntive; i bind globali e per-agente vengono uniti. +**`docker.binds`** monta directory host aggiuntive; i bind globali e per agente vengono uniti. -**Browser sandboxed** (`sandbox.browser.enabled`): Chromium + CDP in un container. L'URL noVNC viene iniettata nel prompt di sistema. Non richiede `browser.enabled` in `openclaw.json`. +**Browser sandboxed** (`sandbox.browser.enabled`): Chromium + CDP in un contenitore. L'URL noVNC viene iniettato nel prompt di sistema. Non richiede `browser.enabled` in `openclaw.json`. L'accesso osservatore noVNC usa per impostazione predefinita l'autenticazione VNC e OpenClaw emette un URL con token a breve durata (invece di esporre la password nell'URL condiviso). -- `allowHostControl: false` (predefinito) impedisce alle sessioni sandboxed di avere come target il browser host. -- `network` usa per impostazione predefinita `openclaw-sandbox-browser` (rete bridge dedicata). Imposta `bridge` solo quando vuoi esplicitamente una connettività bridge globale. -- `cdpSourceRange` limita facoltativamente l'ingresso CDP al bordo del container a un intervallo CIDR (per esempio `172.21.0.1/32`). -- `sandbox.browser.binds` monta directory host aggiuntive solo nel container del browser sandboxed. Quando è impostato (incluso `[]`), sostituisce `docker.binds` per il container browser. +- `allowHostControl: false` (predefinito) impedisce alle sessioni sandboxed di puntare al browser host. +- `network` ha come predefinito `openclaw-sandbox-browser` (rete bridge dedicata). Imposta `bridge` solo quando vuoi esplicitamente la connettività bridge globale. +- `cdpSourceRange` limita facoltativamente l'ingresso CDP al bordo del contenitore a un intervallo CIDR (ad 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 container: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` @@ -1714,23 +1714,23 @@ L'accesso osservatore noVNC usa per impostazione predefinita l'autenticazione VN - `--disable-3d-apis`, `--disable-software-rasterizer` e `--disable-gpu` sono abilitati per impostazione predefinita e possono essere disabilitati con `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` se l'uso di WebGL/3D lo richiede. - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` riabilita le estensioni se il tuo workflow + - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` riabilita le estensioni se il tuo flusso di lavoro ne dipende. - `--renderer-process-limit=2` può essere modificato con `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; imposta `0` per usare il - limite di processi predefinito di Chromium. + limite di processo predefinito di Chromium. - più `--no-sandbox` e `--disable-setuid-sandbox` quando `noSandbox` è abilitato. - - I valori predefiniti sono la baseline dell'immagine container; usa un'immagine browser personalizzata con un entrypoint personalizzato per cambiare i valori predefiniti del container. + - I valori predefiniti sono la baseline dell'immagine contenitore; usa un'immagine browser personalizzata con un entrypoint personalizzato per modificare i valori predefiniti del contenitore. -Il browser sandboxing e `sandbox.docker.binds` sono disponibili solo con Docker. +Il sandboxing del browser e `sandbox.docker.binds` sono solo per Docker. -Build delle immagini: +Crea 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 facoltativa ``` ### `agents.list` (override per agente) @@ -1745,13 +1745,13 @@ scripts/sandbox-browser-setup.sh # optional browser image name: "Main Agent", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", - model: "anthropic/claude-opus-4-6", // or { primary, fallbacks } - thinkingDefault: "high", // per-agent thinking level override - reasoningDefault: "on", // per-agent reasoning visibility override - fastModeDefault: false, // per-agent fast mode override + model: "anthropic/claude-opus-4-6", // oppure { primary, fallbacks } + thinkingDefault: "high", // override per agente del livello thinking + reasoningDefault: "on", // override per agente della visibilità del reasoning + fastModeDefault: false, // override per agente della modalità rapida embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // overrides matching defaults.models params by key - skills: ["docs-search"], // replaces agents.defaults.skills when set + params: { cacheRetention: "none" }, // sovrascrive per chiave i params di defaults.models corrispondenti + skills: ["docs-search"], // sostituisce agents.defaults.skills quando impostato identity: { name: "Samantha", theme: "helpful sloth", @@ -1783,26 +1783,26 @@ scripts/sandbox-browser-setup.sh # optional browser image ``` - `id`: ID agente stabile (obbligatorio). -- `default`: quando ne sono impostati più di uno, vince il primo (viene registrato un avviso). Se non ne è impostato nessuno, il predefinito è la prima voce 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` 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; una lista esplicita sostituisce i valori predefiniti invece di unirli, e `[]` significa nessuna Skills. +- `default`: quando ne sono impostati più di uno, vince il primo (viene registrato un avviso). Se non ne è impostato nessuno, il valore predefinito è la prima voce dell'elenco. +- `model`: la forma stringa sovrascrive solo `primary`; la forma oggetto `{ primary, fallbacks }` sovrascrive entrambi (`[]` disabilita i fallback globali). I job Cron che sovrascrivono solo `primary` ereditano comunque i fallback predefiniti a meno che non imposti `fallbacks: []`. +- `params`: params di stream per agente uniti sopra la voce del modello selezionato in `agents.defaults.models`. Usali per override specifici dell'agente come `cacheRetention`, `temperature` o `maxTokens` senza duplicare l'intero catalogo modelli. +- `skills`: allowlist facoltativa delle Skills per agente. Se omessa, l'agente eredita `agents.defaults.skills` quando è impostato; un elenco esplicito sostituisce i valori predefiniti invece di unirsi a essi, 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 sessione. -- `reasoningDefault`: visibilità reasoning predefinita facoltativa per agente (`on | off | stream`). Si applica quando non è impostato alcun override reasoning per messaggio o sessione. -- `fastModeDefault`: valore predefinito facoltativo per agente per la modalità veloce (`true | false`). Si applica quando non è impostato alcun override della modalità veloce per messaggio o sessione. -- `embeddedHarness`: override facoltativo per agente del criterio di harness di basso livello. Usa `{ runtime: "codex", fallback: "none" }` per rendere un agente solo-Codex mentre gli altri agenti mantengono il fallback predefinito a Pi. +- `reasoningDefault`: visibilità 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 modalità rapida (`true | false`). Si applica quando non è impostato alcun override della modalità rapida per messaggio o sessione. +- `embeddedHarness`: override facoltativo del criterio di harness di basso livello per agente. Usa `{ runtime: "codex", fallback: "none" }` per rendere un agente solo Codex mentre gli altri agenti mantengono il fallback PI predefinito. - `runtime`: descrittore runtime facoltativo per agente. Usa `type: "acp"` con i valori predefiniti di `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) quando l'agente deve usare per impostazione predefinita sessioni harness ACP. -- `identity.avatar`: percorso relativo alla workspace, URL `http(s)` o URI `data:`. -- `identity` deriva valori predefiniti: `ackReaction` da `emoji`, `mentionPatterns` da `name`/`emoji`. +- `identity.avatar`: percorso relativo alla workspace, URL `http(s)` oppure URI `data:`. +- `identity` deriva 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). -- Guardrail 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). +- Guardrail di ereditarietà del 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-agent +## Routing multi-agente -Esegui più agenti isolati all'interno di un unico Gateway. Vedi [Multi-Agent](/it/concepts/multi-agent). +Esegui più agenti isolati all'interno di un Gateway. Vedi [Multi-Agent](/it/concepts/multi-agent). ```json5 { @@ -1819,31 +1819,31 @@ Esegui più agenti isolati all'interno di un unico Gateway. Vedi [Multi-Agent](/ } ``` -### Campi match del binding +### Campi `match` dei binding - `type` (facoltativo): `route` per il routing normale (il tipo mancante equivale a route), `acp` per binding di conversazione ACP persistenti. - `match.channel` (obbligatorio) -- `match.accountId` (facoltativo; `*` = qualsiasi account; omesso = account predefinito) +- `match.accountId` (facoltativo; `*` = qualunque 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 }` -**Ordine di match deterministico:** +**Ordine di corrispondenza deterministico:** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` 4. `match.accountId` (esatto, senza peer/guild/team) -5. `match.accountId: "*"` (a livello di canale) +5. `match.accountId: "*"` (esteso al canale) 6. Agente predefinito All'interno di ogni livello, vince la prima voce `bindings` corrispondente. -Per le voci `type: "acp"`, OpenClaw risolve in base all'identità esatta della conversazione (`match.channel` + account + `match.peer.id`) e non usa l'ordine dei livelli di binding route sopra. +Per le voci `type: "acp"`, OpenClaw risolve in base all'identità esatta della conversazione (`match.channel` + account + `match.peer.id`) e non usa l'ordine dei livelli di route binding sopra. ### Profili di accesso per agente - + ```json5 { @@ -1936,7 +1936,7 @@ Per le voci `type: "acp"`, OpenClaw risolve in base all'identità esatta della c -Vedi [Sandbox & Tools Multi-Agent](/it/tools/multi-agent-sandbox-tools) per i dettagli sulla precedenza. +Vedi [Sandbox e strumenti multi-agente](/it/tools/multi-agent-sandbox-tools) per i dettagli sulla precedenza. --- @@ -1962,22 +1962,22 @@ Vedi [Sandbox & Tools Multi-Agent](/it/tools/multi-agent-sandbox-tools) per i de }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) + parentForkMaxTokens: 100000, // salta il fork del thread padre sopra questo conteggio di token (0 disabilita) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // duration or false - maxDiskBytes: "500mb", // optional hard budget - highWaterBytes: "400mb", // optional cleanup target + resetArchiveRetention: "30d", // durata oppure false + maxDiskBytes: "500mb", // hard budget facoltativo + highWaterBytes: "400mb", // target di pulizia facoltativo }, threadBindings: { enabled: true, - idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables) - maxAgeHours: 0, // default hard max age in hours (`0` disables) + idleHours: 24, // disaccoppiamento automatico predefinito per inattività in ore (`0` disabilita) + maxAgeHours: 0, // età massima rigida predefinita in ore (`0` disabilita) }, - mainKey: "main", // legacy (runtime always uses "main") + mainKey: "main", // legacy (il runtime usa sempre "main") agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1989,35 +1989,35 @@ Vedi [Sandbox & Tools Multi-Agent](/it/tools/multi-agent-sandbox-tools) per i de -- **`scope`**: strategia base di raggruppamento delle sessioni per i contesti di chat di gruppo. - - `per-sender` (predefinito): ogni mittente ottiene una sessione isolata all'interno del contesto del canale. - - `global`: tutti i partecipanti in un contesto canale condividono una singola sessione (usalo solo quando è voluto un contesto condiviso). +- **`scope`**: strategia di raggruppamento base della 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 è intenzionale un contesto condiviso). - **`dmScope`**: come vengono raggruppati i DM. - `main`: tutti i DM condividono la sessione principale. - - `per-peer`: isola per ID mittente attraverso i canali. - - `per-channel-peer`: isola per canale + mittente (consigliato per inbox multiutente). - - `per-account-channel-peer`: isola per account + canale + mittente (consigliato per multi-account). -- **`identityLinks`**: mappa ID canonici a peer con prefisso provider per la condivisione della sessione tra canali. -- **`reset`**: criterio di reset principale. `daily` resetta all'ora locale `atHour`; `idle` resetta dopo `idleMinutes`. Quando sono configurati entrambi, vince quello che scade per primo. + - `per-peer`: isola per ID mittente tra i canali. + - `per-channel-peer`: isola per canale + mittente (consigliato per caselle di posta multiutente). + - `per-account-channel-peer`: isola per account + canale + mittente (consigliato per configurazioni multi-account). +- **`identityLinks`**: mappa gli ID canonici ai peer con prefisso provider per la condivisione della sessione tra canali. +- **`reset`**: criterio principale di reset. `daily` esegue il reset a `atHour` nell'ora locale; `idle` esegue il reset dopo `idleMinutes`. Quando entrambi sono configurati, prevale quello che scade per primo. - **`resetByType`**: override per tipo (`direct`, `group`, `thread`). Il legacy `dm` è accettato come alias di `direct`. -- **`parentForkMaxTokens`**: massimo `totalTokens` della sessione padre consentito quando si crea una sessione thread forked (predefinito `100000`). - - Se `totalTokens` del padre è sopra questo valore, OpenClaw avvia una nuova sessione thread invece di ereditare la cronologia del transcript del padre. - - Imposta `0` per disabilitare questo guardrail e consentire sempre il fork dal padre. -- **`mainKey`**: campo legacy. Il runtime usa sempre `"main"` per il bucket principale delle chat dirette. +- **`parentForkMaxTokens`**: valore massimo di `totalTokens` della sessione padre consentito quando viene creata una sessione thread derivata (predefinito `100000`). + - Se `totalTokens` del padre è superiore a questo valore, OpenClaw avvia una nuova sessione thread invece di ereditare la cronologia della trascrizione del padre. + - Imposta `0` per disabilitare questa protezione e consentire sempre il fork dal padre. +- **`mainKey`**: campo legacy. Il runtime usa sempre `"main"` per il bucket principale della chat diretta. - **`agentToAgent.maxPingPongTurns`**: numero massimo di turni di risposta reciproca tra agenti durante gli scambi agent-to-agent (intero, intervallo: `0`–`5`). `0` disabilita la catena ping-pong. - **`sendPolicy`**: corrispondenza per `channel`, `chatType` (`direct|group|channel`, con alias legacy `dm`), `keyPrefix` o `rawKeyPrefix`. Vince il primo deny. -- **`maintenance`**: controlli di pulizia + retention dello store delle sessioni. +- **`maintenance`**: controlli di pulizia + conservazione dello store delle sessioni. - `mode`: `warn` emette solo avvisi; `enforce` applica la pulizia. - - `pruneAfter`: soglia di età per le voci obsolete (predefinito `30d`). + - `pruneAfter`: soglia temporale per le voci obsolete (predefinito `30d`). - `maxEntries`: numero massimo di voci in `sessions.json` (predefinito `500`). - `rotateBytes`: ruota `sessions.json` quando supera questa dimensione (predefinito `10mb`). - - `resetArchiveRetention`: retention per gli archivi di transcript `*.reset.`. Per impostazione predefinita usa `pruneAfter`; imposta `false` per disabilitarla. - - `maxDiskBytes`: budget facoltativo di disco per la directory delle sessioni. In modalità `warn` registra avvisi; in modalità `enforce` rimuove prima gli artifact/sessioni più vecchi. - - `highWaterBytes`: target facoltativo dopo la pulizia del budget. Per impostazione predefinita è l'`80%` di `maxDiskBytes`. -- **`threadBindings`**: valori predefiniti globali per le funzionalità di sessione associate ai thread. - - `enabled`: switch master predefinito (i provider possono sovrascriverlo; Discord usa `channels.discord.threadBindings.enabled`) - - `idleHours`: auto-unfocus predefinito per inattività in ore (`0` lo disabilita; i provider possono sovrascriverlo) - - `maxAgeHours`: età massima rigida predefinita in ore (`0` la disabilita; i provider possono sovrascriverla) + - `resetArchiveRetention`: conservazione per gli archivi di trascrizione `*.reset.`. Per impostazione predefinita usa `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 artifact/le sessioni più vecchi. + - `highWaterBytes`: target facoltativo dopo la pulizia del budget. Per impostazione predefinita è `80%` di `maxDiskBytes`. +- **`threadBindings`**: valori predefiniti globali per le funzionalità di sessione vincolate ai thread. + - `enabled`: interruttore predefinito principale (i provider possono sovrascriverlo; Discord usa `channels.discord.threadBindings.enabled`) + - `idleHours`: disaccoppiamento automatico predefinito per inattività in ore (`0` disabilita; i provider possono sovrascriverlo) + - `maxAgeHours`: età massima rigida predefinita in ore (`0` disabilita; i provider possono sovrascriverlo) @@ -2028,7 +2028,7 @@ Vedi [Sandbox & Tools Multi-Agent](/it/tools/multi-agent-sandbox-tools) per i de ```json5 { messages: { - responsePrefix: "🦞", // or "auto" + responsePrefix: "🦞", // oppure "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, @@ -2043,7 +2043,7 @@ Vedi [Sandbox & Tools Multi-Agent](/it/tools/multi-agent-sandbox-tools) per i de }, }, inbound: { - debounceMs: 2000, // 0 disables + debounceMs: 2000, // 0 disabilita byChannel: { whatsapp: 5000, slack: 1500, @@ -2053,21 +2053,21 @@ Vedi [Sandbox & Tools Multi-Agent](/it/tools/multi-agent-sandbox-tools) per i de } ``` -### Prefisso di risposta +### Prefisso della risposta Override per canale/account: `channels..responsePrefix`, `channels..accounts..responsePrefix`. Risoluzione (vince il più specifico): account → canale → globale. `""` disabilita e interrompe la cascata. `"auto"` deriva `[{identity.name}]`. -**Variabili di template:** +**Variabili del template:** -| Variabile | Descrizione | Esempio | -| ----------------- | ------------------------- | --------------------------- | -| `{model}` | Nome breve del modello | `claude-opus-4-6` | +| Variabile | Descrizione | Esempio | +| ----------------- | ---------------------- | --------------------------- | +| `{model}` | Nome breve del modello | `claude-opus-4-6` | | `{modelFull}` | Identificatore completo del modello | `anthropic/claude-opus-4-6` | -| `{provider}` | Nome del provider | `anthropic` | -| `{thinkingLevel}` | Livello thinking corrente | `high`, `low`, `off` | -| `{identity.name}` | Nome identità dell'agente | (uguale a `"auto"`) | +| `{provider}` | Nome del provider | `anthropic` | +| `{thinkingLevel}` | Livello thinking corrente | `high`, `low`, `off` | +| `{identity.name}` | Nome identità dell'agente | (uguale a `"auto"`) | Le variabili non distinguono tra maiuscole e minuscole. `{think}` è un alias di `{thinkingLevel}`. @@ -2075,16 +2075,16 @@ Le variabili non distinguono tra maiuscole e minuscole. `{think}` è un alias di - Per impostazione predefinita usa `identity.emoji` dell'agente attivo, altrimenti `"👀"`. Imposta `""` per disabilitare. - Override per canale: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Ordine di risoluzione: account → canale → `messages.ackReaction` → fallback identità. +- Ordine di risoluzione: account → canale → `messages.ackReaction` → fallback identity. - Ambito: `group-mentions` (predefinito), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: rimuove l'ack dopo la risposta su Slack, Discord e Telegram. +- `removeAckAfterReply`: rimuove la conferma dopo la risposta su Slack, Discord e Telegram. - `messages.statusReactions.enabled`: abilita le reazioni di stato del ciclo di vita su Slack, Discord e Telegram. - Su Slack e Discord, se non impostato mantiene abilitate le reazioni di stato quando sono attive le reazioni ack. + Su Slack e Discord, se non impostato mantiene abilitate le reazioni di stato quando le reazioni di conferma sono attive. Su Telegram, impostalo esplicitamente su `true` per abilitare le reazioni di stato del ciclo di vita. ### Debounce in ingresso -Raggruppa i rapidi messaggi di solo testo dello stesso mittente in un singolo turno agente. I media/allegati forzano l'invio immediato. I comandi di controllo bypassano il debounce. +Raggruppa i rapidi messaggi solo testuali dallo stesso mittente in un unico turno dell'agente. Media/allegati vengono svuotati immediatamente. I comandi di controllo bypassano il debounce. ### TTS (text-to-speech) @@ -2127,12 +2127,12 @@ Raggruppa i rapidi messaggi di solo testo dello stesso mittente in un singolo tu } ``` -- `auto` controlla la modalità predefinita auto-TTS: `off`, `always`, `inbound` oppure `tagged`. `/tts on|off` può sovrascrivere le preferenze locali e `/tts status` mostra lo stato effettivo. +- `auto` controlla la modalità predefinita di auto-TTS: `off`, `always`, `inbound` oppure `tagged`. `/tts on|off` può sovrascrivere le preferenze locali e `/tts status` mostra lo stato effettivo. - `summaryModel` sovrascrive `agents.defaults.model.primary` per il riepilogo automatico. -- `modelOverrides` è abilitato per impostazione predefinita; `modelOverrides.allowProvider` è `false` per impostazione predefinita (opt-in). -- Le API key usano come fallback `ELEVENLABS_API_KEY`/`XI_API_KEY` e `OPENAI_API_KEY`. +- `modelOverrides` è abilitato per impostazione predefinita; `modelOverrides.allowProvider` ha come predefinito `false` (opt-in). +- Le chiavi API usano come fallback `ELEVENLABS_API_KEY`/`XI_API_KEY` e `OPENAI_API_KEY`. - `openai.baseUrl` sovrascrive l'endpoint TTS OpenAI. L'ordine di risoluzione è config, poi `OPENAI_TTS_BASE_URL`, poi `https://api.openai.com/v1`. -- Quando `openai.baseUrl` punta a un endpoint non OpenAI, OpenClaw lo tratta come un server TTS compatibile con OpenAI e allenta la validazione di modello/voce. +- Quando `openai.baseUrl` punta a un endpoint non OpenAI, OpenClaw lo tratta come un server TTS compatibile con OpenAI e allenta la convalida di modello/voce. --- @@ -2164,11 +2164,11 @@ 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 flat (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) sono solo per compatibilità e vengono migrate automaticamente in `talk.providers.`. -- Gli ID voce usano come fallback `ELEVENLABS_VOICE_ID` o `SAG_VOICE_ID`. -- `providers.*.apiKey` accetta stringhe in chiaro o oggetti SecretRef. -- Il fallback `ELEVENLABS_API_KEY` si applica solo quando non è configurata alcuna API key Talk. +- Gli ID voce usano come fallback `ELEVENLABS_VOICE_ID` oppure `SAG_VOICE_ID`. +- `providers.*.apiKey` accetta stringhe in chiaro oppure 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 per quanto tempo la modalità Talk attende dopo il silenzio dell'utente prima di inviare il transcript. Se non impostato, mantiene la finestra di pausa predefinita della piattaforma (`700 ms su macOS e Android, 900 ms su iOS`). +- `silenceTimeoutMs` controlla quanto a lungo 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`). --- @@ -2178,35 +2178,35 @@ Valori predefiniti per la modalità Talk (macOS/iOS/Android). `tools.profile` imposta una allowlist di base prima di `tools.allow`/`tools.deny`: -L'onboarding locale imposta per le nuove configurazioni locali il valore predefinito `tools.profile: "coding"` quando non impostato (i profili espliciti esistenti vengono preservati). +L'onboarding locale imposta per i nuovi config locali `tools.profile: "coding"` quando non è impostato (i profili espliciti esistenti vengono preservati). | Profilo | Include | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | solo `session_status` | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------ | +| `minimal` | solo `session_status` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | -| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | Nessuna restrizione (uguale a non impostato) | +| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | +| `full` | Nessuna restrizione (uguale a non impostato) | ### Gruppi di strumenti -| Gruppo | Strumenti | -| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` è accettato come alias di `exec`) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| Gruppo | Strumenti | +| ------------------ | ---------------------------------------------------------------------------------------------------------------------- | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash` è accettato come alias di `exec`) | +| `group:fs` | `read`, `write`, `edit`, `apply_patch` | | `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | -| `group:memory` | `memory_search`, `memory_get` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation` | `cron`, `gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | +| `group:memory` | `memory_search`, `memory_get` | +| `group:web` | `web_search`, `x_search`, `web_fetch` | +| `group:ui` | `browser`, `canvas` | +| `group:automation` | `cron`, `gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | | `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Tutti gli strumenti integrati (esclude i plugin provider) | +| `group:openclaw` | Tutti gli strumenti integrati (esclude i plugin provider) | ### `tools.allow` / `tools.deny` -Criterio globale allow/deny degli strumenti (deny ha la precedenza). Case-insensitive, supporta wildcard `*`. Si applica anche quando la sandbox Docker è disattivata. +Criterio globale di autorizzazione/blocco degli strumenti (vince il deny). Non distingue tra maiuscole e minuscole, supporta wildcard `*`. Applicato anche quando il sandbox Docker è disattivato. ```json5 { @@ -2216,7 +2216,7 @@ Criterio globale allow/deny degli strumenti (deny ha la precedenza). Case-insens ### `tools.byProvider` -Limita ulteriormente gli strumenti per provider o modelli specifici. Ordine: profilo base → profilo provider → allow/deny. +Limita ulteriormente gli strumenti per provider o modelli specifici. Ordine: profilo di base → profilo provider → allow/deny. ```json5 { @@ -2232,7 +2232,7 @@ Limita ulteriormente gli strumenti per provider o modelli specifici. Ordine: pro ### `tools.elevated` -Controlla l'accesso exec elevato fuori dalla sandbox: +Controlla l'accesso exec elevato fuori dal sandbox: ```json5 { @@ -2249,8 +2249,8 @@ Controlla l'accesso exec elevato fuori dalla sandbox: ``` - L'override per agente (`agents.list[].tools.elevated`) può solo restringere ulteriormente. -- `/elevated on|off|ask|full` memorizza lo stato per sessione; le direttive inline si applicano a un singolo messaggio. -- `exec` elevato bypassa la sandbox e usa il percorso di escape configurato (`gateway` per impostazione predefinita, oppure `node` quando il target exec è `node`). +- `/elevated on|off|ask|full` salva lo stato per sessione; le direttive inline si applicano a un solo messaggio. +- `exec` elevato bypassa il sandbox e usa il percorso di escape configurato (`gateway` per impostazione predefinita, oppure `node` quando il target exec è `node`). ### `tools.exec` @@ -2274,7 +2274,7 @@ Controlla l'accesso exec elevato fuori dalla sandbox: ### `tools.loopDetection` -I controlli di sicurezza sui loop degli strumenti sono **disabilitati per impostazione predefinita**. Imposta `enabled: true` per attivare il rilevamento. +I controlli di sicurezza per i loop degli strumenti sono **disabilitati per impostazione predefinita**. Imposta `enabled: true` per attivare il rilevamento. Le impostazioni possono essere definite globalmente in `tools.loopDetection` e sovrascritte per agente in `agents.list[].tools.loopDetection`. ```json5 @@ -2296,13 +2296,13 @@ Le impostazioni possono essere definite globalmente in `tools.loopDetection` e s } ``` -- `historySize`: cronologia massima delle chiamate agli strumenti mantenuta per l'analisi dei loop. -- `warningThreshold`: soglia dei pattern ripetuti senza progresso per gli avvisi. +- `historySize`: massimo storico delle chiamate agli strumenti conservato per l'analisi dei loop. +- `warningThreshold`: soglia del pattern ripetuto senza avanzamento per gli avvisi. - `criticalThreshold`: soglia ripetuta più alta per bloccare i loop critici. -- `globalCircuitBreakerThreshold`: soglia di arresto rigido per qualsiasi esecuzione senza progresso. -- `detectors.genericRepeat`: avvisa sulle chiamate ripetute allo stesso strumento/con gli stessi argomenti. +- `globalCircuitBreakerThreshold`: soglia di stop rigida per qualunque esecuzione senza avanzamento. +- `detectors.genericRepeat`: avvisa su chiamate ripetute allo stesso strumento/con gli stessi argomenti. - `detectors.knownPollNoProgress`: avvisa/blocca sugli strumenti di poll noti (`process.poll`, `command_status`, ecc.). -- `detectors.pingPong`: avvisa/blocca sui pattern alternati a coppia senza progresso. +- `detectors.pingPong`: avvisa/blocca su pattern a coppie alternate senza avanzamento. - Se `warningThreshold >= criticalThreshold` oppure `criticalThreshold >= globalCircuitBreakerThreshold`, la convalida fallisce. ### `tools.web` @@ -2313,14 +2313,14 @@ Le impostazioni possono essere definite globalmente in `tools.loopDetection` e s web: { search: { enabled: true, - apiKey: "brave_api_key", // or BRAVE_API_KEY env + apiKey: "brave_api_key", // oppure env BRAVE_API_KEY maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, }, fetch: { enabled: true, - provider: "firecrawl", // optional; omit for auto-detect + provider: "firecrawl", // facoltativo; ometti per auto-rilevamento maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2345,7 +2345,7 @@ Configura la comprensione dei media in ingresso (immagine/audio/video): media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: send finished async music/video directly to the channel + directSend: false, // opt-in: invia direttamente al canale la musica/il video asincroni completati }, audio: { enabled: true, @@ -2369,32 +2369,32 @@ Configura la comprensione dei media in ingresso (immagine/audio/video): } ``` - + -**Voce provider** (`type: "provider"` o omesso): +**Voce provider** (`type: "provider"` oppure omesso): -- `provider`: ID provider API (`openai`, `anthropic`, `google`/`gemini`, `groq`, ecc.) -- `model`: override dell'ID modello +- `provider`: id del provider API (`openai`, `anthropic`, `google`/`gemini`, `groq`, ecc.) +- `model`: override dell'id del modello - `profile` / `preferredProfile`: selezione del profilo `auth-profiles.json` **Voce CLI** (`type: "cli"`): - `command`: eseguibile da avviare -- `args`: argomenti templateizzati (supporta `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, ecc.) +- `args`: argomenti con template (supporta `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, ecc.) **Campi comuni:** -- `capabilities`: elenco facoltativo (`image`, `audio`, `video`). Valori predefiniti: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. +- `capabilities`: elenco facoltativo (`image`, `audio`, `video`). Predefiniti: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. - `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: override per voce. - In caso di errore si passa alla voce successiva. L'autenticazione del provider segue l'ordine standard: `auth-profiles.json` → variabili env → `models.providers.*.apiKey`. -**Campi di completamento asincrono:** +**Campi del completamento asincrono:** -- `asyncCompletion.directSend`: quando `true`, le attività asincrone completate `music_generate` +- `asyncCompletion.directSend`: quando `true`, le attività completate asincrone `music_generate` e `video_generate` provano prima la consegna diretta al canale. Predefinito: `false` - (percorso legacy di wake/model-delivery della sessione richiedente). + (percorso legacy di risveglio sessione richiedente/consegna del modello). @@ -2413,9 +2413,9 @@ L'autenticazione del provider segue l'ordine standard: `auth-profiles.json` → ### `tools.sessions` -Controlla quali sessioni possono essere prese come target dagli strumenti di sessione (`sessions_list`, `sessions_history`, `sessions_send`). +Controlla quali sessioni possono essere usate come target dagli strumenti di sessione (`sessions_list`, `sessions_history`, `sessions_send`). -Predefinito: `tree` (sessione corrente + sessioni generate da essa, come i subagent). +Predefinito: `tree` (sessione corrente + sessioni generate da essa, come i subagenti). ```json5 { @@ -2431,25 +2431,25 @@ Predefinito: `tree` (sessione corrente + sessioni generate da essa, come i subag Note: - `self`: solo la chiave della sessione corrente. -- `tree`: sessione corrente + sessioni generate dalla sessione corrente (subagent). -- `agent`: qualsiasi sessione appartenente all'ID agente corrente (può includere altri utenti se esegui sessioni per-sender sotto lo stesso ID agente). +- `tree`: sessione corrente + sessioni generate dalla sessione corrente (subagenti). +- `agent`: qualsiasi sessione appartenente all'ID agente corrente (può includere altri utenti se esegui sessioni per mittente sotto lo stesso ID agente). - `all`: qualsiasi sessione. Il targeting cross-agent richiede comunque `tools.agentToAgent`. -- Clamp della sandbox: quando la sessione corrente è sandboxed e `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, la visibilità viene forzata a `tree` anche se `tools.sessions.visibility="all"`. +- Restrizione sandbox: quando la sessione corrente è sandboxed e `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, la visibilità viene forzata a `tree` anche se `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` -Controlla il supporto degli allegati inline per `sessions_spawn`. +Controlla il supporto per allegati inline in `sessions_spawn`. ```json5 { tools: { sessions_spawn: { attachments: { - enabled: false, // opt-in: set true to allow inline file attachments - maxTotalBytes: 5242880, // 5 MB total across all files + enabled: false, // opt-in: imposta true per consentire allegati file inline + maxTotalBytes: 5242880, // 5 MB totali su tutti i file maxFiles: 50, maxFileBytes: 1048576, // 1 MB per file - retainOnSessionKeep: false, // keep attachments when cleanup="keep" + retainOnSessionKeep: false, // conserva gli allegati quando cleanup="keep" }, }, }, @@ -2460,20 +2460,20 @@ Note: - Gli allegati sono supportati solo per `runtime: "subagent"`. Il runtime ACP li rifiuta. - I file vengono materializzati nella workspace figlia in `.openclaw/attachments//` con un `.manifest.json`. -- Il contenuto degli allegati viene automaticamente redatto dalla persistenza del transcript. -- Gli input Base64 vengono convalidati con controlli rigorosi su alfabeto/padding e un controllo delle dimensioni prima della decodifica. +- Il contenuto degli allegati viene automaticamente redatto dalla persistenza della trascrizione. +- Gli input Base64 vengono convalidati con controlli rigorosi su alfabeto/padding e una protezione sulla dimensione prima della decodifica. - I permessi dei file sono `0700` per le directory e `0600` per i file. - La pulizia segue il criterio `cleanup`: `delete` rimuove sempre gli allegati; `keep` li conserva solo quando `retainOnSessionKeep: true`. ### `tools.experimental` -Flag sperimentali degli strumenti integrati. Disattivati per impostazione predefinita a meno che non si applichi una regola di auto-abilitazione strict-agentic GPT-5. +Flag sperimentali per gli strumenti integrati. Disattivati per impostazione predefinita salvo quando si applica una regola di auto-abilitazione GPT-5 strict-agentic. ```json5 { tools: { experimental: { - planTool: true, // enable experimental update_plan + planTool: true, // abilita l'update_plan sperimentale }, }, } @@ -2481,9 +2481,9 @@ Flag sperimentali degli strumenti integrati. Disattivati per impostazione predef Note: -- `planTool`: abilita lo strumento strutturato `update_plan` per il tracciamento di lavori multi-step non banali. -- Predefinito: `false` a meno che `agents.defaults.embeddedPi.executionContract` (o un override per agente) sia impostato su `"strict-agentic"` per un'esecuzione OpenAI o OpenAI Codex della famiglia GPT-5. Imposta `true` per forzare lo strumento fuori da quell'ambito, oppure `false` per mantenerlo disattivato anche per le esecuzioni strict-agentic GPT-5. -- Quando è abilitato, il prompt di sistema aggiunge anche linee guida d'uso così il modello lo usa solo per lavori sostanziali e mantiene al massimo un passo `in_progress`. +- `planTool`: abilita lo strumento strutturato `update_plan` per il tracciamento di lavori non banali in più passaggi. +- Predefinito: `false` a meno che `agents.defaults.embeddedPi.executionContract` (o un override per agente) sia impostato su `"strict-agentic"` per un'esecuzione GPT-5 family OpenAI o OpenAI Codex. Imposta `true` per forzare l'attivazione dello strumento fuori da quell'ambito, oppure `false` per mantenerlo disattivato anche per esecuzioni GPT-5 strict-agentic. +- Quando è abilitato, il prompt di sistema aggiunge anche linee guida d'uso affinché il modello lo usi solo per lavori sostanziali e mantenga al massimo un passaggio `in_progress`. ### `agents.defaults.subagents` @@ -2503,21 +2503,21 @@ Note: } ``` -- `model`: modello predefinito per i sub-agent generati. Se omesso, i sub-agent ereditano il modello del chiamante. +- `model`: modello predefinito per i subagenti generati. Se omesso, i subagenti ereditano il modello del chiamante. - `allowAgents`: allowlist predefinita degli ID agente target per `sessions_spawn` quando l'agente richiedente non imposta il proprio `subagents.allowAgents` (`["*"]` = qualunque; predefinito: solo lo stesso agente). -- `runTimeoutSeconds`: timeout predefinito (secondi) per `sessions_spawn` quando la chiamata allo strumento omette `runTimeoutSeconds`. `0` significa nessun timeout. -- Criterio degli strumenti per subagent: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. +- `runTimeoutSeconds`: timeout predefinito (secondi) per `sessions_spawn` quando la chiamata dello strumento omette `runTimeoutSeconds`. `0` significa nessun timeout. +- Criterio degli strumenti per subagente: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- -## Provider personalizzati e base URL +## Provider personalizzati e URL base -OpenClaw usa il catalogo modelli integrato. Aggiungi provider personalizzati tramite `models.providers` nella config o `~/.openclaw/agents//agent/models.json`. +OpenClaw usa il catalogo modelli integrato. Aggiungi provider personalizzati tramite `models.providers` nella configurazione o `~/.openclaw/agents//agent/models.json`. ```json5 { models: { - mode: "merge", // merge (default) | replace + mode: "merge", // merge (predefinito) | replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", @@ -2542,47 +2542,47 @@ OpenClaw usa il catalogo modelli integrato. Aggiungi provider personalizzati tra ``` - Usa `authHeader: true` + `headers` per esigenze di autenticazione personalizzate. -- Sovrascrivi la root della config dell'agente con `OPENCLAW_AGENT_DIR` (o `PI_CODING_AGENT_DIR`, alias legacy della variabile d'ambiente). +- Sovrascrivi la radice della configurazione agente con `OPENCLAW_AGENT_DIR` (oppure `PI_CODING_AGENT_DIR`, alias legacy della variabile d'ambiente). - Precedenza di merge per ID provider corrispondenti: - - I valori `baseUrl` non vuoti in `models.json` dell'agente hanno la precedenza. - - I valori `apiKey` non vuoti dell'agente hanno la precedenza solo quando quel provider non è gestito da SecretRef nel contesto attuale di config/auth-profile. - - I valori `apiKey` del provider gestiti da SecretRef vengono aggiornati dai marker sorgente (`ENV_VAR_NAME` per riferimenti env, `secretref-managed` per riferimenti file/exec) invece di persistere i segreti risolti. - - I valori header del provider gestiti da SecretRef vengono aggiornati dai marker sorgente (`secretref-env:ENV_VAR_NAME` per riferimenti env, `secretref-managed` per riferimenti file/exec). - - `apiKey`/`baseUrl` dell'agente vuoti o mancanti usano come fallback `models.providers` nella config. - - Per i modelli corrispondenti, `contextWindow`/`maxTokens` usano il valore più alto tra config esplicita e valori impliciti del catalogo. - - Per i modelli corrispondenti, `contextTokens` preserva un limite runtime esplicito quando presente; usalo per limitare il contesto effettivo senza cambiare i metadati nativi del modello. - - Usa `models.mode: "replace"` quando vuoi che la config riscriva completamente `models.json`. - - La persistenza dei marker è autorevole rispetto alla sorgente: i marker vengono scritti dallo snapshot di config sorgente attivo (pre-risoluzione), non dai valori segreti runtime risolti. + - I valori `baseUrl` non vuoti di `models.json` dell'agente hanno la precedenza. + - I valori `apiKey` non vuoti dell'agente hanno la precedenza solo quando quel provider non è gestito da SecretRef nel contesto attuale di configurazione/profilo di autenticazione. + - I valori `apiKey` del provider gestiti da SecretRef vengono aggiornati dai marcatori di origine (`ENV_VAR_NAME` per riferimenti env, `secretref-managed` per riferimenti file/exec) invece di persistere i secret risolti. + - I valori header del provider gestiti da SecretRef vengono aggiornati dai marcatori di origine (`secretref-env:ENV_VAR_NAME` per riferimenti env, `secretref-managed` per riferimenti file/exec). + - `apiKey`/`baseUrl` vuoti o mancanti dell'agente usano come fallback `models.providers` nella configurazione. + - `contextWindow`/`maxTokens` del modello corrispondente usano il valore più alto tra configurazione esplicita e valori impliciti del catalogo. + - `contextTokens` del modello corrispondente preserva un limite runtime esplicito quando presente; usalo per limitare il contesto effettivo senza cambiare i metadati nativi del modello. + - Usa `models.mode: "replace"` quando vuoi che la configurazione riscriva completamente `models.json`. + - La persistenza dei marcatori è autorevole rispetto alla sorgente: i marcatori vengono scritti dallo snapshot di configurazione sorgente attivo (prima della risoluzione), non dai valori secret runtime risolti. ### Dettagli dei campi del provider - `models.mode`: comportamento del catalogo provider (`merge` oppure `replace`). -- `models.providers`: mappa di provider personalizzati indicizzata per ID provider. +- `models.providers`: mappa dei provider personalizzati indicizzata per ID provider. - `models.providers.*.api`: adattatore di richiesta (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai`, ecc.). - `models.providers.*.apiKey`: credenziale del provider (preferisci SecretRef/sostituzione env). - `models.providers.*.auth`: strategia di autenticazione (`api-key`, `token`, `oauth`, `aws-sdk`). - `models.providers.*.injectNumCtxForOpenAICompat`: per Ollama + `openai-completions`, inietta `options.num_ctx` nelle richieste (predefinito: `true`). -- `models.providers.*.authHeader`: forza il trasporto delle credenziali nell'header `Authorization` quando richiesto. +- `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 aggiuntivi per il routing proxy/tenant. +- `models.providers.*.headers`: header statici extra per routing proxy/tenant. - `models.providers.*.request`: override di trasporto per le richieste HTTP del model provider. - - `request.headers`: header aggiuntivi (uniti ai valori predefiniti del provider). I valori accettano SecretRef. + - `request.headers`: header extra (uniti ai valori predefiniti del provider). I valori accettano SecretRef. - `request.auth`: override della strategia di autenticazione. Modalità: `"provider-default"` (usa l'autenticazione integrata del provider), `"authorization-bearer"` (con `token`), `"header"` (con `headerName`, `value`, `prefix` facoltativo). - `request.proxy`: override del proxy HTTP. Modalità: `"env-proxy"` (usa le variabili env `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (con `url`). Entrambe le modalità accettano un sotto-oggetto `tls` facoltativo. - `request.tls`: override TLS per connessioni dirette. Campi: `ca`, `cert`, `key`, `passphrase` (tutti accettano SecretRef), `serverName`, `insecureSkipVerify`. - - `request.allowPrivateNetwork`: quando `true`, consente HTTPS verso `baseUrl` quando il DNS si risolve in intervalli privati, CGNAT o simili, tramite il guard di fetch HTTP del provider (opt-in dell'operatore per endpoint OpenAI-compatible self-hosted attendibili). WebSocket usa lo stesso `request` per header/TLS ma non quel gate SSRF di fetch. Predefinito `false`. + - `request.allowPrivateNetwork`: quando è `true`, consente HTTPS verso `baseUrl` quando il DNS si risolve in intervalli privati, CGNAT o simili, tramite la guardia fetch HTTP del provider (opt-in dell'operatore per endpoint OpenAI-compatibili self-hosted affidabili). WebSocket usa lo stesso `request` per header/TLS ma non quella protezione SSRF di fetch. Predefinito `false`. - `models.providers.*.models`: voci esplicite del catalogo modelli del provider. - `models.providers.*.models.*.contextWindow`: metadati della finestra di contesto nativa del modello. -- `models.providers.*.models.*.contextTokens`: limite runtime facoltativo del contesto. Usalo quando vuoi un budget di contesto effettivo più piccolo del `contextWindow` nativo 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 forza questo valore a `false` a runtime. Un `baseUrl` vuoto/omesso mantiene il comportamento OpenAI predefinito. -- `models.providers.*.models.*.compat.requiresStringContent`: hint facoltativo di compatibilità per endpoint chat OpenAI-compatible che accettano solo stringhe. Quando è `true`, OpenClaw appiattisce gli array puramente testuali `messages[].content` in stringhe semplici prima di inviare la richiesta. -- `plugins.entries.amazon-bedrock.config.discovery`: root delle impostazioni di auto-discovery di 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 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`: numero massimo di token in output di fallback per i modelli scoperti. +- `models.providers.*.models.*.contextTokens`: limite di contesto runtime facoltativo. Usalo quando vuoi un budget di contesto effettivo più piccolo rispetto a `contextWindow` nativo del modello. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: hint di compatibilità facoltativo. Per `api: "openai-completions"` con `baseUrl` non nativo non vuoto (host diverso da `api.openai.com`), OpenClaw lo forza a `false` a runtime. Un `baseUrl` vuoto/omesso mantiene il comportamento OpenAI predefinito. +- `models.providers.*.models.*.compat.requiresStringContent`: hint di compatibilità facoltativo per endpoint chat OpenAI-compatibili che accettano solo stringhe. Quando è `true`, OpenClaw appiattisce gli array `messages[].content` di puro testo in stringhe semplici prima di inviare la richiesta. +- `plugins.entries.amazon-bedrock.config.discovery`: radice delle impostazioni di auto-discovery Bedrock. +- `plugins.entries.amazon-bedrock.config.discovery.enabled`: attiva/disattiva il rilevamento implicito. +- `plugins.entries.amazon-bedrock.config.discovery.region`: regione AWS per il rilevamento. +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: filtro facoltativo per ID provider per il rilevamento mirato. +- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: intervallo di polling per l'aggiornamento del rilevamento. +- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: finestra di contesto di fallback per i modelli rilevati. +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: numero massimo di token di output di fallback per i modelli rilevati. ### Esempi di provider @@ -2637,7 +2637,7 @@ Usa `cerebras/zai-glm-4.7` per Cerebras; `zai/glm-4.7` per Z.AI diretto. } ``` -Imposta `OPENCODE_API_KEY` (oppure `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` oppure `openclaw onboard --auth-choice opencode-go`. +Imposta `OPENCODE_API_KEY` (oppure `OPENCODE_ZEN_API_KEY`). Usa riferimenti `opencode/...` per il catalogo Zen oppure riferimenti `opencode-go/...` per il catalogo Go. Scorciatoia: `openclaw onboard --auth-choice opencode-zen` oppure `openclaw onboard --auth-choice opencode-go`. @@ -2658,7 +2658,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 di base URL. +- Per l'endpoint generale, definisci un provider personalizzato con l'override di `baseUrl`. @@ -2699,9 +2699,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"` oppure `openclaw onboard --auth-choice moonshot-api-key-cn`. -Gli endpoint nativi Moonshot dichiarano compatibilità con l'uso dello streaming sul trasporto condiviso -`openai-completions`, e OpenClaw si basa su queste capacità dell'endpoint -piuttosto che solo sull'ID provider integrato. +Gli endpoint Moonshot nativi dichiarano compatibilità d'uso con lo streaming sul trasporto condiviso +`openai-completions`, e OpenClaw basa questo comportamento sulle capacità dell'endpoint +anziché solo sull'ID provider integrato. @@ -2758,7 +2758,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`. @@ -2801,9 +2801,9 @@ Il base URL deve omettere `/v1` (il client Anthropic lo aggiunge). Scorciatoia: Imposta `MINIMAX_API_KEY`. Scorciatoie: `openclaw onboard --auth-choice minimax-global-api` oppure `openclaw onboard --auth-choice minimax-cn-api`. -Il catalogo modelli usa per impostazione predefinita solo M2.7. -Nel percorso di streaming compatibile con Anthropic, OpenClaw disabilita il thinking di MiniMax -per impostazione predefinita a meno che tu non imposti esplicitamente `thinking`. `/fast on` oppure +Il catalogo modelli 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` oppure `params.fastMode: true` riscrive `MiniMax-M2.7` in `MiniMax-M2.7-highspeed`. @@ -2811,7 +2811,7 @@ per impostazione predefinita a meno che tu non imposti esplicitamente `thinking` -Vedi [Modelli locali](/it/gateway/local-models). In breve: esegui un grande modello locale tramite l'API Responses di LM Studio su hardware serio; mantieni uniti i modelli hosted per il fallback. +Vedi [Modelli locali](/it/gateway/local-models). In breve: esegui un grande modello locale tramite LM Studio Responses API su hardware serio; mantieni uniti i modelli hosted per il fallback. @@ -2832,7 +2832,7 @@ Vedi [Modelli locali](/it/gateway/local-models). In breve: esegui un grande mode }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // oppure stringa in chiaro env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -2843,11 +2843,11 @@ Vedi [Modelli locali](/it/gateway/local-models). In breve: esegui un grande mode ``` - `allowBundled`: allowlist facoltativa solo per le Skills bundled (le Skills managed/workspace non sono interessate). -- `load.extraDirs`: root condivise aggiuntive delle Skills (precedenza più bassa). -- `install.preferBrew`: quando true, preferisce gli installer Homebrew quando `brew` è +- `load.extraDirs`: radici condivise extra delle Skills (precedenza più bassa). +- `install.preferBrew`: quando è true, preferisce gli installer Homebrew quando `brew` è disponibile prima di passare ad altri tipi di installer. -- `install.nodeManager`: preferenza dell'installer Node per le specifiche - `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). +- `install.nodeManager`: preferenza del gestore Node per le specifiche `metadata.openclaw.install` + (`npm` | `pnpm` | `yarn` | `bun`). - `entries..enabled: false` disabilita una Skills anche se bundled/installata. - `entries..apiKey`: comodità per le Skills che dichiarano una variabile env primaria (stringa in chiaro o oggetto SecretRef). @@ -2877,38 +2877,38 @@ Vedi [Modelli locali](/it/gateway/local-models). In breve: esegui un grande mode } ``` -- Caricati da `~/.openclaw/extensions`, `/.openclaw/extensions` e `plugins.load.paths`. -- Il discovery accetta Plugin nativi OpenClaw oltre a bundle Codex compatibili e bundle Claude, inclusi bundle Claude senza manifest con layout predefinito. -- **Le modifiche alla configurazione richiedono un riavvio del Gateway.** -- `allow`: allowlist facoltativa (vengono caricati solo i Plugin elencati). `deny` ha la precedenza. -- `plugins.entries..apiKey`: campo di comodità per API key a livello di 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 che mutano il prompt del legacy `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 attendibile questo Plugin per richiedere override per esecuzione di `provider` e `model` per esecuzioni in background dei subagent. -- `plugins.entries..subagent.allowedModels`: allowlist facoltativa di target canonici `provider/model` per override attendibili dei subagent. Usa `"*"` solo quando vuoi intenzionalmente consentire qualsiasi modello. -- `plugins.entries..config`: oggetto di configurazione definito dal Plugin (convalidato dallo schema del Plugin nativo OpenClaw quando disponibile). +- Caricati da `~/.openclaw/extensions`, `/.openclaw/extensions`, più `plugins.load.paths`. +- Il rilevamento accetta plugin OpenClaw nativi più bundle Codex compatibili e bundle Claude, inclusi bundle Claude senza manifest con layout predefinito. +- **Le modifiche di configurazione richiedono un riavvio del gateway.** +- `allow`: allowlist facoltativa (vengono caricati solo i plugin elencati). Vince `deny`. +- `plugins.entries..apiKey`: campo di comodità per chiave API 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 che mutano il prompt del legacy `before_agent_start`, preservando però i legacy `modelOverride` e `providerOverride`. 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 in background dei subagenti. +- `plugins.entries..subagent.allowedModels`: allowlist facoltativa di target canonici `provider/model` per override affidabili dei subagenti. 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`: API key Firecrawl (accetta SecretRef). Usa come fallback `plugins.entries.firecrawl.config.webSearch.apiKey`, il legacy `tools.web.fetch.firecrawl.apiKey` o la variabile env `FIRECRAWL_API_KEY`. - - `baseUrl`: URL base dell'API Firecrawl (predefinito: `https://api.firecrawl.dev`). + - `apiKey`: chiave API 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). - `timeoutSeconds`: timeout della richiesta di scraping 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 (ad es. `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: impostazioni del dreaming della memoria. Vedi [Dreaming](/it/concepts/dreaming) per fasi e soglie. - - `enabled`: switch master del dreaming (predefinito `false`). - - `frequency`: cadenza Cron per ogni sweep completo di dreaming (predefinita `"0 3 * * *"`). - - il criterio delle fasi e le soglie sono dettagli implementativi (non chiavi di configurazione esposte all'utente). +- `plugins.entries.memory-core.config.dreaming`: impostazioni di Dreaming della memoria. Vedi [Dreaming](/it/concepts/dreaming) per fasi e soglie. + - `enabled`: interruttore principale di Dreaming (predefinito `false`). + - `frequency`: cadenza Cron per ogni sweep completo di Dreaming (predefinito `"0 3 * * *"`). + - i criteri di fase e le soglie sono dettagli di implementazione (non chiavi di configurazione rivolte all'utente). - La configurazione completa della memoria si trova in [Riferimento della configurazione della memoria](/it/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- I Plugin bundle Claude abilitati possono anche contribuire con valori predefiniti embedded di Pi 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, oppure `"none"` per disabilitare i Plugin memoria. -- `plugins.slots.contextEngine`: scegli l'ID del Plugin motore di contesto attivo; il valore predefinito è `"legacy"` a meno che tu non installi e selezioni un altro motore. +- 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 grezze della configurazione OpenClaw. +- `plugins.slots.memory`: scegli l'ID del plugin di memoria attivo, oppure `"none"` per disabilitare i plugin di memoria. +- `plugins.slots.contextEngine`: scegli l'ID del plugin del motore di contesto attivo; il predefinito è `"legacy"` a meno che tu non installi e selezioni un altro motore. - `plugins.installs`: metadati di installazione gestiti dalla CLI usati da `openclaw plugins update`. - Include `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. - Tratta `plugins.installs.*` come stato gestito; preferisci i comandi CLI alle modifiche manuali. @@ -2926,8 +2926,8 @@ Vedi [Plugin](/it/tools/plugin). evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access - // allowPrivateNetwork: true, // legacy alias + // dangerouslyAllowPrivateNetwork: true, // opt in solo per accesso affidabile a reti private + // allowPrivateNetwork: true, // alias legacy // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, @@ -2954,28 +2954,29 @@ Vedi [Plugin](/it/tools/plugin). ``` - `evaluateEnabled: false` disabilita `act:evaluate` e `wait --fn`. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` è disabilitato quando non impostato, quindi la navigazione del browser resta rigorosa per impostazione predefinita. -- Imposta `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` solo quando intendi esplicitamente fidarti della navigazione browser su rete privata. -- In modalità rigorosa, gli endpoint remoti dei profili CDP (`profiles.*.cdpUrl`) sono soggetti allo stesso blocco di rete privata durante i controlli di raggiungibilità/discovery. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` è disabilitato quando non è impostato, quindi la navigazione del browser resta rigorosa per impostazione predefinita. +- Imposta `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` solo quando ti fidi intenzionalmente della navigazione del browser su rete privata. +- In modalità rigorosa, gli endpoint del profilo CDP remoto (`profiles.*.cdpUrl`) sono soggetti allo stesso blocco della rete privata durante i controlli di raggiungibilità/rilevamento. - `ssrfPolicy.allowPrivateNetwork` resta supportato come alias legacy. - In modalità rigorosa, usa `ssrfPolicy.hostnameAllowlist` e `ssrfPolicy.allowedHostnames` per eccezioni esplicite. -- I profili remoti sono solo attach (start/stop/reset disabilitati). +- I profili remoti sono solo attach-only (start/stop/reset disabilitati). - `profiles.*.cdpUrl` accetta `http://`, `https://`, `ws://` e `wss://`. - Usa HTTP(S) quando vuoi che OpenClaw scopra `/json/version`; usa WS(S) - quando il provider ti fornisce direttamente un URL WebSocket DevTools. -- I profili `existing-session` sono solo host e usano Chrome MCP invece di CDP. + Usa HTTP(S) quando vuoi che OpenClaw rilevi `/json/version`; usa WS(S) + quando il provider fornisce un URL WebSocket DevTools diretto. +- I profili `existing-session` usano Chrome MCP invece di CDP e possono collegarsi + sull'host selezionato o tramite un browser Node connesso. - I profili `existing-session` possono impostare `userDataDir` per puntare a uno specifico - profilo di browser basato su Chromium come Brave o Edge. + profilo browser basato su Chromium come Brave o Edge. - I profili `existing-session` mantengono gli attuali limiti di routing di Chrome MCP: - azioni guidate da snapshot/ref invece del targeting con selettori CSS, hook di upload - di un solo file, nessun override del timeout dei dialoghi, nessun `wait --load networkidle`, e nessun - `responsebody`, esportazione PDF, intercettazione dei download o azioni batch. + azioni guidate da snapshot/ref invece del targeting tramite selettori CSS, hook per upload + di un solo file, nessun override del timeout dei dialoghi, nessun `wait --load networkidle` e + nessun `responsebody`, esportazione PDF, intercettazione dei download o azioni batch. - I profili locali gestiti `openclaw` assegnano automaticamente `cdpPort` e `cdpUrl`; imposta - esplicitamente `cdpUrl` solo per CDP remoto. + `cdpUrl` esplicitamente solo per CDP remoto. - Ordine di auto-rilevamento: browser predefinito se basato su Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. -- Servizio di controllo: solo loopback (porta derivata da `gateway.port`, predefinita `18791`). -- `extraArgs` aggiunge flag di avvio extra allo startup locale di Chromium (per esempio - `--disable-gpu`, dimensionamento della finestra o flag di debug). +- Servizio di controllo: solo loopback (porta derivata da `gateway.port`, predefinito `18791`). +- `extraArgs` aggiunge flag di avvio extra all'avvio locale di Chromium (ad esempio + `--disable-gpu`, dimensionamento finestra o flag di debug). --- @@ -2987,14 +2988,14 @@ Vedi [Plugin](/it/tools/plugin). seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // emoji, short text, image URL, or data URI + avatar: "CB", // emoji, testo breve, URL immagine oppure URI data }, }, } ``` -- `seamColor`: colore di accento per la UI chrome dell'app nativa (tinta del fumetto Talk Mode, ecc.). -- `assistant`: override dell'identità della UI di controllo. Usa come fallback l'identità dell'agente attivo. +- `seamColor`: colore di accento per la chrome UI dell'app nativa (tinta della bolla Talk Mode, ecc.). +- `assistant`: override dell'identità della Control UI. Usa come fallback l'identità dell'agente attivo. --- @@ -3009,8 +3010,8 @@ Vedi [Plugin](/it/tools/plugin). auth: { mode: "token", // none | token | password | trusted-proxy token: "your-token", - // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD - // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth + // password: "your-password", // oppure OPENCLAW_GATEWAY_PASSWORD + // trustedProxy: { userHeader: "x-forwarded-user" }, // per mode=trusted-proxy; vedi /gateway/trusted-proxy-auth allowTailscale: true, rateLimit: { maxAttempts: 10, @@ -3028,9 +3029,9 @@ Vedi [Plugin](/it/tools/plugin). basePath: "/openclaw", // root: "dist/control-ui", // embedSandbox: "scripts", // strict | scripts | trusted - // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs - // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI - // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode + // allowExternalEmbedUrls: false, // pericoloso: consenti URL embed http(s) esterni assoluti + // allowedOrigins: ["https://control.example.com"], // richiesto per Control UI non loopback + // dangerouslyAllowHostHeaderOriginFallback: false, // pericolosa modalità fallback origin Host-header // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -3041,12 +3042,12 @@ Vedi [Plugin](/it/tools/plugin). // password: "your-password", }, trustedProxies: ["10.0.0.1"], - // Optional. Default false. + // Facoltativo. Predefinito false. allowRealIpFallback: false, tools: { - // Additional /tools/invoke HTTP denies + // deny HTTP aggiuntivi per /tools/invoke deny: ["browser"], - // Remove tools from the default HTTP deny list + // Rimuove strumenti dall'elenco deny HTTP predefinito allow: ["gateway"], }, push: { @@ -3063,64 +3064,64 @@ Vedi [Plugin](/it/tools/plugin). -- `mode`: `local` (esegui il gateway) oppure `remote` (connettiti a un gateway remoto). Il Gateway rifiuta di avviarsi se non è `local`. +- `mode`: `local` (esegue il gateway) oppure `remote` (si connette a un gateway remoto). Il gateway rifiuta di avviarsi se non è `local`. - `port`: singola porta multiplexata per WS + HTTP. Precedenza: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. - `bind`: `auto`, `loopback` (predefinito), `lan` (`0.0.0.0`), `tailnet` (solo IP Tailscale) oppure `custom`. -- **Alias bind legacy**: usa i valori di modalità bind in `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), non gli alias host (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Nota Docker**: il bind predefinito `loopback` resta in ascolto su `127.0.0.1` dentro il container. Con il networking bridge di Docker (`-p 18789:18789`), il traffico arriva su `eth0`, quindi il gateway non è raggiungibile. Usa `--network host`, oppure imposta `bind: "lan"` (o `bind: "custom"` con `customBindHost: "0.0.0.0"`) per ascoltare su tutte le interfacce. -- **Auth**: richiesta per impostazione predefinita. I bind non-loopback richiedono l'autenticazione del gateway. In pratica questo significa un token/password condiviso 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`. I flussi di avvio e di installazione/riparazione del servizio falliscono quando entrambi sono configurati e la modalità non è impostata. -- `gateway.auth.mode: "none"`: modalità esplicita senza autenticazione. Usala solo per configurazioni trusted local loopback; intenzionalmente non viene proposta nei prompt di onboarding. -- `gateway.auth.mode: "trusted-proxy"`: delega l'autenticazione a un reverse proxy identity-aware e si fida degli header di identità da `gateway.trustedProxies` (vedi [Autenticazione Trusted Proxy](/it/gateway/trusted-proxy-auth)). Questa modalità si aspetta una sorgente proxy **non-loopback**; i reverse proxy loopback sullo stesso host non soddisfano l'autenticazione trusted-proxy. -- `gateway.auth.allowTailscale`: quando `true`, gli header di identità Tailscale Serve possono soddisfare l'autenticazione di Control UI/WebSocket (verificati tramite `tailscale whois`). Gli endpoint API HTTP **non** usano quell'autenticazione via header Tailscale; seguono invece la normale modalità di autenticazione HTTP del gateway. Questo flusso senza token presuppone che l'host del gateway sia attendibile. Il valore predefinito è `true` quando `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: limiter facoltativo per i tentativi di autenticazione falliti. Si applica per IP client e per ambito di autenticazione (shared-secret e device-token sono tracciati in modo indipendente). I tentativi bloccati restituiscono `429` + `Retry-After`. - - Nel percorso async Tailscale Serve Control UI, i tentativi falliti per lo stesso `{scope, clientIp}` vengono serializzati prima della scrittura del fallimento. Tentativi errati concorrenti dallo stesso client possono quindi attivare il limiter sulla seconda richiesta invece di passare entrambi come semplici mismatch. - - `gateway.auth.rateLimit.exemptLoopback` è `true` per impostazione predefinita; impostalo su `false` quando vuoi intenzionalmente applicare il rate limiting anche al traffico localhost (per setup di test o deployment proxy rigorosi). -- I tentativi di autenticazione WS con origine browser vengono sempre limitati con l'esenzione loopback disabilitata (difesa in profondità contro brute force localhost basati su browser). +- **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` all'interno del contenitore. Con il networking bridge di Docker (`-p 18789:18789`), il traffico arriva su `eth0`, quindi il gateway è irraggiungibile. Usa `--network host`, oppure imposta `bind: "lan"` (o `bind: "custom"` con `customBindHost: "0.0.0.0"`) per ascoltare su tutte le interfacce. +- **Auth**: richiesta per 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 per impostazione predefinita un token. +- Se sono configurati sia `gateway.auth.token` sia `gateway.auth.password` (inclusi SecretRef), imposta esplicitamente `gateway.auth.mode` su `token` oppure `password`. I flussi di avvio e installazione/riparazione del servizio falliscono quando entrambi sono configurati e `mode` non è impostato. +- `gateway.auth.mode: "none"`: modalità esplicita senza auth. Usala solo per configurazioni affidabili di local loopback; intenzionalmente non è offerta dai prompt di onboarding. +- `gateway.auth.mode: "trusted-proxy"`: delega l'auth a un reverse proxy identity-aware e considera affidabili gli header di identità da `gateway.trustedProxies` (vedi [Trusted Proxy Auth](/it/gateway/trusted-proxy-auth)). Questa modalità si aspetta una sorgente proxy **non loopback**; i reverse proxy loopback sullo stesso host non soddisfano l'auth trusted-proxy. +- `gateway.auth.allowTailscale`: quando è `true`, gli header di identità di Tailscale Serve possono soddisfare l'auth di Control UI/WebSocket (verificata tramite `tailscale whois`). Gli endpoint API HTTP **non** usano quell'auth con header Tailscale; seguono invece la normale modalità auth HTTP del gateway. Questo flusso senza token presuppone che l'host del gateway sia affidabile. Il valore predefinito è `true` quando `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: limitatore facoltativo dei tentativi di auth falliti. Si applica per IP client e per ambito auth (shared-secret e device-token sono tracciati indipendentemente). I tentativi bloccati restituiscono `429` + `Retry-After`. + - Sul percorso asincrono Tailscale Serve Control UI, i tentativi falliti per lo stesso `{scope, clientIp}` vengono serializzati prima della scrittura del fallimento. Tentativi concorrenti errati dello stesso client possono quindi attivare il limitatore sulla seconda richiesta invece di passare entrambi in gara come semplici mismatch. + - `gateway.auth.rateLimit.exemptLoopback` ha come predefinito `true`; imposta `false` quando vuoi intenzionalmente limitare anche il traffico localhost (per configurazioni di test o deployment proxy rigorosi). +- I tentativi di auth WS con origine browser vengono sempre limitati con l'esenzione loopback disabilitata (difesa in profondità contro brute force localhost dal browser). - Su loopback, quei lockout con origine browser sono isolati per valore `Origin` - normalizzato, così fallimenti ripetuti da una origin localhost non bloccano - automaticamente un'altra origin. -- `tailscale.mode`: `serve` (solo tailnet, bind loopback) oppure `funnel` (pubblico, richiede autenticazione). -- `controlUi.allowedOrigins`: allowlist esplicita delle origin browser per le connessioni WebSocket del Gateway. Richiesta quando i client browser sono previsti da origin non-loopback. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: modalità pericolosa che abilita il fallback dell'origin tramite header Host per deployment che si basano intenzionalmente sul criterio di origin tramite header Host. -- `remote.transport`: `ssh` (predefinito) oppure `direct` (ws/wss). Per `direct`, `remote.url` deve essere `ws://` o `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: override break-glass lato client che consente `ws://` in chiaro verso IP attendibili di rete privata; per impostazione predefinita il testo in chiaro resta consentito solo sul loopback. -- `gateway.remote.token` / `.password` sono campi credenziali del client remoto. Non configurano di per sé l'autenticazione del gateway. -- `gateway.push.apns.relay.baseUrl`: URL HTTPS base del relay APNs esterno usato dalle build iOS ufficiali/TestFlight dopo che pubblicano registrazioni relay-backed verso il gateway. Questo URL deve corrispondere all'URL del relay compilato nella build iOS. -- `gateway.push.apns.relay.timeoutMs`: timeout in millisecondi per l'invio dal gateway al relay. Predefinito `10000`. -- Le registrazioni relay-backed vengono delegate a una specifica identità del gateway. L'app iOS associata recupera `gateway.identity.get`, include quell'identità nella registrazione relay e inoltra al gateway un permesso di invio con ambito sulla registrazione. Un altro gateway non può riutilizzare quella registrazione memorizzata. + normalizzato, così fallimenti ripetuti da una origine localhost non bloccano + automaticamente un'origine diversa. +- `tailscale.mode`: `serve` (solo tailnet, bind loopback) oppure `funnel` (pubblico, richiede auth). +- `controlUi.allowedOrigins`: allowlist esplicita di origini browser per le connessioni WebSocket del Gateway. Richiesta quando ci si aspetta client browser da origini non loopback. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: modalità pericolosa che abilita il fallback dell'origine tramite header Host per deployment che si affidano intenzionalmente al criterio di origine dell'header Host. +- `remote.transport`: `ssh` (predefinito) oppure `direct` (ws/wss). Per `direct`, `remote.url` deve essere `ws://` oppure `wss://`. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: override break-glass lato client che consente `ws://` in chiaro verso IP di rete privata affidabili; il valore predefinito resta limitato al loopback per il testo in chiaro. +- `gateway.remote.token` / `.password` sono campi di credenziali del client remoto. Non configurano da soli l'auth del gateway. +- `gateway.push.apns.relay.baseUrl`: URL HTTPS base del relay APNs esterno usato dalle build iOS ufficiali/TestFlight dopo che pubblicano registrazioni basate su relay verso il gateway. Questo URL deve corrispondere all'URL relay compilato nella build iOS. +- `gateway.push.apns.relay.timeoutMs`: timeout in millisecondi per l'invio gateway-verso-relay. Predefinito `10000`. +- Le registrazioni basate su relay vengono delegate a una specifica identità gateway. L'app iOS associata recupera `gateway.identity.get`, include quell'identità nella registrazione relay e inoltra al gateway una send grant con ambito registrazione. Un altro gateway non può riutilizzare quella registrazione memorizzata. - `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: override env temporanei per la configurazione relay sopra. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: escape hatch solo per sviluppo per URL relay HTTP in loopback. Gli URL relay di produzione dovrebbero restare su HTTPS. -- `gateway.channelHealthCheckMinutes`: intervallo in minuti del monitor di salute dei canali. Imposta `0` per disabilitare globalmente i riavvii del monitor di salute. Predefinito: `5`. -- `gateway.channelStaleEventThresholdMinutes`: soglia in minuti per socket obsoleti. Mantienila maggiore o uguale a `gateway.channelHealthCheckMinutes`. Predefinito: `30`. -- `gateway.channelMaxRestartsPerHour`: numero massimo di riavvii del monitor di salute per canale/account in un'ora mobile. Predefinito: `10`. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: escape hatch solo per sviluppo per URL relay HTTP loopback. Gli URL relay di produzione dovrebbero restare su HTTPS. +- `gateway.channelHealthCheckMinutes`: intervallo del monitor di salute dei canali in minuti. Imposta `0` per disabilitare globalmente i riavvii del monitor di salute. Predefinito: `5`. +- `gateway.channelStaleEventThresholdMinutes`: soglia socket obsoleti in minuti. Mantienila maggiore o uguale a `gateway.channelHealthCheckMinutes`. Predefinito: `30`. +- `gateway.channelMaxRestartsPerHour`: massimo numero di riavvii del monitor di salute per canale/account in un'ora mobile. Predefinito: `10`. - `channels..healthMonitor.enabled`: opt-out per canale dai riavvii del monitor di salute mantenendo abilitato il monitor globale. -- `channels..accounts..healthMonitor.enabled`: override per account nei canali multi-account. Quando è impostato, ha la precedenza sull'override a livello canale. +- `channels..accounts..healthMonitor.enabled`: override per account per canali multi-account. Quando è impostato, ha la precedenza sull'override a livello canale. - I percorsi di chiamata del gateway locale possono usare `gateway.remote.*` come fallback solo quando `gateway.auth.*` non è impostato. -- Se `gateway.auth.token` / `gateway.auth.password` è configurato esplicitamente tramite SecretRef e non risolto, la risoluzione fallisce in modo fail-closed (nessun fallback remoto che maschera il problema). -- `trustedProxies`: IP dei reverse proxy che terminano TLS o iniettano header client inoltrati. Elenca solo proxy che controlli. Le voci loopback restano valide per setup di rilevamento proxy locale/stesso host (per esempio Tailscale Serve o un reverse proxy locale), ma **non** rendono le richieste loopback idonee a `gateway.auth.mode: "trusted-proxy"`. -- `allowRealIpFallback`: quando `true`, il gateway accetta `X-Real-IP` se manca `X-Forwarded-For`. Predefinito `false` per comportamento fail-closed. -- `gateway.tools.deny`: nomi di strumenti aggiuntivi bloccati per HTTP `POST /tools/invoke` (estende la deny list predefinita). -- `gateway.tools.allow`: rimuove nomi di strumenti dalla deny list HTTP predefinita. +- Se `gateway.auth.token` / `gateway.auth.password` è configurato esplicitamente tramite SecretRef e non risolto, la risoluzione fallisce in modalità fail-closed (nessun fallback remoto che maschera il problema). +- `trustedProxies`: IP di reverse proxy che terminano TLS o iniettano header client inoltrati. Elenca solo proxy che controlli. Le voci loopback restano valide per configurazioni di rilevamento proxy locale/stesso host (ad esempio Tailscale Serve o un reverse proxy locale), ma **non** rendono eleggibili le richieste loopback per `gateway.auth.mode: "trusted-proxy"`. +- `allowRealIpFallback`: quando è `true`, il gateway accetta `X-Real-IP` se `X-Forwarded-For` manca. Predefinito `false` per comportamento fail-closed. +- `gateway.tools.deny`: nomi strumenti extra bloccati per HTTP `POST /tools/invoke` (estende l'elenco deny predefinito). +- `gateway.tools.allow`: rimuove nomi strumenti dall'elenco deny HTTP predefinito. -### Endpoint OpenAI-compatible +### Endpoint compatibili con OpenAI - Chat Completions: disabilitato per impostazione predefinita. Abilitalo con `gateway.http.endpoints.chatCompletions.enabled: true`. -- API Responses: `gateway.http.endpoints.responses.enabled`. -- Hardening degli URL input di Responses: +- Responses API: `gateway.http.endpoints.responses.enabled`. +- Hardening degli input URL di Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - Le allowlist vuote sono trattate come non impostate; usa `gateway.http.endpoints.responses.files.allowUrl=false` - e/o `gateway.http.endpoints.responses.images.allowUrl=false` per disabilitare il recupero tramite URL. + Le allowlist vuote vengono trattate come non impostate; usa `gateway.http.endpoints.responses.files.allowUrl=false` + e/o `gateway.http.endpoints.responses.images.allowUrl=false` per disabilitare il recupero URL. - Header facoltativo di hardening della risposta: - - `gateway.http.securityHeaders.strictTransportSecurity` (impostalo solo per origin HTTPS che controlli; vedi [Autenticazione Trusted Proxy](/it/gateway/trusted-proxy-auth#tls-termination-and-hsts)) + - `gateway.http.securityHeaders.strictTransportSecurity` (impostalo solo per origini HTTPS che controlli; vedi [Trusted Proxy Auth](/it/gateway/trusted-proxy-auth#tls-termination-and-hsts)) -### Isolamento multi-instance +### Isolamento multi-istanza -Esegui più gateway su un singolo host con porte e directory di stato univoche: +Esegui più gateway sullo stesso host con porte e directory di stato uniche: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -3149,10 +3150,10 @@ Vedi [Gateway multipli](/it/gateway/multiple-gateways). ``` - `enabled`: abilita la terminazione TLS sul listener del gateway (HTTPS/WSS) (predefinito: `false`). -- `autoGenerate`: genera automaticamente una coppia locale certificato/chiave self-signed quando non sono configurati file espliciti; solo per uso locale/dev. +- `autoGenerate`: genera automaticamente una coppia cert/key locale self-signed quando non sono configurati file espliciti; solo per uso locale/dev. - `certPath`: percorso filesystem del file del certificato TLS. -- `keyPath`: percorso filesystem del file della chiave privata TLS; mantienilo con permessi limitati. -- `caPath`: percorso facoltativo del bundle CA per la verifica client o per catene di trust personalizzate. +- `keyPath`: percorso filesystem della chiave privata TLS; mantieni permessi ristretti. +- `caPath`: percorso facoltativo del bundle CA per verifica client o catene di attendibilità personalizzate. ### `gateway.reload` @@ -3168,13 +3169,13 @@ Vedi [Gateway multipli](/it/gateway/multiple-gateways). } ``` -- `mode`: controlla come le modifiche alla config vengono applicate a runtime. - - `"off"`: ignora le modifiche live; i cambiamenti richiedono un riavvio esplicito. - - `"restart"`: riavvia sempre il processo gateway quando la config cambia. - - `"hot"`: applica le modifiche in-process senza riavvio. - - `"hybrid"` (predefinito): prova prima l'hot reload; se necessario passa al riavvio. -- `debounceMs`: finestra di debounce in ms prima che le modifiche della config vengano applicate (intero non negativo). -- `deferralTimeoutMs`: tempo massimo in ms di attesa per le operazioni in corso prima di forzare un riavvio (predefinito: `300000` = 5 minuti). +- `mode`: controlla come le modifiche di configurazione vengono applicate a runtime. + - `"off"`: ignora le modifiche live; le modifiche richiedono un riavvio esplicito. + - `"restart"`: riavvia sempre il processo gateway a ogni modifica della configurazione. + - `"hot"`: applica le modifiche in-process senza riavviare. + - `"hybrid"` (predefinito): prova prima l'hot reload; torna al riavvio se necessario. +- `debounceMs`: finestra di debounce in ms prima che le modifiche di configurazione vengano applicate (intero non negativo). +- `deferralTimeoutMs`: tempo massimo in ms di attesa per operazioni in corso prima di forzare un riavvio (predefinito: `300000` = 5 minuti). --- @@ -3214,12 +3215,12 @@ Vedi [Gateway multipli](/it/gateway/multiple-gateways). Auth: `Authorization: Bearer ` oppure `x-openclaw-token: `. I token hook nella query string vengono rifiutati. -Note su convalida e sicurezza: +Note di convalida e sicurezza: - `hooks.enabled=true` richiede un `hooks.token` non vuoto. - `hooks.token` deve essere **distinto** da `gateway.auth.token`; il riutilizzo del token del Gateway viene rifiutato. - `hooks.path` non può essere `/`; usa un sottopercorso dedicato come `/hooks`. -- Se `hooks.allowRequestSessionKey=true`, limita `hooks.allowedSessionKeyPrefixes` (per esempio `["hook:"]`). +- Se `hooks.allowRequestSessionKey=true`, limita `hooks.allowedSessionKeyPrefixes` (ad esempio `["hook:"]`). **Endpoint:** @@ -3230,17 +3231,17 @@ Note su convalida e sicurezza: -- `match.path` corrisponde al sottopercorso dopo `/hooks` (ad es. `/hooks/gmail` → `gmail`). -- `match.source` corrisponde a un campo del payload per i percorsi generici. +- `match.path` corrisponde al sottopercorso dopo `/hooks` (ad esempio `/hooks/gmail` → `gmail`). +- `match.source` corrisponde a un campo del payload per percorsi generici. - Template come `{{messages[0].subject}}` leggono dal payload. - `transform` può puntare a un modulo JS/TS che restituisce un'azione hook. - - `transform.module` deve essere un percorso relativo e resta all'interno di `hooks.transformsDir` (i percorsi assoluti e il traversal vengono rifiutati). -- `agentId` instrada verso un agente specifico; gli ID sconosciuti usano come fallback quello predefinito. -- `allowedAgentIds`: limita il routing esplicito (`*` oppure omesso = consenti tutti, `[]` = nega tutti). -- `defaultSessionKey`: chiave di sessione fissa facoltativa per esecuzioni dell'agente hook senza `sessionKey` esplicito. + - `transform.module` deve essere un percorso relativo e restare entro `hooks.transformsDir` (i percorsi assoluti e il traversal vengono rifiutati). +- `agentId` instrada verso un agente specifico; gli ID sconosciuti usano come fallback il predefinito. +- `allowedAgentIds`: limita il routing esplicito (`*` oppure omesso = consenti tutto, `[]` = nega tutto). +- `defaultSessionKey`: chiave di sessione fissa facoltativa per esecuzioni dell'agente hook senza `sessionKey` esplicita. - `allowRequestSessionKey`: consente ai chiamanti di `/hooks/agent` di impostare `sessionKey` (predefinito: `false`). -- `allowedSessionKeyPrefixes`: allowlist facoltativa di prefissi per valori `sessionKey` espliciti (richiesta + mapping), ad es. `["hook:"]`. -- `deliver: true` invia la risposta finale a un canale; `channel` usa `last` come valore predefinito. +- `allowedSessionKeyPrefixes`: allowlist facoltativa di prefissi per valori `sessionKey` espliciti (richiesta + mapping), ad esempio `["hook:"]`. +- `deliver: true` invia la risposta finale a un canale; `channel` usa come predefinito `last`. - `model` sovrascrive l'LLM per questa esecuzione hook (deve essere consentito se è impostato il catalogo modelli). @@ -3268,19 +3269,19 @@ Note su convalida e sicurezza: } ``` -- Il Gateway avvia automaticamente `gog gmail watch serve` all'avvio quando è configurato. Imposta `OPENCLAW_SKIP_GMAIL_WATCHER=1` per disabilitarlo. +- Il Gateway avvia automaticamente `gog gmail watch serve` all'avvio quando configurato. Imposta `OPENCLAW_SKIP_GMAIL_WATCHER=1` per disabilitarlo. - Non eseguire un `gog gmail watch serve` separato insieme al Gateway. --- -## Host canvas +## Host Canvas ```json5 { canvasHost: { root: "~/.openclaw/workspace/canvas", liveReload: true, - // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1 + // enabled: false, // oppure OPENCLAW_SKIP_CANVAS_HOST=1 }, } ``` @@ -3289,12 +3290,12 @@ Note su convalida e sicurezza: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` - Solo locale: mantieni `gateway.bind: "loopback"` (predefinito). -- Bind non-loopback: le route canvas richiedono l'autenticazione del Gateway (token/password/trusted-proxy), come le altre superfici HTTP del Gateway. -- I Node WebView in genere non inviano header di autenticazione; dopo che un node è stato associato e connesso, il Gateway pubblicizza URL di capability con ambito node per l'accesso a canvas/A2UI. -- Gli URL di capability sono associati alla sessione WS attiva del node e scadono rapidamente. Il fallback basato su IP non viene usato. +- Bind non loopback: le route canvas richiedono auth del Gateway (token/password/trusted-proxy), come le altre superfici HTTP del Gateway. +- I Node WebView in genere non inviano header auth; dopo che un Node è associato e connesso, il Gateway pubblicizza URL capability con ambito Node per l'accesso a canvas/A2UI. +- Gli URL capability sono vincolati alla sessione WS del Node attiva e scadono rapidamente. Il fallback basato su IP non viene usato. - Inietta il client live-reload nell'HTML servito. - Crea automaticamente un `index.html` iniziale quando è vuoto. -- Serve anche A2UI in `/__openclaw__/a2ui/`. +- Serve anche A2UI su `/__openclaw__/a2ui/`. - Le modifiche richiedono un riavvio del gateway. - Disabilita il live reload per directory grandi o errori `EMFILE`. @@ -3316,7 +3317,7 @@ Note su convalida e sicurezza: - `minimal` (predefinito): omette `cliPath` + `sshPort` dai record TXT. - `full`: include `cliPath` + `sshPort`. -- L'hostname predefinito è `openclaw`. Sovrascrivilo con `OPENCLAW_MDNS_HOSTNAME`. +- L'hostname usa come predefinito `openclaw`. Sovrascrivilo con `OPENCLAW_MDNS_HOSTNAME`. ### Wide-area (DNS-SD) @@ -3328,9 +3329,9 @@ Note su convalida e sicurezza: } ``` -Scrive una zona DNS-SD unicast sotto `~/.openclaw/dns/`. Per il discovery cross-network, abbinala a un server DNS (si consiglia CoreDNS) + split DNS Tailscale. +Scrive una zona DNS-SD unicast in `~/.openclaw/dns/`. Per il rilevamento cross-network, abbinala a un server DNS (consigliato CoreDNS) + split DNS Tailscale. -Setup: `openclaw dns setup --apply`. +Configurazione: `openclaw dns setup --apply`. --- @@ -3353,8 +3354,8 @@ Setup: `openclaw dns setup --apply`. } ``` -- Le variabili env inline vengono applicate solo se manca la chiave nell'env del processo. -- File `.env`: `.env` della CWD + `~/.openclaw/.env` (nessuno dei due sovrascrive variabili esistenti). +- Le variabili env inline vengono applicate solo se nell'env del processo manca la chiave. +- File `.env`: `.env` nella CWD + `~/.openclaw/.env` (nessuno dei due sovrascrive variabili esistenti). - `shellEnv`: importa le chiavi attese mancanti dal profilo della tua shell di login. - Vedi [Ambiente](/it/help/environment) per la precedenza completa. @@ -3372,18 +3373,18 @@ Fai riferimento alle variabili env in qualsiasi stringa di configurazione con `$ - Vengono riconosciuti solo nomi maiuscoli corrispondenti a: `[A-Z_][A-Z0-9_]*`. - Variabili mancanti/vuote generano un errore al caricamento della configurazione. -- Esegui l'escape con `$${VAR}` per un `${VAR}` letterale. +- Effettua l'escape con `$${VAR}` per un letterale `${VAR}`. - Funziona con `$include`. --- -## Segreti +## Secret -I riferimenti ai segreti sono additivi: i valori in chiaro continuano a funzionare. +I riferimenti ai secret sono additivi: i valori in chiaro continuano a funzionare. ### `SecretRef` -Usa un'unica shape oggetto: +Usa una sola forma oggetto: ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } @@ -3392,24 +3393,24 @@ Usa un'unica shape oggetto: Convalida: - pattern `provider`: `^[a-z][a-z0-9_-]{0,63}$` -- pattern `id` per `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` -- `source: "file"` id: JSON pointer assoluto (per esempio `"/providers/openai/apiKey"`) -- pattern `id` per `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- Gli `id` di `source: "exec"` non devono contenere segmenti di percorso delimitati da slash `.` o `..` (per esempio `a/../b` viene rifiutato) +- pattern `id` con `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` +- `source: "file"` `id`: puntatore JSON assoluto (ad esempio `"/providers/openai/apiKey"`) +- pattern `id` con `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` +- Gli `id` con `source: "exec"` non devono contenere segmenti di percorso delimitati da slash `.` o `..` (ad esempio `a/../b` viene rifiutato) -### Superficie delle credenziali supportata +### Superficie credenziali supportata -- Matrice canonica: [Superficie delle credenziali SecretRef](/it/reference/secretref-credential-surface) -- `secrets apply` prende come target i percorsi credenziali supportati di `openclaw.json`. -- I riferimenti in `auth-profiles.json` sono inclusi nella risoluzione runtime e nella copertura audit. +- Matrice canonica: [Superficie credenziali SecretRef](/it/reference/secretref-credential-surface) +- `secrets apply` usa come target i percorsi credenziali supportati di `openclaw.json`. +- I riferimenti in `auth-profiles.json` sono inclusi nella risoluzione runtime e nella copertura di audit. -### Config dei provider di segreti +### Configurazione dei provider di secret ```json5 { secrets: { providers: { - default: { source: "env" }, // optional explicit env provider + default: { source: "env" }, // provider env esplicito facoltativo filemain: { source: "file", path: "~/.openclaw/secrets.json", @@ -3436,10 +3437,10 @@ Note: - Il provider `file` supporta `mode: "json"` e `mode: "singleValue"` (`id` deve essere `"value"` in modalità singleValue). - Il provider `exec` richiede un percorso `command` assoluto e usa payload di protocollo su stdin/stdout. - Per impostazione predefinita, i percorsi comando symlink vengono rifiutati. Imposta `allowSymlinkCommand: true` per consentire percorsi symlink con convalida del percorso target risolto. -- Se è configurato `trustedDirs`, il controllo della directory trusted si applica al percorso target risolto. -- L'ambiente figlio `exec` è minimo per impostazione predefinita; passa esplicitamente le variabili necessarie con `passEnv`. -- I riferimenti ai segreti vengono risolti al momento dell'attivazione in uno snapshot in memoria, poi i percorsi di richiesta leggono solo quello snapshot. -- Durante l'attivazione si applica il filtro active-surface: i riferimenti non risolti su superfici abilitate fanno fallire startup/reload, mentre le superfici inattive vengono saltate con diagnostica. +- Se `trustedDirs` è configurato, il controllo trusted-dir si applica al percorso target risolto. +- L'ambiente figlio di `exec` è minimale per impostazione predefinita; passa esplicitamente le variabili richieste con `passEnv`. +- I riferimenti ai secret vengono risolti al momento dell'attivazione in uno snapshot in memoria, poi i percorsi di richiesta leggono solo lo snapshot. +- Durante l'attivazione si applica il filtraggio della superficie attiva: i riferimenti non risolti su superfici abilitate fanno fallire avvio/reload, mentre le superfici inattive vengono saltate con diagnostica. --- @@ -3461,13 +3462,13 @@ Note: } ``` -- I profili per agente sono memorizzati in `/auth-profiles.json`. -- `auth-profiles.json` supporta riferimenti a livello di valore (`keyRef` per `api_key`, `tokenRef` per `token`) per le modalità di credenziali statiche. +- I profili per agente sono archiviati in `/auth-profiles.json`. +- `auth-profiles.json` supporta riferimenti a livello valore (`keyRef` per `api_key`, `tokenRef` per `token`) per modalità di credenziali statiche. - I profili in modalità OAuth (`auth.profiles..mode = "oauth"`) non supportano credenziali del profilo auth supportate da SecretRef. -- Le credenziali runtime statiche provengono da snapshot risolti in memoria; le voci statiche legacy di `auth.json` vengono ripulite quando individuate. -- Importazioni OAuth legacy da `~/.openclaw/credentials/oauth.json`. +- Le credenziali runtime statiche provengono da snapshot risolti in memoria; le voci statiche legacy di `auth.json` vengono ripulite quando rilevate. +- Import legacy OAuth da `~/.openclaw/credentials/oauth.json`. - Vedi [OAuth](/it/concepts/oauth). -- Comportamento runtime dei segreti e tooling `audit/configure/apply`: [Gestione dei segreti](/it/gateway/secrets). +- Comportamento runtime dei secret e strumenti `audit/configure/apply`: [Gestione dei secret](/it/gateway/secrets). ### `auth.cooldowns` @@ -3490,19 +3491,19 @@ Note: ``` - `billingBackoffHours`: backoff base in ore quando un profilo fallisce per veri - errori di fatturazione/credito insufficiente (predefinito: `5`). Testo esplicito relativo alla fatturazione può + errori di fatturazione/credito insufficiente (predefinito: `5`). Testi espliciti di fatturazione possono comunque finire qui anche su risposte `401`/`403`, ma i matcher di testo - specifici del provider restano limitati al provider che li possiede (per esempio OpenRouter - `Key limit exceeded`). I messaggi HTTP `402` retryable relativi a usage-window o - ai limiti di spesa di organizzazione/workspace restano invece nel percorso `rate_limit`. -- `billingBackoffHoursByProvider`: override facoltativi per provider delle ore di backoff per fatturazione. + specifici del provider restano limitati al provider che li possiede (ad esempio OpenRouter + `Key limit exceeded`). I messaggi retryable HTTP `402` relativi a usage-window o + spend limit di organizzazione/workspace restano invece nel percorso `rate_limit`. +- `billingBackoffHoursByProvider`: override facoltativi per provider del backoff di fatturazione in ore. - `billingMaxHours`: limite massimo in ore per la crescita esponenziale del backoff di fatturazione (predefinito: `24`). -- `authPermanentBackoffMinutes`: backoff base in minuti per errori `auth_permanent` ad alta confidenza (predefinito: `10`). +- `authPermanentBackoffMinutes`: backoff base in minuti per fallimenti `auth_permanent` ad alta confidenza (predefinito: `10`). - `authPermanentMaxMinutes`: limite massimo in minuti per la crescita del backoff `auth_permanent` (predefinito: `60`). - `failureWindowHours`: finestra mobile in ore usata per i contatori di backoff (predefinito: `24`). -- `overloadedProfileRotations`: massimo numero di rotazioni auth-profile dello stesso provider per errori di overload prima di passare al fallback del modello (predefinito: `1`). Le shape di provider occupato come `ModelNotReadyException` finiscono qui. -- `overloadedBackoffMs`: ritardo fisso prima di ritentare una rotazione di provider/profilo in overload (predefinito: `0`). -- `rateLimitedProfileRotations`: massimo numero di rotazioni auth-profile dello stesso provider per errori di rate limit prima di passare al fallback del modello (predefinito: `1`). Quel bucket di rate limit include testo tipico del provider come `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` e `resource exhausted`. +- `overloadedProfileRotations`: massimo numero di rotazioni dello stesso provider auth-profile per errori di sovraccarico prima di passare al fallback del modello (predefinito: `1`). Forme provider-busy come `ModelNotReadyException` finiscono qui. +- `overloadedBackoffMs`: ritardo fisso prima di ritentare una rotazione di provider/profile sovraccarico (predefinito: `0`). +- `rateLimitedProfileRotations`: massimo numero di rotazioni dello stesso provider auth-profile per errori di rate limit prima di passare al fallback del modello (predefinito: `1`). Quel bucket di rate limit include testo modellato dal provider come `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` e `resource exhausted`. --- @@ -3523,8 +3524,8 @@ Note: - File di log predefinito: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. - Imposta `logging.file` per un percorso stabile. -- `consoleLevel` passa a `debug` quando si usa `--verbose`. -- `maxFileBytes`: dimensione massima del file di log in byte prima che le scritture vengano soppresse (intero positivo; predefinito: `524288000` = 500 MB). Usa rotazione esterna dei log per i deployment di produzione. +- `consoleLevel` passa a `debug` quando usi `--verbose`. +- `maxFileBytes`: dimensione massima del file di log in byte prima che le scritture vengano soppresse (intero positivo; predefinito: `524288000` = 500 MB). Usa una rotazione log esterna per deployment di produzione. --- @@ -3561,20 +3562,20 @@ Note: } ``` -- `enabled`: switch master per l'output di instrumentazione (predefinito: `true`). -- `flags`: array di stringhe flag che abilitano output di log mirati (supporta wildcard come `"telegram.*"` oppure `"*"`). +- `enabled`: interruttore principale per l'output di strumentazione (predefinito: `true`). +- `flags`: array di stringhe flag che abilitano output di log mirato (supporta wildcard come `"telegram.*"` oppure `"*"`). - `stuckSessionWarnMs`: soglia di età in ms per emettere avvisi di sessione bloccata mentre una sessione resta nello stato di elaborazione. - `otel.enabled`: abilita la pipeline di esportazione OpenTelemetry (predefinito: `false`). - `otel.endpoint`: URL del collector per l'esportazione OTel. - `otel.protocol`: `"http/protobuf"` (predefinito) oppure `"grpc"`. -- `otel.headers`: header di metadati HTTP/gRPC aggiuntivi inviati con le richieste di esportazione OTel. +- `otel.headers`: header di metadati HTTP/gRPC extra inviati con le richieste di esportazione OTel. - `otel.serviceName`: nome del servizio per gli attributi della risorsa. - `otel.traces` / `otel.metrics` / `otel.logs`: abilita l'esportazione di trace, metriche o log. -- `otel.sampleRate`: tasso di campionamento delle trace `0`–`1`. +- `otel.sampleRate`: frequenza di campionamento delle trace `0`–`1`. - `otel.flushIntervalMs`: intervallo periodico di flush della telemetria in ms. -- `cacheTrace.enabled`: registra snapshot di cache trace per le esecuzioni embedded (predefinito: `false`). -- `cacheTrace.filePath`: percorso di output per il JSONL della cache trace (predefinito: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: controllano cosa è incluso nell'output della cache trace (tutti predefiniti: `true`). +- `cacheTrace.enabled`: registra snapshot di cache trace per esecuzioni incorporate (predefinito: `false`). +- `cacheTrace.filePath`: percorso di output per il JSONL di cache trace (predefinito: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: controllano cosa viene incluso nell'output di cache trace (tutti con predefinito: `true`). --- @@ -3598,10 +3599,10 @@ Note: - `channel`: canale di rilascio per installazioni npm/git — `"stable"`, `"beta"` oppure `"dev"`. - `checkOnStart`: controlla la presenza di aggiornamenti npm all'avvio del gateway (predefinito: `true`). -- `auto.enabled`: abilita l'auto-aggiornamento in background per le installazioni di pacchetti (predefinito: `false`). +- `auto.enabled`: abilita l'aggiornamento automatico in background per le installazioni di pacchetti (predefinito: `false`). - `auto.stableDelayHours`: ritardo minimo in ore prima dell'applicazione automatica sul canale stable (predefinito: `6`; massimo: `168`). -- `auto.stableJitterHours`: finestra aggiuntiva di distribuzione in ore per il canale stable (predefinito: `12`; massimo: `168`). -- `auto.betaCheckIntervalHours`: frequenza dei controlli sul canale beta in ore (predefinito: `1`; massimo: `24`). +- `auto.stableJitterHours`: finestra extra di distribuzione graduale sul canale stable in ore (predefinito: `12`; massimo: `168`). +- `auto.betaCheckIntervalHours`: frequenza in ore dei controlli sul canale beta (predefinito: `1`; massimo: `24`). --- @@ -3634,21 +3635,21 @@ Note: } ``` -- `enabled`: feature gate globale ACP (predefinito: `false`). +- `enabled`: gate globale della funzionalità ACP (predefinito: `false`). - `dispatch.enabled`: gate indipendente per il dispatch dei turni di sessione ACP (predefinito: `true`). Imposta `false` per mantenere disponibili i comandi ACP bloccando però l'esecuzione. -- `backend`: ID predefinito del backend runtime ACP (deve corrispondere a un Plugin runtime ACP registrato). -- `defaultAgent`: ID agente ACP di fallback quando le spawn non specificano un target esplicito. -- `allowedAgents`: allowlist di ID agente consentiti per le sessioni runtime ACP; vuota significa nessuna restrizione aggiuntiva. +- `backend`: ID backend runtime ACP predefinito (deve corrispondere a un plugin runtime ACP registrato). +- `defaultAgent`: ID agente ACP di fallback quando gli spawn non specificano un target esplicito. +- `allowedAgents`: allowlist di ID agente consentiti per le sessioni runtime ACP; vuoto significa nessuna restrizione aggiuntiva. - `maxConcurrentSessions`: numero massimo di sessioni ACP attive contemporaneamente. - `stream.coalesceIdleMs`: finestra di flush inattivo in ms per il testo in streaming. -- `stream.maxChunkChars`: dimensione massima del chunk prima di dividere la proiezione del blocco in streaming. -- `stream.repeatSuppression`: sopprime righe ripetute di stato/strumenti per turno (predefinito: `true`). -- `stream.deliveryMode`: `"live"` esegue streaming incrementale; `"final_only"` bufferizza fino agli eventi terminali del turno. -- `stream.hiddenBoundarySeparator`: separatore prima del testo visibile dopo eventi di strumenti nascosti (predefinito: `"paragraph"`). -- `stream.maxOutputChars`: massimo numero di caratteri dell'output assistant proiettati per turno ACP. +- `stream.maxChunkChars`: dimensione massima del blocco prima della suddivisione della proiezione del blocco in streaming. +- `stream.repeatSuppression`: sopprime le righe ripetute di stato/strumenti per turno (predefinito: `true`). +- `stream.deliveryMode`: `"live"` effettua lo streaming incrementale; `"final_only"` accumula fino agli eventi terminali del turno. +- `stream.hiddenBoundarySeparator`: separatore prima del testo visibile dopo eventi nascosti degli strumenti (predefinito: `"paragraph"`). +- `stream.maxOutputChars`: massimo numero di caratteri di output dell'assistente proiettati per turno ACP. - `stream.maxSessionUpdateChars`: massimo numero di caratteri per le righe proiettate di stato/aggiornamento ACP. -- `stream.tagVisibility`: record da nomi di tag a override booleani di visibilità per gli eventi in streaming. -- `runtime.ttlMinutes`: TTL di inattività in minuti per i worker di sessione ACP prima che siano idonei alla pulizia. +- `stream.tagVisibility`: record da nomi di tag a override booleani di visibilità per eventi in streaming. +- `runtime.ttlMinutes`: TTL inattivo in minuti per i worker di sessione ACP prima che diventino idonei alla pulizia. - `runtime.installCommand`: comando di installazione facoltativo da eseguire durante il bootstrap di un ambiente runtime ACP. --- @@ -3665,17 +3666,17 @@ Note: } ``` -- `cli.banner.taglineMode` controlla lo stile della tagline del banner: - - `"random"` (predefinito): tagline a rotazione divertenti/stagionali. - - `"default"`: tagline neutrale fissa (`All your chats, one OpenClaw.`). - - `"off"`: nessun testo tagline (titolo/versione del banner comunque mostrati). -- Per nascondere l'intero banner (non solo le tagline), imposta l'env `OPENCLAW_HIDE_BANNER=1`. +- `cli.banner.taglineMode` controlla lo stile del tagline del banner: + - `"random"` (predefinito): tagline rotanti divertenti/stagionali. + - `"default"`: tagline neutra fissa (`All your chats, one OpenClaw.`). + - `"off"`: nessun testo tagline (restano comunque mostrati titolo/versione del banner). +- Per nascondere l'intero banner (non solo i tagline), imposta la variabile env `OPENCLAW_HIDE_BANNER=1`. --- ## Wizard -Metadati scritti dai flussi di setup guidato della CLI (`onboard`, `configure`, `doctor`): +Metadati scritti dai flussi di configurazione guidata della CLI (`onboard`, `configure`, `doctor`): ```json5 { @@ -3693,13 +3694,13 @@ Metadati scritti dai flussi di setup guidato della CLI (`onboard`, `configure`, ## Identità -Vedi i campi identity di `agents.list` in [Valori predefiniti degli agenti](#agent-defaults). +Vedi i campi `identity` di `agents.list` in [Valori predefiniti dell'agente](#agent-defaults). --- ## Bridge (legacy, rimosso) -Le build correnti non includono più il bridge TCP. I node si connettono tramite il WebSocket del Gateway. Le chiavi `bridge.*` non fanno più parte dello schema di configurazione (la convalida fallisce finché non vengono rimosse; `openclaw doctor --fix` può eliminare le chiavi sconosciute). +Le build correnti non includono più il bridge TCP. I Node si connettono tramite il WebSocket Gateway. Le chiavi `bridge.*` non fanno più parte dello schema di configurazione (la convalida fallisce finché non vengono rimosse; `openclaw doctor --fix` può eliminare le chiavi sconosciute). @@ -3728,22 +3729,22 @@ Le build correnti non includono più il bridge TCP. I node si connettono tramite cron: { enabled: true, maxConcurrentRuns: 2, - webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs - webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth - sessionRetention: "24h", // duration string or false + webhook: "https://example.invalid/legacy", // fallback deprecato per i job memorizzati con notify:true + webhookToken: "replace-with-dedicated-token", // bearer token facoltativo per auth webhook in uscita + sessionRetention: "24h", // stringa di durata oppure false runLog: { - maxBytes: "2mb", // default 2_000_000 bytes - keepLines: 2000, // default 2000 + maxBytes: "2mb", // predefinito 2_000_000 byte + keepLines: 2000, // predefinito 2000 }, }, } ``` -- `sessionRetention`: per quanto tempo conservare le sessioni completate delle esecuzioni Cron isolate prima di eliminarle da `sessions.json`. Controlla anche la pulizia dei transcript Cron eliminati archiviati. Predefinito: `24h`; imposta `false` per disabilitare. -- `runLog.maxBytes`: dimensione massima per file di log di esecuzione (`cron/runs/.jsonl`) prima del pruning. Predefinito: `2_000_000` byte. -- `runLog.keepLines`: righe più recenti conservate quando viene attivato il pruning del log di esecuzione. Predefinito: `2000`. -- `webhookToken`: token bearer usato per la consegna POST Webhook di Cron (`delivery.mode = "webhook"`); se omesso non viene inviato alcun header di autenticazione. -- `webhook`: URL Webhook di fallback legacy deprecato (http/https) usato solo per i job memorizzati che hanno ancora `notify: true`. +- `sessionRetention`: per quanto tempo mantenere le sessioni completate delle esecuzioni Cron isolate prima di rimuoverle da `sessions.json`. Controlla anche la pulizia delle trascrizioni Cron eliminate archiviate. Predefinito: `24h`; imposta `false` per disabilitare. +- `runLog.maxBytes`: dimensione massima per file di log di esecuzione (`cron/runs/.jsonl`) prima della potatura. Predefinito: `2_000_000` byte. +- `runLog.keepLines`: righe più recenti conservate quando viene attivata la potatura del log di esecuzione. Predefinito: `2000`. +- `webhookToken`: bearer token usato per la consegna POST del webhook Cron (`delivery.mode = "webhook"`); se omesso non viene inviato alcun header auth. +- `webhook`: URL webhook legacy deprecato di fallback (http/https) usato solo per i job memorizzati che hanno ancora `notify: true`. ### `cron.retry` @@ -3759,11 +3760,11 @@ Le build correnti non includono più il bridge TCP. I node si connettono tramite } ``` -- `maxAttempts`: numero massimo di retry per i job one-shot su errori transitori (predefinito: `3`; intervallo: `0`–`10`). +- `maxAttempts`: massimo numero di retry per job one-shot in caso di errori transitori (predefinito: `3`; intervallo: `0`–`10`). - `backoffMs`: array di ritardi di backoff in ms per ogni tentativo di retry (predefinito: `[30000, 60000, 300000]`; 1–10 voci). -- `retryOn`: tipi di errore che attivano i retry — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Omettilo per ritentare tutti i tipi transitori. +- `retryOn`: tipi di errore che attivano i retry — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Ometti per ritentare tutti i tipi transitori. -Si applica solo ai job Cron one-shot. I job ricorrenti usano una gestione separata degli errori. +Si applica solo ai job Cron one-shot. I job ricorrenti usano una gestione dei fallimenti separata. ### `cron.failureAlert` @@ -3782,10 +3783,10 @@ Si applica solo ai job Cron one-shot. I job ricorrenti usano una gestione separa ``` - `enabled`: abilita gli avvisi di errore per i job Cron (predefinito: `false`). -- `after`: errori consecutivi prima che venga emesso un avviso (intero positivo, min: `1`). +- `after`: numero di errori consecutivi prima che venga inviato un avviso (intero positivo, min: `1`). - `cooldownMs`: millisecondi minimi tra avvisi ripetuti per lo stesso job (intero non negativo). -- `mode`: modalità di consegna — `"announce"` invia tramite un messaggio del canale; `"webhook"` esegue un POST al Webhook configurato. -- `accountId`: ID facoltativo di account o canale per limitare l'ambito della consegna dell'avviso. +- `mode`: modalità di consegna — `"announce"` invia tramite un messaggio di canale; `"webhook"` esegue una POST al webhook configurato. +- `accountId`: ID account o canale facoltativo per limitare la consegna degli avvisi. ### `cron.failureDestination` @@ -3803,43 +3804,43 @@ Si applica solo ai job Cron one-shot. I job ricorrenti usano una gestione separa ``` - Destinazione predefinita per le notifiche di errore Cron per tutti i job. -- `mode`: `"announce"` oppure `"webhook"`; usa `"announce"` come predefinito quando esistono dati target sufficienti. -- `channel`: override del canale per la consegna announce. `"last"` riutilizza l'ultimo canale di consegna noto. -- `to`: target announce esplicito o URL Webhook. Obbligatorio per la modalità Webhook. -- `accountId`: override facoltativo dell'account per la consegna. +- `mode`: `"announce"` oppure `"webhook"`; usa come predefinito `"announce"` quando esistono dati target sufficienti. +- `channel`: override del canale per la consegna `announce`. `"last"` riutilizza l'ultimo canale di consegna noto. +- `to`: target esplicito per `announce` oppure URL webhook. Obbligatorio per la modalità webhook. +- `accountId`: override account facoltativo per la consegna. - `delivery.failureDestination` per job sovrascrive questo valore predefinito globale. -- Quando non è impostata né una destinazione di errore globale né una per job, i job che già consegnano tramite `announce` tornano su quel target announce principale in caso di errore. -- `delivery.failureDestination` è supportato solo per i job `sessionTarget="isolated"` a meno che `delivery.mode` principale del job non sia `"webhook"`. +- Quando non è impostata né la destinazione di errore globale né quella per job, i job che già consegnano tramite `announce` usano come fallback quel target principale `announce` in caso di errore. +- `delivery.failureDestination` è supportato solo per job `sessionTarget="isolated"` a meno che `delivery.mode` principale del job non sia `"webhook"`. -Vedi [Job Cron](/it/automation/cron-jobs). Le esecuzioni Cron isolate vengono tracciate come [task in background](/it/automation/tasks). +Vedi [Job Cron](/it/automation/cron-jobs). Le esecuzioni Cron isolate sono tracciate come [attività in background](/it/automation/tasks). --- -## Variabili di template del modello media +## Variabili template del modello media -Placeholder di template espansi in `tools.media.models[].args`: +Segnaposto template espansi in `tools.media.models[].args`: -| Variabile | Descrizione | -| ------------------ | ------------------------------------------------ | -| `{{Body}}` | Corpo completo del messaggio in ingresso | -| `{{RawBody}}` | Corpo raw (senza wrapper di cronologia/mittente) | -| `{{BodyStripped}}` | Corpo con le mention di gruppo rimosse | -| `{{From}}` | Identificatore del mittente | -| `{{To}}` | Identificatore di destinazione | -| `{{MessageSid}}` | ID del messaggio del canale | -| `{{SessionId}}` | UUID della sessione corrente | -| `{{IsNewSession}}` | `"true"` quando viene creata una nuova sessione | -| `{{MediaUrl}}` | pseudo-URL del media in ingresso | -| `{{MediaPath}}` | percorso locale del media | -| `{{MediaType}}` | tipo di media (image/audio/document/…) | -| `{{Transcript}}` | transcript audio | -| `{{Prompt}}` | prompt media risolto per le voci CLI | -| `{{MaxChars}}` | numero massimo di caratteri in output risolto per le voci CLI | -| `{{ChatType}}` | `"direct"` oppure `"group"` | -| `{{GroupSubject}}` | oggetto del gruppo (best effort) | -| `{{GroupMembers}}` | anteprima dei membri del gruppo (best effort) | -| `{{SenderName}}` | nome visualizzato del mittente (best effort) | -| `{{SenderE164}}` | numero di telefono del mittente (best effort) | +| Variabile | Descrizione | +| ------------------ | ----------------------------------------------- | +| `{{Body}}` | Corpo completo del messaggio in ingresso | +| `{{RawBody}}` | Corpo grezzo (senza wrapper di cronologia/mittente) | +| `{{BodyStripped}}` | Corpo con le menzioni di gruppo rimosse | +| `{{From}}` | Identificatore del mittente | +| `{{To}}` | Identificatore della destinazione | +| `{{MessageSid}}` | ID del messaggio del canale | +| `{{SessionId}}` | UUID della sessione corrente | +| `{{IsNewSession}}` | `"true"` quando viene creata una nuova sessione | +| `{{MediaUrl}}` | pseudo-URL del media in ingresso | +| `{{MediaPath}}` | percorso media locale | +| `{{MediaType}}` | tipo di media (image/audio/document/…) | +| `{{Transcript}}` | trascrizione audio | +| `{{Prompt}}` | prompt media risolto per le voci CLI | +| `{{MaxChars}}` | max caratteri di output risolti per le voci CLI | +| `{{ChatType}}` | `"direct"` oppure `"group"` | +| `{{GroupSubject}}` | oggetto del gruppo (best effort) | +| `{{GroupMembers}}` | anteprima dei membri del gruppo (best effort) | +| `{{SenderName}}` | nome visualizzato del mittente (best effort) | +| `{{SenderE164}}` | numero di telefono del mittente (best effort) | | `{{Provider}}` | hint del provider (whatsapp, telegram, discord, ecc.) | --- @@ -3859,13 +3860,13 @@ Suddividi la configurazione in più file: } ``` -**Comportamento del merge:** +**Comportamento di merge:** - File singolo: sostituisce l'oggetto contenitore. -- Array di file: deep merge in ordine (i successivi sovrascrivono i precedenti). -- Chiavi sibling: vengono unite dopo gli include (sovrascrivono i valori inclusi). +- Array di file: deep-merge in ordine (quelli successivi sovrascrivono i precedenti). +- Chiavi sorelle: unite dopo gli include (sovrascrivono i valori inclusi). - Include annidati: fino a 10 livelli di profondità. -- Percorsi: risolti relativamente al file che include, ma devono restare all'interno della directory di configurazione di livello superiore (`dirname` di `openclaw.json`). Le forme assolute/`../` sono consentite solo se si risolvono comunque all'interno di quel confine. +- Percorsi: risolti relativamente al file che include, ma devono restare all'interno della directory di configurazione di primo livello (`dirname` di `openclaw.json`). Le forme assolute/`../` sono consentite solo se si risolvono comunque all'interno di quel confine. - Errori: messaggi chiari per file mancanti, errori di parsing e include circolari. --- diff --git a/docs/it/gateway/doctor.md b/docs/it/gateway/doctor.md index 17ffa3c6e..c9cd7b8ce 100644 --- a/docs/it/gateway/doctor.md +++ b/docs/it/gateway/doctor.md @@ -1,23 +1,21 @@ --- read_when: - - Stai aggiungendo o modificando migrazioni di doctor - - Stai introducendo modifiche incompatibili alla configurazione -summary: 'Comando Doctor: controlli di integrità, migrazioni della configurazione e passaggi di riparazione' + - Aggiunta o modifica delle migrazioni di doctor + - Introduzione di modifiche incompatibili alla configurazione +summary: 'Comando doctor: controlli di integrità, migrazioni della configurazione e passaggi di riparazione' title: Doctor x-i18n: - generated_at: "2026-04-09T01:29:07Z" + generated_at: "2026-04-20T08:30:53Z" model: gpt-5.4 provider: openai - source_hash: 75d321bd1ad0e16c29f2382e249c51edfc3a8d33b55bdceea39e7dbcd4901fce + source_hash: 61a5e01a306058c49be6095f7c8082d779a55d63cf3b5f4c4096173943faf51b source_path: gateway/doctor.md workflow: 15 --- # Doctor -`openclaw doctor` è lo strumento di riparazione + migrazione di OpenClaw. Corregge -configurazioni/stati obsoleti, controlla l'integrità e fornisce passaggi di -riparazione concreti. +`openclaw doctor` è lo strumento di riparazione + migrazione per OpenClaw. Corregge configurazione/stato obsoleti, esegue controlli di integrità e fornisce passaggi di riparazione attuabili. ## Avvio rapido @@ -31,32 +29,32 @@ openclaw doctor openclaw doctor --yes ``` -Accetta le impostazioni predefinite senza richiedere conferma (inclusi i passaggi di ripristino di riavvio/servizio/sandbox quando applicabili). +Accetta i valori predefiniti senza chiedere conferma (inclusi i passaggi di riparazione di riavvio/servizio/sandbox quando applicabili). ```bash openclaw doctor --repair ``` -Applica le riparazioni consigliate senza richiedere conferma (riparazioni + riavvii dove sicuro). +Applica le riparazioni consigliate senza chiedere conferma (riparazioni + riavvii dove sicuro). ```bash openclaw doctor --repair --force ``` -Applica anche riparazioni aggressive (sovrascrive configurazioni del supervisor personalizzate). +Applica anche riparazioni aggressive (sovrascrive configurazioni supervisor personalizzate). ```bash openclaw doctor --non-interactive ``` -Esegue senza richieste e applica solo migrazioni sicure (normalizzazione della configurazione + spostamenti dello stato su disco). Salta le azioni di riavvio/servizio/sandbox che richiedono conferma umana. +Esegue senza richieste e applica solo migrazioni sicure (normalizzazione della configurazione + spostamenti dello stato su disco). Salta azioni di riavvio/servizio/sandbox che richiedono conferma umana. Le migrazioni dello stato legacy vengono eseguite automaticamente quando rilevate. ```bash openclaw doctor --deep ``` -Analizza i servizi di sistema per installazioni gateway aggiuntive (launchd/systemd/schtasks). +Analizza i servizi di sistema per installazioni Gateway aggiuntive (launchd/systemd/schtasks). Se vuoi rivedere le modifiche prima di scrivere, apri prima il file di configurazione: @@ -66,114 +64,99 @@ cat ~/.openclaw/openclaw.json ## Cosa fa (riepilogo) -- Aggiornamento pre-flight facoltativo per installazioni git (solo interattivo). -- Controllo dell'aggiornamento del protocollo UI (ricostruisce la Control UI quando lo schema del protocollo è più recente). +- Aggiornamento pre-flight opzionale per installazioni git (solo interattivo). +- Controllo di aggiornamento del protocollo UI (ricostruisce la Control UI quando lo schema del protocollo è più recente). - Controllo di integrità + richiesta di riavvio. -- Riepilogo dello stato delle Skills (idonee/mancanti/bloccate) e stato dei plugin. +- Riepilogo dello stato di Skills (idonee/mancanti/bloccate) e stato dei plugin. - Normalizzazione della configurazione per valori legacy. -- Migrazione della configurazione Talk dai campi legacy piatti `talk.*` a `talk.provider` + `talk.providers.`. -- Controlli di migrazione del browser per configurazioni legacy dell'estensione Chrome e preparazione di Chrome MCP. -- Avvisi sulle sostituzioni del provider OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). -- Avvisi sull'oscuramento di Codex OAuth (`models.providers.openai-codex`). -- Controllo dei prerequisiti OAuth TLS per i profili OAuth OpenAI Codex. -- Migrazione legacy dello stato su disco (sessioni/dir agente/autenticazione WhatsApp). -- Migrazione legacy della chiave del contratto del manifest del plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). -- Migrazione legacy dell'archivio cron (`jobId`, `schedule.cron`, campi delivery/payload di primo livello, `provider` nel payload, semplici job di fallback webhook `notify: true`). +- Migrazione della configurazione Talk dai campi flat legacy `talk.*` a `talk.provider` + `talk.providers.`. +- Controlli di migrazione del browser per configurazioni legacy dell'estensione Chrome e stato di prontezza di Chrome MCP. +- Avvisi di override del provider OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). +- Avvisi di shadowing OAuth Codex (`models.providers.openai-codex`). +- Controllo dei prerequisiti TLS OAuth per i profili OAuth OpenAI Codex. +- Migrazione dello stato legacy su disco (sessions/agent dir/auth WhatsApp). +- Migrazione della chiave `contracts` del manifesto dei plugin legacy (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). +- Migrazione dell'archivio Cron legacy (`jobId`, `schedule.cron`, campi top-level delivery/payload, `provider` del payload, job fallback Webhook semplici con `notify: true`). - Ispezione dei file di lock della sessione e pulizia dei lock obsoleti. -- Controlli di integrità e permessi dello stato (sessioni, trascrizioni, directory di stato). -- Controlli dei permessi del file di configurazione (chmod 600) quando eseguito in locale. -- Integrità dell'autenticazione del modello: controlla la scadenza OAuth, può aggiornare token in scadenza e segnala stati di cooldown/disabilitazione del profilo auth. +- Controlli di integrità e permessi dello stato (sessions, transcripts, directory dello stato). +- Controlli dei permessi del file di configurazione (`chmod 600`) quando eseguito in locale. +- Integrità dell'autenticazione del modello: controlla la scadenza OAuth, può rinnovare token in scadenza e segnala stati di cooldown/disabilitazione del profilo di autenticazione. - Rilevamento di directory workspace aggiuntive (`~/openclaw`). -- Riparazione dell'immagine sandbox quando la sandbox è abilitata. -- Migrazione di servizi legacy e rilevamento di gateway aggiuntivi. +- Riparazione dell'immagine sandbox quando il sandboxing è abilitato. +- Migrazione dei servizi legacy e rilevamento di Gateway aggiuntivi. - Migrazione dello stato legacy del canale Matrix (in modalità `--fix` / `--repair`). -- Controlli del runtime del gateway (servizio installato ma non in esecuzione; etichetta launchd in cache). -- Avvisi sullo stato dei canali (rilevati dal gateway in esecuzione). -- Audit della configurazione del supervisor (launchd/systemd/schtasks) con riparazione facoltativa. -- Controlli delle best practice del runtime del gateway (Node vs Bun, percorsi dei version manager). -- Diagnostica dei conflitti di porta del gateway (predefinita `18789`). +- Controlli del runtime Gateway (servizio installato ma non in esecuzione; etichetta launchd in cache). +- Avvisi sullo stato dei canali (sondati dal Gateway in esecuzione). +- Audit della configurazione supervisor (launchd/systemd/schtasks) con riparazione opzionale. +- Controlli delle best practice del runtime Gateway (Node vs Bun, percorsi del gestore versioni). +- Diagnostica dei conflitti di porta Gateway (predefinita `18789`). - Avvisi di sicurezza per policy DM aperte. -- Controlli di autenticazione del gateway per la modalità token locale (offre la generazione del token quando non esiste una sorgente token; non sovrascrive configurazioni token SecretRef). -- Controllo di `linger` per systemd su Linux. -- Controllo della dimensione dei file bootstrap del workspace (avvisi per troncamento/quasi limite dei file di contesto). +- Controlli di autenticazione Gateway per la modalità token locale (offre la generazione del token quando non esiste alcuna sorgente di token; non sovrascrive configurazioni token SecretRef). +- Rilevamento dei problemi di associazione dei dispositivi (richieste di prima associazione in sospeso, aggiornamenti di ruolo/ambito in sospeso, deriva della cache locale obsoleta del token del dispositivo e deriva di autenticazione dei record associati). +- Controllo di linger systemd su Linux. +- Controllo della dimensione dei file di bootstrap del workspace (avvisi di troncamento/quasi limite per i file di contesto). - Controllo dello stato del completamento della shell e installazione/aggiornamento automatici. -- Controllo di preparazione del provider di embedding per la ricerca nella memoria (modello locale, chiave API remota o binario QMD). -- Controlli dell'installazione da sorgente (mismatch del workspace pnpm, asset UI mancanti, binario tsx mancante). +- Controllo della prontezza del provider di embedding per la ricerca in memoria (modello locale, chiave API remota o binario QMD). +- Controlli dell'installazione da sorgente (mismatch del workspace pnpm, risorse UI mancanti, binario tsx mancante). - Scrive la configurazione aggiornata + i metadati del wizard. -## Backfill e reset Dreams UI +## Backfill e reset della UI Dreams -La scena Dreams della Control UI include le azioni **Backfill**, **Reset** e **Clear Grounded** -per il flusso di lavoro di grounded dreaming. Queste azioni usano metodi RPC -in stile doctor del gateway, ma **non** fanno parte della riparazione/migrazione -della CLI `openclaw doctor`. +La scena Dreams della Control UI include le azioni **Backfill**, **Reset** e **Clear Grounded** per il flusso di dreaming grounded. Queste azioni usano metodi RPC in stile doctor del Gateway, ma **non** fanno parte della riparazione/migrazione della CLI `openclaw doctor`. Cosa fanno: -- **Backfill** analizza i file storici `memory/YYYY-MM-DD.md` nel workspace - attivo, esegue il passaggio grounded REM diary e scrive voci di backfill - reversibili in `DREAMS.md`. -- **Reset** rimuove da `DREAMS.md` solo le voci del diario di backfill contrassegnate. -- **Clear Grounded** rimuove solo le voci staged grounded-only a breve termine - provenienti dal replay storico e che non hanno ancora accumulato richiamo live - o supporto giornaliero. +- **Backfill** analizza i file storici `memory/YYYY-MM-DD.md` nel workspace attivo, esegue il passaggio grounded REM diary e scrive voci di backfill reversibili in `DREAMS.md`. +- **Reset** rimuove solo quelle voci di diario di backfill contrassegnate da `DREAMS.md`. +- **Clear Grounded** rimuove solo le voci staged grounded-only a breve termine provenienti dal replay storico e che non hanno ancora accumulato richiamo live o supporto giornaliero. Cosa **non** fanno da sole: - non modificano `MEMORY.md` -- non eseguono migrazioni complete di doctor -- non mettono automaticamente in staging i candidati grounded nell'archivio live - di promozione a breve termine, a meno che tu non esegua prima esplicitamente il percorso CLI staged +- non eseguono migrazioni doctor complete +- non mettono automaticamente in staging i candidati grounded nel live short-term promotion store a meno che tu non esegua prima esplicitamente il percorso CLI staged -Se vuoi che il replay storico grounded influenzi il normale percorso di -promozione profonda, usa invece il flusso CLI: +Se vuoi che il replay storico grounded influenzi il normale percorso di deep promotion, usa invece il flusso CLI: ```bash openclaw memory rem-backfill --path ./memory --stage-short-term ``` -Questo mette in staging i candidati durevoli grounded nell'archivio di dreaming a breve termine mantenendo `DREAMS.md` come superficie di revisione. +Questo mette in staging i candidati grounded durevoli nel dreaming store a breve termine mantenendo `DREAMS.md` come superficie di revisione. ## Comportamento dettagliato e motivazione -### 0) Aggiornamento facoltativo (installazioni git) +### 0) Aggiornamento opzionale (installazioni git) -Se si tratta di un checkout git e doctor viene eseguito in modo interattivo, offre di -aggiornare (fetch/rebase/build) prima di eseguire doctor. +Se si tratta di un checkout git e doctor è in esecuzione in modalità interattiva, offre la possibilità di aggiornare (fetch/rebase/build) prima di eseguire doctor. ### 1) Normalizzazione della configurazione -Se la configurazione contiene forme di valori legacy (ad esempio `messages.ackReaction` -senza una sostituzione specifica per canale), doctor le normalizza nello schema attuale. +Se la configurazione contiene forme di valore legacy (per esempio `messages.ackReaction` senza un override specifico per canale), doctor le normalizza nello schema corrente. -Questo include i campi legacy piatti di Talk. La configurazione pubblica attuale di Talk è -`talk.provider` + `talk.providers.`. Doctor riscrive le vecchie forme -`talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / -`talk.apiKey` nella mappa dei provider. +Questo include i campi flat legacy di Talk. La configurazione pubblica corrente di Talk è `talk.provider` + `talk.providers.`. Doctor riscrive le vecchie forme `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` nella mappa provider. ### 2) Migrazioni delle chiavi di configurazione legacy -Quando la configurazione contiene chiavi deprecate, gli altri comandi si rifiutano di essere eseguiti e ti chiedono -di eseguire `openclaw doctor`. +Quando la configurazione contiene chiavi deprecate, gli altri comandi si rifiutano di essere eseguiti e chiedono di eseguire `openclaw doctor`. -Doctor eseguirà queste operazioni: +Doctor eseguirà quanto segue: -- Spiegare quali chiavi legacy sono state trovate. -- Mostrare la migrazione applicata. -- Riscrivere `~/.openclaw/openclaw.json` con lo schema aggiornato. +- Spiegherà quali chiavi legacy sono state trovate. +- Mostrerà la migrazione applicata. +- Riscriverà `~/.openclaw/openclaw.json` con lo schema aggiornato. -Il Gateway esegue automaticamente anche le migrazioni doctor all'avvio quando rileva un -formato di configurazione legacy, quindi le configurazioni obsolete vengono riparate senza intervento manuale. -Le migrazioni dell'archivio dei job cron sono gestite da `openclaw doctor --fix`. +Il Gateway esegue inoltre automaticamente le migrazioni doctor all'avvio quando rileva un formato di configurazione legacy, così le configurazioni obsolete vengono riparate senza intervento manuale. +Le migrazioni dell'archivio dei job Cron sono gestite da `openclaw doctor --fix`. -Migrazioni attuali: +Migrazioni correnti: - `routing.allowFrom` → `channels.whatsapp.allowFrom` - `routing.groupChat.requireMention` → `channels.whatsapp/telegram/imessage.groups."*".requireMention` - `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit` - `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns` - `routing.queue` → `messages.queue` -- `routing.bindings` → `bindings` di primo livello +- `routing.bindings` → top-level `bindings` - `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default` - legacy `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.` - `routing.agentToAgent` → `tools.agentToAgent` @@ -188,7 +171,7 @@ Migrazioni attuali: - `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*` - `bindings[].match.accountID` → `bindings[].match.accountId` -- Per i canali con `accounts` nominati ma con ancora valori di canale di primo livello per account singolo, sposta quei valori con ambito account nell'account promosso scelto per quel canale (`accounts.default` per la maggior parte dei canali; Matrix può preservare un target nominato/predefinito corrispondente esistente) +- Per i canali con `accounts` nominati ma con valori top-level del canale single-account ancora presenti, sposta quei valori con ambito account nell'account promosso scelto per quel canale (`accounts.default` per la maggior parte dei canali; Matrix può preservare un target nominato/predefinito esistente corrispondente) - `identity` → `agents.list[].identity` - `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents) - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` @@ -197,22 +180,19 @@ Migrazioni attuali: - `browser.profiles.*.driver: "extension"` → `"existing-session"` - rimuove `browser.relayBindHost` (impostazione legacy del relay dell'estensione) -Gli avvisi di doctor includono anche indicazioni sul default account per i canali multi-account: +Gli avvisi di doctor includono anche indicazioni sui predefiniti degli account per i canali multi-account: -- Se sono configurate due o più voci `channels..accounts` senza `channels..defaultAccount` o `accounts.default`, doctor avvisa che il routing di fallback può selezionare un account imprevisto. +- Se due o più voci `channels..accounts` sono configurate senza `channels..defaultAccount` o `accounts.default`, doctor avvisa che il routing di fallback può scegliere un account imprevisto. - Se `channels..defaultAccount` è impostato su un ID account sconosciuto, doctor avvisa ed elenca gli ID account configurati. -### 2b) Sostituzioni del provider OpenCode +### 2b) Override del provider OpenCode -Se hai aggiunto manualmente `models.providers.opencode`, `opencode-zen` o `opencode-go`, -questo sostituisce il catalogo OpenCode integrato da `@mariozechner/pi-ai`. -Può forzare i modelli sull'API sbagliata o azzerare i costi. Doctor avvisa in modo che tu -possa rimuovere la sostituzione e ripristinare il routing API + i costi per modello. +Se hai aggiunto manualmente `models.providers.opencode`, `opencode-zen` o `opencode-go`, questo sovrascrive il catalogo OpenCode integrato da `@mariozechner/pi-ai`. +Questo può forzare i modelli sull'API sbagliata o azzerare i costi. Doctor avvisa così puoi rimuovere l'override e ripristinare il routing API per modello + i costi. -### 2c) Migrazione del browser e preparazione di Chrome MCP +### 2c) Migrazione del browser e prontezza di Chrome MCP -Se la tua configurazione del browser punta ancora al percorso rimosso dell'estensione Chrome, doctor -la normalizza nell'attuale modello di collegamento Chrome MCP host-local: +Se la configurazione del browser punta ancora al percorso rimosso dell'estensione Chrome, doctor la normalizza all'attuale modello di collegamento Chrome MCP host-local: - `browser.profiles.*.driver: "extension"` diventa `"existing-session"` - `browser.relayBindHost` viene rimosso @@ -220,157 +200,143 @@ la normalizza nell'attuale modello di collegamento Chrome MCP host-local: Doctor controlla anche il percorso Chrome MCP host-local quando usi `defaultProfile: "user"` o un profilo `existing-session` configurato: -- verifica se Google Chrome è installato sullo stesso host per i profili di - connessione automatica predefiniti -- controlla la versione di Chrome rilevata e avvisa quando è inferiore a Chrome 144 -- ricorda di abilitare il debug remoto nella pagina inspect del browser (ad - esempio `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`, - o `edge://inspect/#remote-debugging`) +- controlla se Google Chrome è installato sullo stesso host per i profili di connessione automatica predefiniti +- controlla la versione rilevata di Chrome e avvisa quando è inferiore a Chrome 144 +- ricorda di abilitare il remote debugging nella pagina inspect del browser (per esempio `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`, o `edge://inspect/#remote-debugging`) -Doctor non può abilitare per te l'impostazione lato Chrome. Chrome MCP host-local -richiede comunque: +Doctor non può abilitare per te l'impostazione lato Chrome. Chrome MCP host-local richiede comunque: - un browser basato su Chromium 144+ sull'host gateway/node - il browser in esecuzione localmente -- il debug remoto abilitato in quel browser -- l'approvazione del primo prompt di consenso al collegamento nel browser +- il remote debugging abilitato in quel browser +- l'approvazione del primo prompt di consenso per il collegamento nel browser -La preparazione qui riguarda solo i prerequisiti per il collegamento locale. Existing-session mantiene -gli attuali limiti di routing di Chrome MCP; percorsi avanzati come `responsebody`, esportazione PDF, -intercettazione dei download e azioni batch richiedono ancora un browser gestito -o un profilo CDP raw. +La prontezza qui riguarda solo i prerequisiti di collegamento locale. Existing-session mantiene gli attuali limiti di instradamento di Chrome MCP; instradamenti avanzati come `responsebody`, esportazione PDF, intercettazione dei download e azioni batch richiedono ancora un browser gestito o un profilo CDP raw. -Questo controllo **non** si applica a Docker, sandbox, remote-browser o altri -flussi headless. Questi continuano a usare raw CDP. +Questo controllo **non** si applica a Docker, sandbox, remote-browser o altri flussi headless. Questi continuano a usare CDP raw. -### 2d) Prerequisiti OAuth TLS +### 2d) Prerequisiti TLS OAuth -Quando è configurato un profilo OAuth OpenAI Codex, doctor verifica l'endpoint di -autorizzazione OpenAI per controllare che lo stack TLS locale Node/OpenSSL possa -validare la catena di certificati. Se la verifica fallisce con un errore di certificato (ad -esempio `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, certificato scaduto o certificato autofirmato), -doctor stampa indicazioni di correzione specifiche per piattaforma. Su macOS con un Node Homebrew, la -correzione è di solito `brew postinstall ca-certificates`. Con `--deep`, la verifica viene eseguita -anche se il gateway è integro. +Quando è configurato un profilo OAuth OpenAI Codex, doctor interroga l'endpoint di autorizzazione OpenAI per verificare che lo stack TLS Node/OpenSSL locale possa validare la catena di certificati. Se la verifica fallisce con un errore di certificato (per esempio `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, certificato scaduto o certificato self-signed), doctor stampa indicazioni di correzione specifiche per piattaforma. Su macOS con un Node Homebrew, la correzione di solito è `brew postinstall ca-certificates`. Con `--deep`, la verifica viene eseguita anche se il Gateway è integro. -### 2c) Sostituzioni del provider Codex OAuth +### 2c) Override del provider OAuth Codex Se in precedenza hai aggiunto impostazioni legacy del trasporto OpenAI sotto -`models.providers.openai-codex`, queste possono oscurare il percorso del -provider Codex OAuth integrato che le versioni più recenti usano automaticamente. Doctor avvisa quando vede -quelle vecchie impostazioni di trasporto insieme a Codex OAuth in modo che tu possa rimuovere o riscrivere -la sostituzione del trasporto obsoleta e recuperare il comportamento integrato di routing/fallback. -I proxy personalizzati e le sostituzioni solo-header sono ancora supportati e non -attivano questo avviso. +`models.providers.openai-codex`, possono oscurare il percorso del provider +OAuth Codex integrato che le versioni più recenti usano automaticamente. Doctor +avvisa quando rileva queste vecchie impostazioni di trasporto insieme a Codex OAuth, +così puoi rimuovere o riscrivere l'override di trasporto obsoleto e ripristinare +il comportamento integrato di routing/fallback. I proxy personalizzati e gli override +solo intestazione sono ancora supportati e non attivano questo avviso. ### 3) Migrazioni dello stato legacy (layout su disco) -Doctor può migrare vecchi layout su disco nella struttura attuale: +Doctor può migrare layout su disco più vecchi nella struttura corrente: -- Archivio sessioni + trascrizioni: +- Archivio delle sessioni + transcript: - da `~/.openclaw/sessions/` a `~/.openclaw/agents//sessions/` -- Directory agente: +- Directory dell'agente: - da `~/.openclaw/agent/` a `~/.openclaw/agents//agent/` -- Stato auth WhatsApp (Baileys): - - da `~/.openclaw/credentials/*.json` legacy (eccetto `oauth.json`) +- Stato di autenticazione WhatsApp (Baileys): + - dal legacy `~/.openclaw/credentials/*.json` (eccetto `oauth.json`) - a `~/.openclaw/credentials/whatsapp//...` (ID account predefinito: `default`) Queste migrazioni sono best-effort e idempotenti; doctor emetterà avvisi quando -lascia eventuali cartelle legacy come backup. Anche Gateway/CLI migrano automaticamente -all'avvio le sessioni legacy + la directory agente, quindi cronologia/auth/modelli finiscono nel -percorso per agente senza eseguire manualmente doctor. L'auth WhatsApp viene intenzionalmente -migrata solo tramite `openclaw doctor`. La normalizzazione di provider/mappa provider di Talk ora -confronta per uguaglianza strutturale, quindi differenze solo nell'ordine delle chiavi non attivano più -modifiche ripetute e inutili di `doctor --fix`. +lascia cartelle legacy come backup. Anche il Gateway/la CLI eseguono automaticamente +la migrazione delle sessioni legacy + della directory dell'agente all'avvio, così cronologia/autenticazione/modelli finiscono nel +percorso per agente senza una esecuzione manuale di doctor. L'autenticazione WhatsApp viene intenzionalmente +migrata solo tramite `openclaw doctor`. La normalizzazione del provider/mappa provider di Talk ora +confronta per uguaglianza strutturale, quindi differenze dovute solo all'ordine delle chiavi non attivano più +modifiche ripetute senza effetto di `doctor --fix`. -### 3a) Migrazioni legacy del manifest dei plugin +### 3a) Migrazioni legacy del manifesto dei plugin -Doctor analizza tutti i manifest dei plugin installati per trovare chiavi di capability -di primo livello deprecate (`speechProviders`, `realtimeTranscriptionProviders`, +Doctor analizza tutti i manifesti dei plugin installati alla ricerca di chiavi di capacità +top-level deprecate (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Quando le trova, propone di spostarle nell'oggetto `contracts` -e di riscrivere il file del manifest sul posto. Questa migrazione è idempotente; +e di riscrivere il file del manifesto in-place. Questa migrazione è idempotente; se la chiave `contracts` contiene già gli stessi valori, la chiave legacy viene rimossa senza duplicare i dati. -### 3b) Migrazioni legacy dell'archivio cron +### 3b) Migrazioni legacy dell'archivio Cron -Doctor controlla anche l'archivio dei job cron (`~/.openclaw/cron/jobs.json` per impostazione predefinita, -o `cron.store` quando sostituito) per trovare forme di job vecchie che lo scheduler accetta ancora -per compatibilità. +Doctor controlla anche l'archivio dei job Cron (`~/.openclaw/cron/jobs.json` per impostazione predefinita, +oppure `cron.store` se sovrascritto) per vecchie forme di job che lo scheduler continua +ad accettare per compatibilità. -Le pulizie cron correnti includono: +Le pulizie Cron correnti includono: - `jobId` → `id` - `schedule.cron` → `schedule.expr` -- campi payload di primo livello (`message`, `model`, `thinking`, ...) → `payload` -- campi delivery di primo livello (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` -- alias delivery `provider` nel payload → `delivery.channel` esplicito -- semplici job legacy di fallback webhook `notify: true` → `delivery.mode="webhook"` esplicito con `delivery.to=cron.webhook` +- campi payload top-level (`message`, `model`, `thinking`, ...) → `payload` +- campi delivery top-level (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` +- alias di delivery `provider` del payload → `delivery.channel` esplicito +- semplici job fallback Webhook legacy `notify: true` → `delivery.mode="webhook"` esplicito con `delivery.to=cron.webhook` Doctor migra automaticamente i job `notify: true` solo quando può farlo senza -cambiare comportamento. Se un job combina il fallback legacy di notify con una modalità -delivery non-webhook esistente, doctor avvisa e lascia quel job per una revisione manuale. +cambiare il comportamento. Se un job combina il fallback notify legacy con una modalità +di delivery non webhook già esistente, doctor avvisa e lascia quel job alla revisione manuale. ### 3c) Pulizia dei lock di sessione -Doctor analizza ogni directory di sessione dell'agente per trovare file di lock di scrittura obsoleti — file lasciati -indietro quando una sessione è terminata in modo anomalo. Per ogni file di lock trovato segnala: +Doctor analizza ogni directory di sessione dell'agente alla ricerca di file di lock di scrittura obsoleti — +file lasciati indietro quando una sessione è terminata in modo anomalo. Per ogni file di lock trovato riporta: il percorso, il PID, se il PID è ancora attivo, l'età del lock e se è considerato obsoleto (PID morto o più vecchio di 30 minuti). In modalità `--fix` / `--repair` rimuove automaticamente i file di lock obsoleti; altrimenti stampa una nota e -ti dice di rieseguire con `--fix`. +ti istruisce a eseguire di nuovo con `--fix`. ### 4) Controlli di integrità dello stato (persistenza della sessione, routing e sicurezza) -La directory di stato è il tronco encefalico operativo. Se scompare, perdi +La directory dello stato è il tronco encefalico operativo. Se scompare, perdi sessioni, credenziali, log e configurazione (a meno che tu non abbia backup altrove). Doctor controlla: -- **Directory di stato mancante**: avvisa della perdita catastrofica dello stato, chiede di ricreare +- **Directory dello stato mancante**: avvisa di una perdita catastrofica dello stato, chiede di ricreare la directory e ricorda che non può recuperare i dati mancanti. -- **Permessi della directory di stato**: verifica la scrivibilità; offre di riparare i permessi - (ed emette un suggerimento `chown` quando rileva una mancata corrispondenza tra proprietario/gruppo). -- **Directory di stato macOS sincronizzata con il cloud**: avvisa quando lo stato si risolve sotto iCloud Drive +- **Permessi della directory dello stato**: verifica la scrivibilità; offre di riparare i permessi + (ed emette un suggerimento `chown` quando viene rilevata una discrepanza di proprietario/gruppo). +- **Directory dello stato sincronizzata nel cloud su macOS**: avvisa quando lo stato si risolve sotto iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) o - `~/Library/CloudStorage/...` perché i percorsi supportati dalla sincronizzazione possono causare I/O più lenti + `~/Library/CloudStorage/...` perché i percorsi supportati dalla sincronizzazione possono causare I/O più lento e race di lock/sincronizzazione. -- **Directory di stato Linux su SD o eMMC**: avvisa quando lo stato si risolve in una sorgente di mount `mmcblk*`, - perché l'I/O casuale supportato da SD o eMMC può essere più lento e usurarsi più - rapidamente con scritture di sessione e credenziali. -- **Directory di sessione mancanti**: `sessions/` e la directory dell'archivio sessioni sono +- **Directory dello stato su SD o eMMC su Linux**: avvisa quando lo stato si risolve su una sorgente di mount `mmcblk*`, + perché l'I/O casuale supportato da SD o eMMC può essere più lento e usurarsi + più velocemente con le scritture di sessioni e credenziali. +- **Directory delle sessioni mancanti**: `sessions/` e la directory dell'archivio delle sessioni sono necessarie per mantenere la cronologia ed evitare crash `ENOENT`. -- **Mismatch della trascrizione**: avvisa quando voci di sessione recenti hanno file di - trascrizione mancanti. -- **Sessione principale “JSONL a 1 riga”**: segnala quando la trascrizione principale ha una sola +- **Mancata corrispondenza dei transcript**: avvisa quando voci di sessione recenti hanno + file transcript mancanti. +- **Sessione principale “JSONL a 1 riga”**: segnala quando il transcript principale ha una sola riga (la cronologia non si sta accumulando). -- **Più directory di stato**: avvisa quando esistono più cartelle `~/.openclaw` in diverse - home directory o quando `OPENCLAW_STATE_DIR` punta altrove (la cronologia può +- **Più directory dello stato**: avvisa quando esistono più cartelle `~/.openclaw` in + directory home diverse o quando `OPENCLAW_STATE_DIR` punta altrove (la cronologia può dividersi tra installazioni). - **Promemoria modalità remota**: se `gateway.mode=remote`, doctor ricorda di eseguirlo sull'host remoto (lo stato si trova lì). - **Permessi del file di configurazione**: avvisa se `~/.openclaw/openclaw.json` è - leggibile da gruppo/altri e offre di restringerlo a `600`. + leggibile da gruppo/altri e offre di restringerli a `600`. -### 5) Integrità auth del modello (scadenza OAuth) +### 5) Integrità dell'autenticazione del modello (scadenza OAuth) -Doctor ispeziona i profili OAuth nell'archivio auth, avvisa quando i token -stanno per scadere o sono scaduti e può aggiornarli quando è sicuro. Se il profilo -OAuth/token Anthropic è obsoleto, suggerisce una chiave API Anthropic o il -percorso setup-token Anthropic. -Le richieste di refresh compaiono solo in esecuzione interattiva (TTY); `--non-interactive` -salta i tentativi di refresh. +Doctor ispeziona i profili OAuth nell'archivio auth, avvisa quando i token stanno +per scadere/sono scaduti e può aggiornarli quando è sicuro. Se il +profilo OAuth/token Anthropic è obsoleto, suggerisce una chiave API Anthropic o il +percorso del setup-token Anthropic. +Le richieste di aggiornamento compaiono solo in esecuzione interattiva (TTY); `--non-interactive` +salta i tentativi di aggiornamento. -Quando un refresh OAuth fallisce in modo permanente (ad esempio `refresh_token_reused`, +Quando un aggiornamento OAuth fallisce in modo permanente (per esempio `refresh_token_reused`, `invalid_grant`, o un provider che ti dice di accedere di nuovo), doctor segnala -che è richiesta una nuova autenticazione e stampa il comando esatto `openclaw models auth login --provider ...` +che è necessaria una nuova autenticazione e stampa l'esatto comando `openclaw models auth login --provider ...` da eseguire. Doctor segnala anche i profili auth temporaneamente inutilizzabili a causa di: -- brevi cooldown (limiti di frequenza/timeout/errori auth) +- cooldown brevi (rate limit/timeout/errori di autenticazione) - disabilitazioni più lunghe (errori di fatturazione/credito) ### 6) Validazione del modello Hooks @@ -380,170 +346,198 @@ catalogo e alla allowlist e avvisa quando non verrà risolto o non è consentito ### 7) Riparazione dell'immagine sandbox -Quando la sandbox è abilitata, doctor controlla le immagini Docker e offre di compilare o -passare a nomi legacy se l'immagine attuale manca. +Quando il sandboxing è abilitato, doctor controlla le immagini Docker e offre di compilare o +passare a nomi legacy se l'immagine corrente è mancante. -### 7b) Dipendenze runtime dei plugin integrati +### 7b) Dipendenze runtime dei plugin inclusi -Doctor verifica che le dipendenze runtime dei plugin integrati (ad esempio i +Doctor verifica che le dipendenze runtime dei plugin inclusi (per esempio i pacchetti runtime del plugin Discord) siano presenti nella root di installazione di OpenClaw. -Se ne manca qualcuna, doctor segnala i pacchetti e li installa in modalità -`openclaw doctor --fix` / `openclaw doctor --repair`. +Se ne manca qualcuna, doctor segnala i pacchetti e li installa in +modalità `openclaw doctor --fix` / `openclaw doctor --repair`. -### 8) Migrazioni del servizio gateway e suggerimenti di pulizia +### 8) Migrazioni del servizio Gateway e suggerimenti di pulizia -Doctor rileva i servizi gateway legacy (launchd/systemd/schtasks) e -offre di rimuoverli e installare il servizio OpenClaw usando la porta gateway attuale. -Può anche cercare servizi aggiuntivi simili a gateway e stampare suggerimenti di pulizia. -I servizi gateway OpenClaw con nome del profilo sono considerati di prima classe e non vengono -contrassegnati come "aggiuntivi". +Doctor rileva servizi Gateway legacy (launchd/systemd/schtasks) e +offre di rimuoverli e installare il servizio OpenClaw usando l'attuale porta del Gateway. +Può anche cercare servizi aggiuntivi simili a Gateway e stampare suggerimenti di pulizia. +I servizi Gateway OpenClaw con nome profilo sono considerati di prima classe e non vengono +segnalati come "aggiuntivi". ### 8b) Migrazione Matrix all'avvio -Quando un account del canale Matrix ha una migrazione dello stato legacy in sospeso o applicabile, +Quando un account del canale Matrix ha una migrazione dello stato legacy in sospeso o attuabile, doctor (in modalità `--fix` / `--repair`) crea uno snapshot pre-migrazione e poi esegue i passaggi di migrazione best-effort: migrazione dello stato Matrix legacy e preparazione -legacy dello stato cifrato. Entrambi i passaggi non sono fatali; gli errori vengono registrati e -l'avvio continua. In modalità sola lettura (`openclaw doctor` senza `--fix`) questo controllo +dello stato cifrato legacy. Entrambi i passaggi non sono fatali; gli errori vengono registrati e +l'avvio continua. In modalità di sola lettura (`openclaw doctor` senza `--fix`) questo controllo viene saltato completamente. +### 8c) Associazione del dispositivo e deriva dell'autenticazione + +Doctor ora ispeziona lo stato di associazione del dispositivo come parte del normale controllo di integrità. + +Cosa riporta: + +- richieste di prima associazione in sospeso +- aggiornamenti di ruolo in sospeso per dispositivi già associati +- aggiornamenti di ambito in sospeso per dispositivi già associati +- riparazioni di mancata corrispondenza della chiave pubblica dove l'ID dispositivo corrisponde ancora ma + l'identità del dispositivo non corrisponde più al record approvato +- record associati senza un token attivo per un ruolo approvato +- token associati i cui ambiti divergono dalla baseline di associazione approvata +- voci della cache locale del token del dispositivo per la macchina corrente che precedono una + rotazione del token lato gateway o che riportano metadati di ambito obsoleti + +Doctor non approva automaticamente richieste di associazione né ruota automaticamente i token del dispositivo. Invece +stampa i passaggi successivi esatti: + +- ispeziona le richieste in sospeso con `openclaw devices list` +- approva la richiesta esatta con `openclaw devices approve ` +- ruota un nuovo token con `openclaw devices rotate --device --role ` +- rimuovi e riapprova un record obsoleto con `openclaw devices remove ` + +Questo chiude il comune problema "già associato ma ricevo ancora pairing required": +doctor ora distingue la prima associazione dagli aggiornamenti di ruolo/ambito in sospeso +e dalla deriva obsoleta del token/dell'identità del dispositivo. + ### 9) Avvisi di sicurezza -Doctor emette avvisi quando un provider è aperto ai DM senza una allowlist, o +Doctor emette avvisi quando un provider è aperto ai DM senza una allowlist, oppure quando una policy è configurata in modo pericoloso. ### 10) systemd linger (Linux) -Se è in esecuzione come servizio utente systemd, doctor assicura che lingering sia abilitato in modo che il -gateway resti attivo dopo il logout. +Se è in esecuzione come servizio utente systemd, doctor garantisce che lingering sia abilitato affinché il +Gateway resti attivo dopo il logout. ### 11) Stato del workspace (Skills, plugin e directory legacy) Doctor stampa un riepilogo dello stato del workspace per l'agente predefinito: -- **Stato delle Skills**: conta le Skills idonee, con requisiti mancanti e bloccate dalla allowlist. +- **Stato di Skills**: conta le Skills idonee, con requisiti mancanti e bloccate dalla allowlist. - **Directory workspace legacy**: avvisa quando `~/openclaw` o altre directory workspace legacy - esistono accanto al workspace attuale. + esistono insieme al workspace corrente. - **Stato dei plugin**: conta i plugin caricati/disabilitati/in errore; elenca gli ID plugin per eventuali - errori; segnala le capability dei plugin bundle. + errori; riporta le capacità dei plugin bundle. - **Avvisi di compatibilità dei plugin**: segnala i plugin che hanno problemi di compatibilità con - il runtime attuale. + il runtime corrente. - **Diagnostica dei plugin**: mostra eventuali avvisi o errori di caricamento emessi dal - registro plugin. + registro dei plugin. -### 11b) Dimensione del file bootstrap +### 11b) Dimensione del file di bootstrap -Doctor controlla se i file bootstrap del workspace (ad esempio `AGENTS.md`, -`CLAUDE.md` o altri file di contesto iniettati) sono vicini o oltre il budget -di caratteri configurato. Riporta per file il numero di caratteri raw rispetto a quelli iniettati, la percentuale -di troncamento, la causa del troncamento (`max/file` o `max/total`) e il totale dei caratteri -iniettati come frazione del budget totale. Quando i file sono troncati o vicini +Doctor controlla se i file bootstrap del workspace (per esempio `AGENTS.md`, +`CLAUDE.md` o altri file di contesto iniettati) sono vicini o oltre il budget di +caratteri configurato. Riporta per file il numero di caratteri grezzi rispetto a quelli iniettati, la percentuale di +troncamento, la causa del troncamento (`max/file` o `max/total`) e il totale dei caratteri +iniettati come frazione del budget totale. Quando i file vengono troncati o sono vicini al limite, doctor stampa suggerimenti per regolare `agents.defaults.bootstrapMaxChars` e `agents.defaults.bootstrapTotalMaxChars`. ### 11c) Completamento della shell -Doctor controlla se il completamento tramite tab è installato per la shell attuale +Doctor controlla se il completamento con tabulazione è installato per la shell corrente (zsh, bash, fish o PowerShell): - Se il profilo della shell usa un pattern di completamento dinamico lento (`source <(openclaw completion ...)`), doctor lo aggiorna alla variante più veloce con file in cache. -- Se il completamento è configurato nel profilo ma il file cache manca, +- Se il completamento è configurato nel profilo ma il file di cache manca, doctor rigenera automaticamente la cache. - Se non è configurato alcun completamento, doctor propone di installarlo (solo modalità interattiva; saltato con `--non-interactive`). Esegui `openclaw completion --write-state` per rigenerare manualmente la cache. -### 12) Controlli auth del gateway (token locale) +### 12) Controlli di autenticazione Gateway (token locale) -Doctor controlla la preparazione dell'autenticazione token del gateway locale. +Doctor controlla lo stato di prontezza dell'autenticazione del token Gateway locale. -- Se la modalità token richiede un token e non esiste alcuna sorgente token, doctor propone di generarne uno. +- Se la modalità token richiede un token e non esiste alcuna sorgente di token, doctor offre di generarne uno. - Se `gateway.auth.token` è gestito da SecretRef ma non disponibile, doctor avvisa e non lo sovrascrive con testo in chiaro. - `openclaw doctor --generate-gateway-token` forza la generazione solo quando non è configurato alcun token SecretRef. ### 12b) Riparazioni in sola lettura consapevoli di SecretRef -Alcuni flussi di riparazione devono ispezionare le credenziali configurate senza indebolire il comportamento runtime fail-fast. +Alcuni flussi di riparazione devono ispezionare le credenziali configurate senza indebolire il comportamento fail-fast del runtime. -- `openclaw doctor --fix` ora usa lo stesso modello riassuntivo SecretRef in sola lettura dei comandi della famiglia status per riparazioni di configurazione mirate. -- Esempio: la riparazione Telegram `allowFrom` / `groupAllowFrom` con `@username` prova a usare le credenziali del bot configurate quando disponibili. -- Se il token del bot Telegram è configurato tramite SecretRef ma non disponibile nel percorso del comando corrente, doctor segnala che la credenziale è configurata-ma-non-disponibile e salta la risoluzione automatica invece di andare in crash o segnalare erroneamente che il token manca. +- `openclaw doctor --fix` ora usa lo stesso modello di riepilogo SecretRef in sola lettura dei comandi della famiglia status per riparazioni mirate della configurazione. +- Esempio: la riparazione di Telegram `allowFrom` / `groupAllowFrom` `@username` prova a usare le credenziali del bot configurate quando disponibili. +- Se il token del bot Telegram è configurato tramite SecretRef ma non è disponibile nel percorso del comando corrente, doctor segnala che la credenziale è configurata ma non disponibile e salta la risoluzione automatica invece di andare in crash o segnalare erroneamente il token come mancante. -### 13) Controllo di integrità del gateway + riavvio +### 13) Controllo di integrità Gateway + riavvio -Doctor esegue un controllo di integrità e offre di riavviare il gateway quando +Doctor esegue un controllo di integrità e propone di riavviare il Gateway quando sembra non integro. -### 13b) Preparazione della ricerca nella memoria +### 13b) Prontezza della ricerca in memoria -Doctor controlla se il provider di embedding configurato per la ricerca nella memoria è pronto +Doctor controlla se il provider di embedding configurato per la ricerca in memoria è pronto per l'agente predefinito. Il comportamento dipende dal backend e dal provider configurati: - **Backend QMD**: verifica se il binario `qmd` è disponibile e avviabile. - In caso contrario, stampa indicazioni di correzione incluse il pacchetto npm e un'opzione manuale per il percorso del binario. -- **Provider locale esplicito**: controlla la presenza di un file modello locale o di un URL modello remoto/scaricabile riconosciuto. Se manca, suggerisce di passare a un provider remoto. + In caso contrario, stampa indicazioni per la correzione, incluso il pacchetto npm e un'opzione manuale per il percorso del binario. +- **Provider locale esplicito**: controlla la presenza di un file di modello locale o di un URL di modello remoto/scaricabile riconosciuto. Se manca, suggerisce di passare a un provider remoto. - **Provider remoto esplicito** (`openai`, `voyage`, ecc.): verifica che una chiave API sia - presente nell'ambiente o nell'archivio auth. Stampa suggerimenti di correzione concreti se manca. -- **Provider automatico**: controlla prima la disponibilità del modello locale, poi prova ciascun provider remoto + presente nell'ambiente o nell'archivio auth. Se manca, stampa suggerimenti di correzione attuabili. +- **Provider automatico**: controlla prima la disponibilità del modello locale, poi prova ogni provider remoto nell'ordine di selezione automatica. -Quando è disponibile un risultato della verifica del gateway (il gateway era integro al momento del -controllo), doctor lo confronta con la configurazione visibile dalla CLI e annota +Quando è disponibile il risultato di una verifica del Gateway (il Gateway era integro al momento del +controllo), doctor confronta il suo risultato con la configurazione visibile dalla CLI e segnala qualsiasi discrepanza. -Usa `openclaw memory status --deep` per verificare la preparazione dell'embedding a runtime. +Usa `openclaw memory status --deep` per verificare la prontezza degli embedding a runtime. ### 14) Avvisi sullo stato dei canali -Se il gateway è integro, doctor esegue una verifica dello stato dei canali e segnala -avvisi con le correzioni suggerite. +Se il Gateway è integro, doctor esegue una verifica dello stato dei canali e riporta +avvisi con correzioni suggerite. -### 15) Audit + riparazione della configurazione del supervisor +### 15) Audit + riparazione della configurazione supervisor -Doctor controlla la configurazione del supervisor installata (launchd/systemd/schtasks) per -individuare valori predefiniti mancanti o obsoleti (ad esempio dipendenze systemd network-online e -ritardo di riavvio). Quando trova una mancata corrispondenza, consiglia un aggiornamento e può -riscrivere il file di servizio/task con i valori predefiniti attuali. +Doctor controlla la configurazione supervisor installata (launchd/systemd/schtasks) per +valori predefiniti mancanti o obsoleti (ad esempio dipendenze systemd `network-online` e +ritardo di riavvio). Quando trova una discrepanza, consiglia un aggiornamento e può +riscrivere il file del servizio/task ai valori predefiniti correnti. Note: -- `openclaw doctor` richiede conferma prima di riscrivere la configurazione del supervisor. +- `openclaw doctor` chiede conferma prima di riscrivere la configurazione supervisor. - `openclaw doctor --yes` accetta le richieste di riparazione predefinite. - `openclaw doctor --repair` applica le correzioni consigliate senza richieste. -- `openclaw doctor --repair --force` sovrascrive configurazioni del supervisor personalizzate. -- Se l'autenticazione token richiede un token e `gateway.auth.token` è gestito da SecretRef, doctor durante installazione/riparazione del servizio valida il SecretRef ma non rende persistenti i valori del token risolti in chiaro nei metadati dell'ambiente del servizio supervisor. -- Se l'autenticazione token richiede un token e il token SecretRef configurato non è risolto, doctor blocca il percorso di installazione/riparazione con indicazioni concrete. -- Se sia `gateway.auth.token` sia `gateway.auth.password` sono configurati e `gateway.auth.mode` non è impostato, doctor blocca installazione/riparazione finché la modalità non viene impostata esplicitamente. +- `openclaw doctor --repair --force` sovrascrive le configurazioni supervisor personalizzate. +- Se l'autenticazione token richiede un token e `gateway.auth.token` è gestito da SecretRef, l'installazione/riparazione del servizio doctor convalida il SecretRef ma non rende persistenti i valori del token in chiaro risolti nei metadati dell'ambiente del servizio supervisor. +- Se l'autenticazione token richiede un token e il token SecretRef configurato non è risolto, doctor blocca il percorso di installazione/riparazione con indicazioni attuabili. +- Se sono configurati sia `gateway.auth.token` sia `gateway.auth.password` e `gateway.auth.mode` non è impostato, doctor blocca l'installazione/riparazione finché la modalità non viene impostata esplicitamente. - Per le unità user-systemd Linux, i controlli di deriva del token di doctor ora includono sia le sorgenti `Environment=` sia `EnvironmentFile=` quando confrontano i metadati auth del servizio. - Puoi sempre forzare una riscrittura completa tramite `openclaw gateway install --force`. -### 16) Diagnostica del runtime gateway + della porta +### 16) Runtime Gateway + diagnostica della porta Doctor ispeziona il runtime del servizio (PID, ultimo stato di uscita) e avvisa quando il -servizio è installato ma non è realmente in esecuzione. Controlla anche i conflitti -sulla porta gateway (predefinita `18789`) e riporta le cause probabili (gateway già +servizio è installato ma non è effettivamente in esecuzione. Controlla anche eventuali conflitti +di porta sulla porta del Gateway (predefinita `18789`) e riporta le cause probabili (Gateway già in esecuzione, tunnel SSH). -### 17) Best practice del runtime gateway +### 17) Best practice del runtime Gateway -Doctor avvisa quando il servizio gateway viene eseguito su Bun o su un percorso Node gestito da version manager +Doctor avvisa quando il servizio Gateway viene eseguito su Bun o su un percorso Node gestito da un gestore di versioni (`nvm`, `fnm`, `volta`, `asdf`, ecc.). I canali WhatsApp + Telegram richiedono Node, -e i percorsi dei version manager possono interrompersi dopo gli aggiornamenti perché il servizio non -carica l'inizializzazione della tua shell. Doctor propone di migrare a un'installazione Node di sistema quando +e i percorsi dei gestori di versioni possono rompersi dopo gli aggiornamenti perché il servizio non +carica l'inizializzazione della shell. Doctor propone di migrare a un'installazione Node di sistema quando disponibile (Homebrew/apt/choco). -### 18) Scrittura della configurazione + metadati wizard +### 18) Scrittura della configurazione + metadati del wizard -Doctor rende persistenti eventuali modifiche alla configurazione e appone i metadati wizard per registrare +Doctor rende persistenti eventuali modifiche alla configurazione e registra i metadati del wizard per annotare l'esecuzione di doctor. ### 19) Suggerimenti per il workspace (backup + sistema di memoria) -Doctor suggerisce un sistema di memoria del workspace quando manca e stampa un suggerimento sul backup +Doctor suggerisce un sistema di memoria del workspace quando manca e stampa un suggerimento per il backup se il workspace non è già sotto git. Vedi [/concepts/agent-workspace](/it/concepts/agent-workspace) per una guida completa alla -struttura del workspace e al backup git (consigliati GitHub o GitLab privati). +struttura del workspace e al backup git (GitHub o GitLab privato consigliati). diff --git a/docs/it/gateway/index.md b/docs/it/gateway/index.md index 7fad1a944..73a374da2 100644 --- a/docs/it/gateway/index.md +++ b/docs/it/gateway/index.md @@ -1,24 +1,24 @@ --- read_when: - - Esecuzione o debug del processo gateway + - Eseguire o eseguire il debug del processo Gateway summary: Runbook per il servizio Gateway, il ciclo di vita e le operazioni title: Runbook del Gateway x-i18n: - generated_at: "2026-04-07T08:13:17Z" + generated_at: "2026-04-20T08:30:50Z" model: gpt-5.4 provider: openai - source_hash: fd2c21036e88612861ef2195b8ff7205aca31386bb11558614ade8d1a54fdebd + source_hash: e1004cdd43b1db6794f3ca83da38dbdb231a1976329d9d6d851e2b02405278d8 source_path: gateway/index.md workflow: 15 --- -# Runbook del gateway +# Runbook del Gateway -Usa questa pagina per l'avvio del servizio Gateway il primo giorno e per le operazioni dal secondo giorno in poi. +Usa questa pagina per l'avvio del primo giorno e le operazioni del secondo giorno del servizio Gateway. - Diagnostica orientata ai sintomi con sequenze di comandi esatte e firme nei log. + Diagnostica orientata ai sintomi con sequenze di comandi esatte e firme dei log. Guida di configurazione orientata alle attività + riferimento completo della configurazione. @@ -27,7 +27,7 @@ Usa questa pagina per l'avvio del servizio Gateway il primo giorno e per le oper Contratto SecretRef, comportamento degli snapshot a runtime e operazioni di migrazione/ricarica. - Regole esatte per target/path di `secrets apply` e comportamento dei profili di autenticazione solo-ref. + Regole esatte di target/percorso per `secrets apply` e comportamento dei profili auth solo-ref. @@ -40,13 +40,13 @@ Usa questa pagina per l'avvio del servizio Gateway il primo giorno e per le oper openclaw gateway --port 18789 # debug/trace rispecchiati su stdio openclaw gateway --port 18789 --verbose -# termina forzatamente il listener sulla porta selezionata, quindi avvia +# forza la terminazione del listener sulla porta selezionata, poi avvia openclaw gateway --force ``` - + ```bash openclaw gateway status @@ -54,7 +54,7 @@ openclaw status openclaw logs --follow ``` -Baseline di stato corretto: `Runtime: running` e `RPC probe: ok`. +Riferimento di stato corretto: `Runtime: running`, `Connectivity probe: ok` e `Capability: ...` corrispondente a ciò che ti aspetti. Usa `openclaw gateway status --require-rpc` quando ti serve una prova RPC con ambito di lettura, non solo la raggiungibilità. @@ -64,31 +64,31 @@ Baseline di stato corretto: `Runtime: running` e `RPC probe: ok`. openclaw channels status --probe ``` -Con un gateway raggiungibile, questo esegue probe live per account dei canali e audit opzionali. -Se il gateway non è raggiungibile, la CLI torna a riepiloghi dei canali basati solo sulla configurazione invece -dell'output dei probe live. +Con un gateway raggiungibile questo esegue probe live dei canali per account e audit facoltativi. +Se il gateway non è raggiungibile, la CLI torna a riepiloghi dei canali basati solo sulla configurazione +invece dell'output dei probe live. -La ricarica della configurazione del Gateway osserva il percorso del file di configurazione attivo (risolto dai valori predefiniti del profilo/dello stato, oppure da `OPENCLAW_CONFIG_PATH` se impostato). +La ricarica della configurazione del Gateway osserva il percorso del file di configurazione attivo (risolto dai valori predefiniti di profilo/stato, o da `OPENCLAW_CONFIG_PATH` se impostato). La modalità predefinita è `gateway.reload.mode="hybrid"`. -Dopo il primo caricamento riuscito, il processo in esecuzione serve lo snapshot di configurazione attivo in memoria; una ricarica riuscita sostituisce atomicamente quello snapshot. +Dopo il primo caricamento riuscito, il processo in esecuzione serve lo snapshot della configurazione attiva in memoria; una ricarica riuscita sostituisce quello snapshot in modo atomico. ## Modello di runtime -- Un unico processo sempre attivo per routing, control plane e connessioni dei canali. +- Un processo sempre attivo per routing, control plane e connessioni dei canali. - Una singola porta multiplexata per: - - control/RPC WebSocket + - WebSocket control/RPC - API HTTP, compatibili con OpenAI (`/v1/models`, `/v1/embeddings`, `/v1/chat/completions`, `/v1/responses`, `/tools/invoke`) - - Control UI e hook + - UI di controllo e hook - Modalità di bind predefinita: `loopback`. -- L'autenticazione è richiesta per impostazione predefinita. Le configurazioni con segreto condiviso usano +- L'auth è richiesta per impostazione predefinita. Le configurazioni con segreto condiviso usano `gateway.auth.token` / `gateway.auth.password` (oppure - `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`), e le configurazioni con reverse proxy - non-loopback possono usare `gateway.auth.mode: "trusted-proxy"`. + `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`), e le configurazioni non-loopback + con reverse proxy possono usare `gateway.auth.mode: "trusted-proxy"`. ## Endpoint compatibili con OpenAI @@ -102,7 +102,7 @@ La superficie di compatibilità a più alto impatto di OpenClaw ora è: Perché questo insieme è importante: -- La maggior parte delle integrazioni con Open WebUI, LobeChat e LibreChat esegue prima probe su `/v1/models`. +- La maggior parte delle integrazioni Open WebUI, LobeChat e LibreChat interroga prima `/v1/models`. - Molte pipeline RAG e di memoria si aspettano `/v1/embeddings`. - I client nativi per agenti preferiscono sempre più spesso `/v1/responses`. @@ -110,27 +110,27 @@ Nota di pianificazione: - `/v1/models` è agent-first: restituisce `openclaw`, `openclaw/default` e `openclaw/`. - `openclaw/default` è l'alias stabile che mappa sempre all'agente predefinito configurato. -- Usa `x-openclaw-model` quando vuoi un override del provider/modello di backend; altrimenti il normale modello e la configurazione degli embedding dell'agente selezionato restano in controllo. +- Usa `x-openclaw-model` quando vuoi una sostituzione del provider/modello backend; altrimenti il normale modello e la configurazione degli embedding dell'agente selezionato restano in controllo. -Tutti questi endpoint vengono eseguiti sulla porta principale del Gateway e usano lo stesso confine di autenticazione dell'operatore attendibile del resto dell'API HTTP del Gateway. +Tutti questi endpoint vengono eseguiti sulla porta principale del Gateway e usano lo stesso confine di auth per operatore fidato del resto dell'API HTTP del Gateway. ### Precedenza di porta e bind -| Impostazione | Ordine di risoluzione | -| ---------------- | ------------------------------------------------------------- | -| Porta del Gateway | `--port` → `OPENCLAW_GATEWAY_PORT` → `gateway.port` → `18789` | -| Modalità bind | CLI/override → `gateway.bind` → `loopback` | +| Impostazione | Ordine di risoluzione | +| ------------ | ------------------------------------------------------------- | +| Porta Gateway | `--port` → `OPENCLAW_GATEWAY_PORT` → `gateway.port` → `18789` | +| Modalità bind | CLI/override → `gateway.bind` → `loopback` | ### Modalità di hot reload -| `gateway.reload.mode` | Comportamento | -| --------------------- | ------------------------------------------ | -| `off` | Nessuna ricarica della configurazione | -| `hot` | Applica solo modifiche sicure a caldo | -| `restart` | Riavvia quando le modifiche richiedono reload | -| `hybrid` (predefinita) | Applica a caldo quando sicuro, riavvia quando richiesto | +| `gateway.reload.mode` | Comportamento | +| --------------------- | ----------------------------------------- | +| `off` | Nessuna ricarica della configurazione | +| `hot` | Applica solo modifiche sicure a caldo | +| `restart` | Riavvia per modifiche che richiedono reload | +| `hybrid` (predefinito) | Applica a caldo quando sicuro, riavvia quando richiesto | -## Set di comandi per operatori +## Set di comandi per operatore ```bash openclaw gateway status @@ -144,14 +144,14 @@ openclaw logs --follow openclaw doctor ``` -`gateway status --deep` serve per discovery aggiuntiva dei servizi (unità di sistema LaunchDaemons/systemd/schtasks), non per un probe RPC di stato più approfondito. +`gateway status --deep` serve per il rilevamento aggiuntivo dei servizi (unità di sistema LaunchDaemons/systemd/schtasks), non per un probe di salute RPC più approfondito. -## Più gateway (stesso host) +## Gateway multipli (stesso host) La maggior parte delle installazioni dovrebbe eseguire un gateway per macchina. Un singolo gateway può ospitare più agenti e canali. -Ti servono più gateway solo quando vuoi intenzionalmente isolamento oppure un bot di emergenza. +Hai bisogno di più gateway solo quando vuoi intenzionalmente isolamento o un bot di emergenza. Controlli utili: @@ -163,9 +163,10 @@ openclaw gateway probe Cosa aspettarsi: - `gateway status --deep` può segnalare `Other gateway-like services detected (best effort)` - e stampare suggerimenti di pulizia quando sono ancora presenti installazioni stale di launchd/systemd/schtasks. -- `gateway probe` può avvisare con `multiple reachable gateways` quando risponde più di una destinazione. -- Se ciò è intenzionale, isola porte, config/stato e root del workspace per ciascun gateway. + e stampare suggerimenti di pulizia quando sono ancora presenti installazioni launchd/systemd/schtasks obsolete. +- `gateway probe` può avvisare con `multiple reachable gateways` quando più di un target + risponde. +- Se è intenzionale, isola porte, configurazione/stato e radici del workspace per ciascun gateway. Configurazione dettagliata: [/gateway/multiple-gateways](/it/gateway/multiple-gateways). @@ -181,16 +182,16 @@ ssh -N -L 18789:127.0.0.1:18789 user@host Poi collega i client localmente a `ws://127.0.0.1:18789`. -I tunnel SSH non aggirano l'autenticazione del gateway. Per l'autenticazione con segreto condiviso, i client devono comunque -inviare `token`/`password` anche attraverso il tunnel. Per le modalità con identità incorporata, -la richiesta deve comunque soddisfare quel percorso di autenticazione. +I tunnel SSH non aggirano l'auth del gateway. Per l'auth con segreto condiviso, i client +devono comunque inviare `token`/`password` anche attraverso il tunnel. Per le modalità +con identità, la richiesta deve comunque soddisfare quel percorso di auth. Vedi: [Gateway remoto](/it/gateway/remote), [Autenticazione](/it/gateway/authentication), [Tailscale](/it/gateway/tailscale). ## Supervisione e ciclo di vita del servizio -Usa esecuzioni supervisionate per un'affidabilità di tipo produzione. +Usa esecuzioni supervisionate per un'affidabilità di livello produzione. @@ -202,7 +203,7 @@ openclaw gateway restart openclaw gateway stop ``` -Le etichette LaunchAgent sono `ai.openclaw.gateway` (predefinita) oppure `ai.openclaw.` (profilo con nome). `openclaw doctor` verifica e ripara la deriva della configurazione del servizio. +Le etichette LaunchAgent sono `ai.openclaw.gateway` (predefinita) o `ai.openclaw.` (profilo con nome). `openclaw doctor` controlla e ripara la deriva della configurazione del servizio. @@ -220,7 +221,7 @@ Per la persistenza dopo il logout, abilita lingering: sudo loginctl enable-linger ``` -Esempio manuale di unità utente quando ti serve un percorso di installazione personalizzato: +Esempio manuale di unità utente quando hai bisogno di un percorso di installazione personalizzato: ```ini [Unit] @@ -253,8 +254,8 @@ openclaw gateway stop ``` L'avvio gestito nativo di Windows usa un'Attività pianificata chiamata `OpenClaw Gateway` -(o `OpenClaw Gateway ()` per i profili con nome). Se la creazione dell'Attività pianificata -viene negata, OpenClaw torna a un launcher per utente nella cartella Esecuzione automatica +(oppure `OpenClaw Gateway ()` per i profili con nome). Se la creazione +dell'Attività pianificata viene negata, OpenClaw ripiega su un launcher per utente nella cartella Startup che punta a `gateway.cmd` all'interno della directory di stato. @@ -268,21 +269,21 @@ sudo systemctl daemon-reload sudo systemctl enable --now openclaw-gateway[-].service ``` -Usa lo stesso corpo del servizio dell'unità utente, ma installalo sotto +Usa lo stesso corpo del servizio dell'unità utente, ma installalo in `/etc/systemd/system/openclaw-gateway[-].service` e regola `ExecStart=` se il tuo binario `openclaw` si trova altrove. -## Più gateway su un host +## Gateway multipli su un host -La maggior parte delle configurazioni dovrebbe eseguire **un** solo Gateway. -Usane più di uno solo per isolamento/ridondanza rigorosi (ad esempio un profilo di emergenza). +La maggior parte delle configurazioni dovrebbe eseguire **un solo** Gateway. +Usane più di uno solo per isolamento/ridondanza rigorosi (per esempio un profilo di emergenza). Checklist per istanza: -- `gateway.port` univoco +- `gateway.port` univoca - `OPENCLAW_CONFIG_PATH` univoco - `OPENCLAW_STATE_DIR` univoco - `agents.defaults.workspace` univoco @@ -294,9 +295,9 @@ OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a opencla OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002 ``` -Vedi: [Più gateway](/it/gateway/multiple-gateways). +Vedi: [Gateway multipli](/it/gateway/multiple-gateways). -### Percorso rapido del profilo dev +### Percorso rapido per il profilo dev ```bash openclaw --dev setup @@ -304,13 +305,13 @@ openclaw --dev gateway --allow-unconfigured openclaw --dev status ``` -I valori predefiniti includono stato/config isolati e porta base del gateway `19001`. +I valori predefiniti includono stato/configurazione isolati e una porta Gateway di base `19001`. ## Riferimento rapido del protocollo (vista operatore) - Il primo frame del client deve essere `connect`. - Il Gateway restituisce uno snapshot `hello-ok` (`presence`, `health`, `stateVersion`, `uptimeMs`, limiti/policy). -- `hello-ok.features.methods` / `events` sono un elenco di discovery prudente, non +- `hello-ok.features.methods` / `events` sono un elenco di rilevamento conservativo, non un dump generato di ogni route helper richiamabile. - Richieste: `req(method, params)` → `res(ok/payload|error)`. - Gli eventi comuni includono `connect.challenge`, `agent`, `chat`, @@ -319,7 +320,7 @@ I valori predefiniti includono stato/config isolati e porta base del gateway `19 Le esecuzioni degli agenti sono in due fasi: -1. Ack di accettazione immediata (`status:"accepted"`) +1. Ack di accettazione immediato (`status:"accepted"`) 2. Risposta finale di completamento (`status:"ok"|"error"`), con eventi `agent` in streaming nel mezzo. Vedi la documentazione completa del protocollo: [Protocollo Gateway](/it/gateway/protocol). @@ -329,7 +330,7 @@ Vedi la documentazione completa del protocollo: [Protocollo Gateway](/it/gateway ### Liveness - Apri WS e invia `connect`. -- Attendi una risposta `hello-ok` con snapshot. +- Aspettati una risposta `hello-ok` con snapshot. ### Readiness @@ -343,22 +344,22 @@ openclaw health Gli eventi non vengono riprodotti. In caso di gap di sequenza, aggiorna lo stato (`health`, `system-presence`) prima di continuare. -## Firme di errore comuni +## Firme comuni di errore -| Firma | Problema probabile | -| ------------------------------------------------------------- | -------------------------------------------------------------------------------- | -| `refusing to bind gateway ... without auth` | Bind non-loopback senza un percorso di autenticazione del gateway valido | -| `another gateway instance is already listening` / `EADDRINUSE` | Conflitto di porta | -| `Gateway start blocked: set gateway.mode=local` | Config impostata in modalità remota, oppure stamp di modalità locale mancante in una config danneggiata | -| `unauthorized` during connect | Mancata corrispondenza dell'autenticazione tra client e gateway | +| Firma | Problema probabile | +| -------------------------------------------------------------- | --------------------------------------------------------------------------------- | +| `refusing to bind gateway ... without auth` | Bind non-loopback senza un percorso di auth del gateway valido | +| `another gateway instance is already listening` / `EADDRINUSE` | Conflitto di porta | +| `Gateway start blocked: set gateway.mode=local` | Configurazione impostata in modalità remota, oppure manca il marker local-mode da una configurazione danneggiata | +| `unauthorized` during connect | Mancata corrispondenza auth tra client e gateway | Per sequenze complete di diagnosi, usa [Risoluzione dei problemi del Gateway](/it/gateway/troubleshooting). ## Garanzie di sicurezza - I client del protocollo Gateway falliscono rapidamente quando il Gateway non è disponibile (nessun fallback implicito diretto al canale). -- I first frame non validi/non-connect vengono rifiutati e la connessione viene chiusa. -- Lo shutdown ordinato emette l'evento `shutdown` prima della chiusura del socket. +- I primi frame non validi/non-connect vengono rifiutati e la connessione viene chiusa. +- Lo spegnimento ordinato emette l'evento `shutdown` prima della chiusura del socket. --- diff --git a/docs/it/gateway/troubleshooting.md b/docs/it/gateway/troubleshooting.md index b9e3e9aed..e57a7021c 100644 --- a/docs/it/gateway/troubleshooting.md +++ b/docs/it/gateway/troubleshooting.md @@ -1,14 +1,14 @@ --- read_when: - L'hub di risoluzione dei problemi ti ha indirizzato qui per una diagnosi più approfondita - - Hai bisogno di sezioni di runbook stabili basate sui sintomi con comandi esatti -summary: Runbook di risoluzione avanzata dei problemi per gateway, canali, automazione, nodi e browser + - Hai bisogno di sezioni del runbook stabili e basate sui sintomi con comandi esatti +summary: Runbook di troubleshooting approfondito per Gateway, canali, automazione, Node e browser title: Risoluzione dei problemi x-i18n: - generated_at: "2026-04-11T02:45:10Z" + generated_at: "2026-04-20T08:30:49Z" model: gpt-5.4 provider: openai - source_hash: 7ef2faccba26ede307861504043a6415bc1f12dc64407771106f63ddc5b107f5 + source_hash: d93a82407dbb1314b91a809ff9433114e1e9a3b56d46547ef53a8196bac06260 source_path: gateway/troubleshooting.md workflow: 15 --- @@ -32,12 +32,12 @@ openclaw channels status --probe Segnali attesi di stato sano: -- `openclaw gateway status` mostra `Runtime: running` e `RPC probe: ok`. -- `openclaw doctor` non segnala problemi bloccanti di configurazione o servizio. -- `openclaw channels status --probe` mostra lo stato live del trasporto per account e, +- `openclaw gateway status` mostra `Runtime: running`, `Connectivity probe: ok` e una riga `Capability: ...`. +- `openclaw doctor` non segnala problemi bloccanti di configurazione/servizio. +- `openclaw channels status --probe` mostra lo stato di trasporto live per account e, dove supportato, risultati di probe/audit come `works` o `audit ok`. -## Anthropic 429 richiede utilizzo extra per contesto lungo +## Anthropic 429: utilizzo extra richiesto per contesto lungo Usa questa sezione quando i log/errori includono: `HTTP 429: rate_limit_error: Extra usage is required for long context requests`. @@ -51,14 +51,14 @@ openclaw config get agents.defaults.models Cerca: - Il modello Anthropic Opus/Sonnet selezionato ha `params.context1m: true`. -- La credenziale Anthropic corrente non è idonea per l'uso con contesto lungo. -- Le richieste falliscono solo su sessioni lunghe/esecuzioni del modello che richiedono il percorso beta 1M. +- La credenziale Anthropic corrente non è idonea per l'uso del contesto lungo. +- Le richieste falliscono solo su sessioni lunghe/esecuzioni del modello che richiedono il percorso beta da 1M. Opzioni di correzione: -1. Disabilita `context1m` per quel modello per tornare alla normale finestra di contesto. -2. Usa una credenziale Anthropic idonea per richieste con contesto lungo, oppure passa a una chiave API Anthropic. -3. Configura modelli di fallback in modo che le esecuzioni continuino quando le richieste Anthropic con contesto lungo vengono rifiutate. +1. Disabilita `context1m` per quel modello in modo da tornare alla finestra di contesto normale. +2. Usa una credenziale Anthropic idonea per le richieste a contesto lungo, oppure passa a una chiave API Anthropic. +3. Configura modelli di fallback in modo che le esecuzioni continuino quando le richieste Anthropic a contesto lungo vengono rifiutate. Correlati: @@ -66,13 +66,13 @@ Correlati: - [/reference/token-use](/it/reference/token-use) - [/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic](/it/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic) -## Un backend locale compatibile con OpenAI supera le probe dirette ma le esecuzioni dell'agente falliscono +## Il backend locale compatibile con OpenAI supera i probe diretti ma le esecuzioni dell'agente falliscono Usa questa sezione quando: - `curl ... /v1/models` funziona - piccole chiamate dirette a `/v1/chat/completions` funzionano -- le esecuzioni del modello OpenClaw falliscono solo durante i normali turni dell'agente +- le esecuzioni del modello OpenClaw falliscono solo nei normali turni dell'agente ```bash curl http://127.0.0.1:1234/v1/models @@ -85,22 +85,34 @@ openclaw logs --follow Cerca: -- le piccole chiamate dirette riescono, ma le esecuzioni OpenClaw falliscono solo con prompt più grandi +- le piccole chiamate dirette hanno esito positivo, ma le esecuzioni OpenClaw falliscono solo con prompt più grandi - errori del backend su `messages[].content` che si aspetta una stringa -- crash del backend che compaiono solo con conteggi più alti di token nel prompt o con prompt completi del runtime dell'agente +- crash del backend che compaiono solo con conteggi di token del prompt più elevati o con i prompt completi del runtime dell'agente Firme comuni: -- `messages[...].content: invalid type: sequence, expected a string` → il backend rifiuta parti di contenuto strutturato in Chat Completions. Correzione: imposta `models.providers..models[].compat.requiresStringContent: true`. -- le piccole richieste dirette riescono, ma i turni dell'agente OpenClaw falliscono con crash del backend/modello (per esempio Gemma su alcune build `inferrs`) → il trasporto OpenClaw è probabilmente già corretto; è il backend che fallisce sulla forma più ampia del prompt del runtime dell'agente. -- i fallimenti si riducono dopo aver disabilitato gli strumenti ma non scompaiono → gli schemi degli strumenti contribuivano al carico, ma il problema rimanente è ancora a monte: capacità del modello/server o un bug del backend. +- `messages[...].content: invalid type: sequence, expected a string` → il backend + rifiuta le parti strutturate del contenuto di Chat Completions. Correzione: imposta + `models.providers..models[].compat.requiresStringContent: true`. +- le piccole richieste dirette hanno esito positivo, ma i turni dell'agente OpenClaw falliscono con + crash del backend/modello (per esempio Gemma su alcune build `inferrs`) → il trasporto OpenClaw è + probabilmente già corretto; è il backend che fallisce sulla forma più ampia del prompt + del runtime dell'agente. +- i fallimenti si riducono dopo aver disabilitato i tool ma non scompaiono → gli schemi dei tool erano + parte della pressione, ma il problema residuo è comunque a monte: capacità del modello/server + o un bug del backend. Opzioni di correzione: 1. Imposta `compat.requiresStringContent: true` per i backend Chat Completions che accettano solo stringhe. -2. Imposta `compat.supportsTools: false` per modelli/backend che non riescono a gestire in modo affidabile la superficie di schema degli strumenti di OpenClaw. -3. Riduci il carico del prompt dove possibile: bootstrap del workspace più piccolo, cronologia della sessione più breve, modello locale più leggero o backend con supporto più robusto per contesti lunghi. -4. Se le piccole richieste dirette continuano a funzionare mentre i turni dell'agente OpenClaw continuano a crashare nel backend, trattalo come un limite del server/modello a monte e apri lì un repro con la forma di payload accettata. +2. Imposta `compat.supportsTools: false` per modelli/backend che non riescono a gestire + in modo affidabile la superficie dello schema dei tool di OpenClaw. +3. Riduci la pressione del prompt dove possibile: bootstrap dello workspace più piccolo, cronologia + della sessione più corta, modello locale più leggero o un backend con supporto più solido + per il contesto lungo. +4. Se le piccole richieste dirette continuano a funzionare mentre i turni dell'agente OpenClaw continuano a bloccarsi + nel backend, trattalo come un limite del server/modello a monte e apri lì + un repro con la forma del payload accettata. Correlati: @@ -110,7 +122,7 @@ Correlati: ## Nessuna risposta -Se i canali sono attivi ma non arriva nessuna risposta, controlla instradamento e policy prima di ricollegare qualsiasi cosa. +Se i canali sono attivi ma non arriva alcuna risposta, controlla instradamento e policy prima di riconnettere qualsiasi cosa. ```bash openclaw status @@ -122,14 +134,14 @@ openclaw logs --follow Cerca: -- Pairing in sospeso per i mittenti di messaggi diretti. -- Blocco delle menzioni nei gruppi (`requireMention`, `mentionPatterns`). -- Mancata corrispondenza nelle allowlist di canale/gruppo. +- Pairing in sospeso per i mittenti DM. +- Blocco per menzione nei gruppi (`requireMention`, `mentionPatterns`). +- Mancate corrispondenze nelle allowlist di canale/gruppo. Firme comuni: -- `drop guild message (mention required` → messaggio di gruppo ignorato finché non viene menzionato. -- `pairing request` → il mittente richiede approvazione. +- `drop guild message (mention required` → messaggio di gruppo ignorato fino a menzione. +- `pairing request` → il mittente necessita approvazione. - `blocked` / `allowlist` → mittente/canale filtrato dalla policy. Correlati: @@ -138,9 +150,9 @@ Correlati: - [/channels/pairing](/it/channels/pairing) - [/channels/groups](/it/channels/groups) -## Connettività del dashboard Control UI +## Connettività della control UI della dashboard -Quando il dashboard/Control UI non si connette, verifica URL, modalità di autenticazione e presupposti di contesto sicuro. +Quando la dashboard/control UI non si connette, verifica URL, modalità di autenticazione e presupposti di contesto sicuro. ```bash openclaw gateway status @@ -152,37 +164,47 @@ openclaw gateway status --json Cerca: -- URL di probe e URL del dashboard corretti. -- Mancata corrispondenza della modalità/token di autenticazione tra client e gateway. +- URL del probe e URL della dashboard corretti. +- Mancata corrispondenza della modalità/token di autenticazione tra client e Gateway. - Uso di HTTP dove è richiesta l'identità del dispositivo. Firme comuni: - `device identity required` → contesto non sicuro o autenticazione del dispositivo mancante. -- `origin not allowed` → `Origin` del browser non è in `gateway.controlUi.allowedOrigins` - (oppure ti stai connettendo da un'origine browser non loopback senza una allowlist esplicita). -- `device nonce required` / `device nonce mismatch` → il client non sta completando il flusso di autenticazione del dispositivo basato su challenge (`connect.challenge` + `device.nonce`). -- `device signature invalid` / `device signature expired` → il client ha firmato il payload sbagliato (o con timestamp scaduto) per l'handshake corrente. -- `AUTH_TOKEN_MISMATCH` con `canRetryWithDeviceToken=true` → il client può eseguire un retry trusted con token del dispositivo memorizzato in cache. -- Quel retry con token in cache riutilizza l'insieme di scope memorizzato con il token del dispositivo associato. I chiamanti con `deviceToken` esplicito / `scopes` espliciti mantengono invece l'insieme di scope richiesto. -- Al di fuori di quel percorso di retry, la precedenza dell'autenticazione di connessione è: token/password condivisi espliciti, poi `deviceToken` esplicito, poi token del dispositivo memorizzato, poi bootstrap token. -- Nel percorso asincrono Tailscale Serve Control UI, i tentativi falliti per lo stesso `{scope, ip}` vengono serializzati prima che il limitatore registri il fallimento. Due retry concorrenti errati dallo stesso client possono quindi mostrare `retry later` sul secondo tentativo invece di due semplici mismatch. -- `too many failed authentication attempts (retry later)` da un client loopback con origine browser → fallimenti ripetuti dalla stessa `Origin` normalizzata vengono temporaneamente bloccati; un'altra origine localhost usa un bucket separato. -- `unauthorized` ripetuti dopo quel retry → deriva tra token condiviso e token del dispositivo; aggiorna la configurazione del token e riapprova/ruota il token del dispositivo se necessario. -- `gateway connect failed:` → host/porta/target URL errato. +- `origin not allowed` → l'`Origin` del browser non è in `gateway.controlUi.allowedOrigins` + (oppure stai effettuando la connessione da un'origine browser non loopback senza una + allowlist esplicita). +- `device nonce required` / `device nonce mismatch` → il client non completa il + flusso di autenticazione del dispositivo basato su challenge (`connect.challenge` + `device.nonce`). +- `device signature invalid` / `device signature expired` → il client ha firmato il payload sbagliato + (o con timestamp obsoleto) per l'handshake corrente. +- `AUTH_TOKEN_MISMATCH` con `canRetryWithDeviceToken=true` → il client può eseguire un solo retry affidabile con il token dispositivo in cache. +- Quel retry con token in cache riutilizza l'insieme di scope in cache memorizzato con il + token del dispositivo associato. I chiamanti con `deviceToken` esplicito / `scopes` espliciti mantengono invece + l'insieme di scope richiesto. +- Al di fuori di quel percorso di retry, la precedenza dell'autenticazione in connessione è + prima token/password condivisi espliciti, poi `deviceToken` esplicito, poi token dispositivo memorizzato, + quindi token bootstrap. +- Nel percorso asincrono della Control UI Tailscale Serve, i tentativi falliti per lo stesso + `{scope, ip}` vengono serializzati prima che il limitatore registri il fallimento. Due retry concorrenti errati dello stesso client possono quindi mostrare `retry later` + al secondo tentativo invece di due semplici mismatch. +- `too many failed authentication attempts (retry later)` da un client loopback con origine browser + → i fallimenti ripetuti da quello stesso `Origin` normalizzato vengono bloccati temporaneamente; un'altra origine localhost usa un bucket separato. +- `unauthorized` ripetuti dopo quel retry → deriva di token condiviso/token dispositivo; aggiorna la configurazione del token e riapprova/ruota il token dispositivo se necessario. +- `gateway connect failed:` → host/porta/URL di destinazione errati. ### Mappa rapida dei codici di dettaglio auth Usa `error.details.code` dalla risposta `connect` fallita per scegliere l'azione successiva: -| Codice di dettaglio | Significato | Azione consigliata | -| ---------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AUTH_TOKEN_MISSING` | Il client non ha inviato un token condiviso richiesto. | Incolla/imposta il token nel client e riprova. Per i percorsi dashboard: `openclaw config get gateway.auth.token` poi incollalo nelle impostazioni di Control UI. | -| `AUTH_TOKEN_MISMATCH` | Il token condiviso non corrisponde al token auth del gateway. | Se `canRetryWithDeviceToken=true`, consenti un retry trusted. I retry con token in cache riutilizzano gli scope approvati memorizzati; i chiamanti con `deviceToken` / `scopes` espliciti mantengono gli scope richiesti. Se continua a fallire, esegui la [checklist di ripristino della deriva del token](/cli/devices#token-drift-recovery-checklist). | -| `AUTH_DEVICE_TOKEN_MISMATCH` | Il token per dispositivo memorizzato è obsoleto o revocato. | Ruota/riapprova il token del dispositivo usando la [CLI devices](/cli/devices), poi riconnettiti. | -| `PAIRING_REQUIRED` | L'identità del dispositivo è nota ma non approvata per questo ruolo. | Approva la richiesta in sospeso: `openclaw devices list` poi `openclaw devices approve `. | +| Detail code | Meaning | Recommended action | +| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AUTH_TOKEN_MISSING` | Il client non ha inviato un token condiviso richiesto. | Incolla/imposta il token nel client e riprova. Per i percorsi dashboard: `openclaw config get gateway.auth.token` poi incollalo nelle impostazioni della Control UI. | +| `AUTH_TOKEN_MISMATCH` | Il token condiviso non corrisponde al token auth del Gateway. | Se `canRetryWithDeviceToken=true`, consenti un retry affidabile. I retry con token in cache riutilizzano gli scope approvati memorizzati; i chiamanti con `deviceToken` / `scopes` espliciti mantengono gli scope richiesti. Se continua a fallire, esegui la [checklist di ripristino deriva token](/cli/devices#token-drift-recovery-checklist). | +| `AUTH_DEVICE_TOKEN_MISMATCH` | Il token per-dispositivo in cache è obsoleto o revocato. | Ruota/riapprova il token dispositivo usando la [CLI dei dispositivi](/cli/devices), poi riconnettiti. | +| `PAIRING_REQUIRED` | L'identità del dispositivo richiede approvazione. Controlla `error.details.reason` per `not-paired`, `scope-upgrade`, `role-upgrade` o `metadata-upgrade`, e usa `requestId` / `remediationHint` quando presenti. | Approva la richiesta in sospeso: `openclaw devices list` poi `openclaw devices approve `. Gli upgrade di scope/ruolo usano lo stesso flusso dopo aver esaminato l'accesso richiesto. | -Controllo della migrazione ad auth dispositivo v2: +Controllo della migrazione auth dispositivo v2: ```bash openclaw --version @@ -193,25 +215,27 @@ openclaw gateway status Se i log mostrano errori di nonce/firma, aggiorna il client che si connette e verifica che: 1. attenda `connect.challenge` -2. firmi il payload vincolato alla challenge +2. firmi il payload associato alla challenge 3. invii `connect.params.device.nonce` con lo stesso nonce della challenge -Se `openclaw devices rotate` / `revoke` / `remove` viene negato in modo inatteso: +Se `openclaw devices rotate` / `revoke` / `remove` viene negato in modo imprevisto: -- le sessioni con token di dispositivo associato possono gestire solo **il proprio** dispositivo, a meno che il chiamante non abbia anche `operator.admin` -- `openclaw devices rotate --scope ...` può richiedere solo scope operatore che la sessione chiamante già possiede +- le sessioni con token di dispositivo associato possono gestire solo **il proprio** + dispositivo a meno che il chiamante non abbia anche `operator.admin` +- `openclaw devices rotate --scope ...` può richiedere solo scope operatore che + la sessione chiamante possiede già Correlati: - [/web/control-ui](/web/control-ui) -- [/gateway/configuration](/it/gateway/configuration) (modalità auth del gateway) +- [/gateway/configuration](/it/gateway/configuration) (modalità auth del Gateway) - [/gateway/trusted-proxy-auth](/it/gateway/trusted-proxy-auth) - [/gateway/remote](/it/gateway/remote) - [/cli/devices](/cli/devices) -## Servizio gateway non in esecuzione +## Servizio Gateway non in esecuzione -Usa questa sezione quando il servizio è installato ma il processo non resta attivo. +Usa questa sezione quando il servizio è installato ma il processo non rimane attivo. ```bash openclaw gateway status @@ -223,18 +247,18 @@ openclaw gateway status --deep # esegue anche la scansione dei servizi a livel Cerca: -- `Runtime: stopped` con indizi sull'uscita. +- `Runtime: stopped` con indicazioni sull'uscita. - Mancata corrispondenza della configurazione del servizio (`Config (cli)` vs `Config (service)`). - Conflitti di porta/listener. -- Installazioni launchd/systemd/schtasks aggiuntive quando si usa `--deep`. -- Suggerimenti di pulizia `Other gateway-like services detected (best effort)`. +- Installazioni launchd/systemd/schtasks aggiuntive quando viene usato `--deep`. +- Indicazioni di pulizia `Other gateway-like services detected (best effort)`. Firme comuni: -- `Gateway start blocked: set gateway.mode=local` o `existing config is missing gateway.mode` → la modalità gateway locale non è abilitata, oppure il file di configurazione è stato sovrascritto e ha perso `gateway.mode`. Correzione: imposta `gateway.mode="local"` nella tua configurazione, oppure esegui di nuovo `openclaw onboard --mode local` / `openclaw setup` per ripristinare la configurazione attesa in modalità locale. Se stai eseguendo OpenClaw tramite Podman, il percorso predefinito della configurazione è `~/.openclaw/openclaw.json`. -- `refusing to bind gateway ... without auth` → bind non loopback senza un percorso auth valido per il gateway (token/password, oppure trusted-proxy dove configurato). +- `Gateway start blocked: set gateway.mode=local` o `existing config is missing gateway.mode` → la modalità Gateway locale non è abilitata, oppure il file di configurazione è stato sovrascritto e ha perso `gateway.mode`. Correzione: imposta `gateway.mode="local"` nella tua configurazione, oppure esegui di nuovo `openclaw onboard --mode local` / `openclaw setup` per ripristinare la configurazione prevista per la modalità locale. Se stai eseguendo OpenClaw tramite Podman, il percorso di configurazione predefinito è `~/.openclaw/openclaw.json`. +- `refusing to bind gateway ... without auth` → bind non loopback senza un percorso auth Gateway valido (token/password, oppure trusted-proxy dove configurato). - `another gateway instance is already listening` / `EADDRINUSE` → conflitto di porta. -- `Other gateway-like services detected (best effort)` → esistono unità launchd/systemd/schtasks obsolete o parallele. Nella maggior parte delle configurazioni è opportuno mantenere un solo gateway per macchina; se davvero ne servono più di uno, isola porte + configurazione/stato/workspace. Vedi [/gateway#multiple-gateways-same-host](/it/gateway#multiple-gateways-same-host). +- `Other gateway-like services detected (best effort)` → esistono unità launchd/systemd/schtasks obsolete o parallele. La maggior parte delle configurazioni dovrebbe mantenere un solo Gateway per macchina; se te ne serve più di uno, isola porte + configurazione/stato/workspace. Vedi [/gateway#multiple-gateways-same-host](/it/gateway#multiple-gateways-same-host). Correlati: @@ -242,7 +266,7 @@ Correlati: - [/gateway/configuration](/it/gateway/configuration) - [/gateway/doctor](/it/gateway/doctor) -## Avvisi della probe del gateway +## Avvisi del probe del Gateway Usa questa sezione quando `openclaw gateway probe` raggiunge qualcosa, ma stampa comunque un blocco di avviso. @@ -255,14 +279,15 @@ openclaw gateway probe --ssh user@gateway-host Cerca: - `warnings[].code` e `primaryTargetId` nell'output JSON. -- Se l'avviso riguarda fallback SSH, gateway multipli, scope mancanti o SecretRef auth non risolti. +- Se l'avviso riguarda fallback SSH, più Gateway, scope mancanti o riferimenti auth non risolti. Firme comuni: - `SSH tunnel failed to start; falling back to direct probes.` → la configurazione SSH non è riuscita, ma il comando ha comunque provato i target diretti configurati/loopback. -- `multiple reachable gateways detected` → ha risposto più di un target. Di solito questo indica una configurazione multi-gateway intenzionale oppure listener obsoleti/duplicati. -- `Probe diagnostics are limited by gateway scopes (missing operator.read)` → la connessione è riuscita, ma il dettaglio RPC è limitato dagli scope; associa l'identità del dispositivo oppure usa credenziali con `operator.read`. -- testo di avviso SecretRef non risolto per `gateway.auth.*` / `gateway.remote.*` → il materiale auth non era disponibile in questo percorso di comando per il target fallito. +- `multiple reachable gateways detected` → ha risposto più di un target. Di solito questo indica una configurazione multi-Gateway intenzionale o listener obsoleti/duplicati. +- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → la connessione ha funzionato, ma il dettaglio RPC è limitato dagli scope; associa l'identità del dispositivo o usa credenziali con `operator.read`. +- `Capability: pairing-pending` o `gateway closed (1008): pairing required` → il Gateway ha risposto, ma questo client necessita ancora di pairing/approvazione prima del normale accesso operatore. +- testo di avviso SecretRef `gateway.auth.*` / `gateway.remote.*` non risolto → il materiale auth non era disponibile in questo percorso di comando per il target non riuscito. Correlati: @@ -270,7 +295,7 @@ Correlati: - [/gateway#multiple-gateways-same-host](/it/gateway#multiple-gateways-same-host) - [/gateway/remote](/it/gateway/remote) -## Canale connesso ma flusso dei messaggi bloccato +## Il canale è connesso ma i messaggi non fluiscono Se lo stato del canale è connesso ma il flusso dei messaggi è fermo, concentrati su policy, permessi e regole di consegna specifiche del canale. @@ -285,7 +310,7 @@ openclaw config get channels Cerca: - Policy DM (`pairing`, `allowlist`, `open`, `disabled`). -- Allowlist di gruppo e requisiti di menzione. +- Allowlist dei gruppi e requisiti di menzione. - Permessi/scope API del canale mancanti. Firme comuni: @@ -301,9 +326,9 @@ Correlati: - [/channels/telegram](/it/channels/telegram) - [/channels/discord](/it/channels/discord) -## Consegna di cron e heartbeat +## Consegna di Cron e Heartbeat -Se cron o heartbeat non sono stati eseguiti o non sono stati consegnati, verifica prima lo stato dello scheduler, poi il target di consegna. +Se Cron o Heartbeat non sono stati eseguiti o non hanno recapitato nulla, verifica prima lo stato dello scheduler, poi la destinazione della consegna. ```bash openclaw cron status @@ -315,19 +340,19 @@ openclaw logs --follow Cerca: -- Cron abilitato e prossimo risveglio presente. +- Cron abilitato e prossima attivazione presente. - Stato della cronologia delle esecuzioni del job (`ok`, `skipped`, `error`). -- Motivi di salto dell'heartbeat (`quiet-hours`, `requests-in-flight`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`). +- Motivi di salto di Heartbeat (`quiet-hours`, `requests-in-flight`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`). Firme comuni: -- `cron: scheduler disabled; jobs will not run automatically` → cron disabilitato. -- `cron: timer tick failed` → tick dello scheduler fallito; controlla errori di file/log/runtime. -- `heartbeat skipped` con `reason=quiet-hours` → fuori dalla finestra di orario attivo. +- `cron: scheduler disabled; jobs will not run automatically` → Cron disabilitato. +- `cron: timer tick failed` → tick dello scheduler non riuscito; controlla errori di file/log/runtime. +- `heartbeat skipped` con `reason=quiet-hours` → fuori dalla finestra di ore attive. - `heartbeat skipped` con `reason=empty-heartbeat-file` → `HEARTBEAT.md` esiste ma contiene solo righe vuote / intestazioni markdown, quindi OpenClaw salta la chiamata al modello. -- `heartbeat skipped` con `reason=no-tasks-due` → `HEARTBEAT.md` contiene un blocco `tasks:`, ma nessuna delle attività è prevista in questo tick. -- `heartbeat: unknown accountId` → account id non valido per il target di consegna dell'heartbeat. -- `heartbeat skipped` con `reason=dm-blocked` → il target dell'heartbeat è stato risolto come destinazione in stile DM mentre `agents.defaults.heartbeat.directPolicy` (o l'override per agente) è impostato su `block`. +- `heartbeat skipped` con `reason=no-tasks-due` → `HEARTBEAT.md` contiene un blocco `tasks:`, ma nessuna attività è in scadenza in questo tick. +- `heartbeat: unknown accountId` → account id non valido per la destinazione di consegna di Heartbeat. +- `heartbeat skipped` con `reason=dm-blocked` → la destinazione di Heartbeat è stata risolta in una destinazione di tipo DM mentre `agents.defaults.heartbeat.directPolicy` (o l'override per agente) è impostato su `block`. Correlati: @@ -335,9 +360,9 @@ Correlati: - [/automation/cron-jobs](/it/automation/cron-jobs) - [/gateway/heartbeat](/it/gateway/heartbeat) -## Strumento del nodo associato non funzionante +## Il tool del Node associato fallisce -Se un nodo è associato ma gli strumenti non funzionano, isola stato in primo piano, permessi e approvazione. +Se un Node è associato ma i tool falliscono, isola lo stato di foreground, permessi e approvazione. ```bash openclaw nodes status @@ -349,16 +374,16 @@ openclaw status Cerca: -- Nodo online con le capacità previste. -- Permessi del sistema operativo per fotocamera/microfono/posizione/schermo. -- Stato di approvazioni exec e allowlist. +- Node online con le capability previste. +- Permessi OS concessi per fotocamera/microfono/posizione/schermo. +- Stato delle approvazioni exec e dell'allowlist. Firme comuni: -- `NODE_BACKGROUND_UNAVAILABLE` → l'app del nodo deve essere in primo piano. -- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → permesso del sistema operativo mancante. +- `NODE_BACKGROUND_UNAVAILABLE` → l'app del Node deve essere in foreground. +- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → permesso OS mancante. - `SYSTEM_RUN_DENIED: approval required` → approvazione exec in sospeso. -- `SYSTEM_RUN_DENIED: allowlist miss` → comando bloccato dalla allowlist. +- `SYSTEM_RUN_DENIED: allowlist miss` → comando bloccato dall'allowlist. Correlati: @@ -366,9 +391,9 @@ Correlati: - [/nodes/index](/it/nodes/index) - [/tools/exec-approvals](/it/tools/exec-approvals) -## Strumento browser non funzionante +## Il tool browser fallisce -Usa questa sezione quando le azioni dello strumento browser falliscono anche se il gateway stesso è sano. +Usa questa sezione quando le azioni del tool browser falliscono anche se il Gateway stesso è sano. ```bash openclaw browser status @@ -381,38 +406,38 @@ openclaw doctor Cerca: - Se `plugins.allow` è impostato e include `browser`. -- Percorso valido dell'eseguibile del browser. +- Percorso eseguibile del browser valido. - Raggiungibilità del profilo CDP. - Disponibilità di Chrome locale per i profili `existing-session` / `user`. Firme comuni: -- `unknown command "browser"` o `unknown command 'browser'` → il plugin browser incluso è escluso da `plugins.allow`. -- browser tool mancante / non disponibile mentre `browser.enabled=true` → `plugins.allow` esclude `browser`, quindi il plugin non è mai stato caricato. +- `unknown command "browser"` o `unknown command 'browser'` → il Plugin browser integrato è escluso da `plugins.allow`. +- tool browser mancante / non disponibile mentre `browser.enabled=true` → `plugins.allow` esclude `browser`, quindi il Plugin non è mai stato caricato. - `Failed to start Chrome CDP on port` → il processo del browser non è riuscito ad avviarsi. - `browser.executablePath not found` → il percorso configurato non è valido. - `browser.cdpUrl must be http(s) or ws(s)` → l'URL CDP configurato usa uno schema non supportato come `file:` o `ftp:`. -- `browser.cdpUrl has invalid port` → l'URL CDP configurato ha una porta non valida o fuori intervallo. +- `browser.cdpUrl has invalid port` → l'URL CDP configurato ha una porta errata o fuori intervallo. - `No Chrome tabs found for profile="user"` → il profilo di collegamento Chrome MCP non ha schede Chrome locali aperte. -- `Remote CDP for profile "" is not reachable` → l'endpoint CDP remoto configurato non è raggiungibile dall'host del gateway. -- `Browser attachOnly is enabled ... not reachable` o `Browser attachOnly is enabled and CDP websocket ... is not reachable` → il profilo solo-attach non ha un target raggiungibile, oppure l'endpoint HTTP ha risposto ma il WebSocket CDP non è comunque stato aperto. -- `Playwright is not available in this gateway build; '' is unsupported.` → l'installazione corrente del gateway non include il pacchetto completo Playwright; snapshot ARIA e screenshot di base della pagina possono comunque funzionare, ma navigazione, snapshot AI, screenshot di elementi con selettori CSS ed esportazione PDF restano non disponibili. -- `fullPage is not supported for element screenshots` → la richiesta di screenshot ha mescolato `--full-page` con `--ref` o `--element`. -- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → le chiamate di screenshot Chrome MCP / `existing-session` devono usare la cattura della pagina o un `--ref` da snapshot, non `--element` CSS. -- `existing-session file uploads do not support element selectors; use ref/inputRef.` → gli hook di upload file in Chrome MCP richiedono riferimenti snapshot, non selettori CSS. -- `existing-session file uploads currently support one file at a time.` → invia un solo upload per chiamata nei profili Chrome MCP. -- `existing-session dialog handling does not support timeoutMs.` → gli hook di dialogo nei profili Chrome MCP non supportano override di timeout. +- `Remote CDP for profile "" is not reachable` → l'endpoint CDP remoto configurato non è raggiungibile dall'host Gateway. +- `Browser attachOnly is enabled ... not reachable` o `Browser attachOnly is enabled and CDP websocket ... is not reachable` → il profilo solo attach non ha un target raggiungibile, oppure l'endpoint HTTP ha risposto ma il WebSocket CDP non può comunque essere aperto. +- `Playwright is not available in this gateway build; '' is unsupported.` → l'installazione corrente del Gateway non include il pacchetto completo di Playwright; gli snapshot ARIA e gli screenshot di pagina di base possono comunque funzionare, ma navigazione, snapshot AI, screenshot di elementi con selettori CSS ed esportazione PDF restano non disponibili. +- `fullPage is not supported for element screenshots` → la richiesta di screenshot ha combinato `--full-page` con `--ref` o `--element`. +- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → le chiamate di screenshot Chrome MCP / `existing-session` devono usare l'acquisizione della pagina o un `--ref` da snapshot, non `--element` CSS. +- `existing-session file uploads do not support element selectors; use ref/inputRef.` → gli hook di upload file di Chrome MCP richiedono riferimenti snapshot, non selettori CSS. +- `existing-session file uploads currently support one file at a time.` → invia un upload per chiamata sui profili Chrome MCP. +- `existing-session dialog handling does not support timeoutMs.` → gli hook di dialogo sui profili Chrome MCP non supportano override di timeout. - `response body is not supported for existing-session profiles yet.` → `responsebody` richiede ancora un browser gestito o un profilo CDP raw. -- override obsoleti di viewport / dark-mode / locale / offline nei profili solo-attach o CDP remoti → esegui `openclaw browser stop --browser-profile ` per chiudere la sessione di controllo attiva e rilasciare lo stato di emulazione Playwright/CDP senza riavviare l'intero gateway. +- override obsoleti di viewport / dark mode / locale / offline su profili solo attach o CDP remoti → esegui `openclaw browser stop --browser-profile ` per chiudere la sessione di controllo attiva e rilasciare lo stato di emulazione Playwright/CDP senza riavviare l'intero Gateway. Correlati: - [/tools/browser-linux-troubleshooting](/it/tools/browser-linux-troubleshooting) - [/tools/browser](/it/tools/browser) -## Se hai aggiornato e qualcosa si è improvvisamente rotto +## Se hai aggiornato e qualcosa si è rotto improvvisamente -La maggior parte dei problemi dopo un aggiornamento dipende da derive di configurazione o da impostazioni predefinite più rigide che ora vengono applicate. +La maggior parte dei problemi dopo un aggiornamento è dovuta a deriva della configurazione o a impostazioni predefinite più rigide ora applicate. ### 1) Il comportamento di auth e override URL è cambiato @@ -426,14 +451,14 @@ openclaw config get gateway.auth.mode Cosa controllare: - Se `gateway.mode=remote`, le chiamate CLI potrebbero puntare al remoto mentre il tuo servizio locale funziona correttamente. -- Le chiamate esplicite con `--url` non fanno fallback sulle credenziali memorizzate. +- Le chiamate esplicite con `--url` non usano fallback alle credenziali memorizzate. Firme comuni: - `gateway connect failed:` → target URL errato. - `unauthorized` → endpoint raggiungibile ma auth errata. -### 2) I guardrail su bind e auth sono più rigidi +### 2) I guardrail di bind e auth sono più rigidi ```bash openclaw config get gateway.bind @@ -445,13 +470,13 @@ openclaw logs --follow Cosa controllare: -- I bind non loopback (`lan`, `tailnet`, `custom`) richiedono un percorso auth valido per il gateway: auth con token/password condivisi, oppure un deployment `trusted-proxy` non loopback configurato correttamente. -- Vecchie chiavi come `gateway.token` non sostituiscono `gateway.auth.token`. +- I bind non loopback (`lan`, `tailnet`, `custom`) richiedono un percorso auth Gateway valido: auth con token/password condivisi, oppure un deployment `trusted-proxy` non loopback configurato correttamente. +- Chiavi vecchie come `gateway.token` non sostituiscono `gateway.auth.token`. Firme comuni: -- `refusing to bind gateway ... without auth` → bind non loopback senza un percorso auth valido per il gateway. -- `RPC probe: failed` mentre il runtime è in esecuzione → gateway attivo ma inaccessibile con l'auth/url attuale. +- `refusing to bind gateway ... without auth` → bind non loopback senza un percorso auth Gateway valido. +- `Connectivity probe: failed` mentre il runtime è in esecuzione → Gateway attivo ma inaccessibile con auth/URL correnti. ### 3) Lo stato di pairing e identità del dispositivo è cambiato @@ -464,15 +489,15 @@ openclaw doctor Cosa controllare: -- Approvazioni dispositivo in sospeso per dashboard/nodi. -- Approvazioni di pairing DM in sospeso dopo modifiche a policy o identità. +- Approvazioni dispositivo in sospeso per dashboard/Node. +- Approvazioni pairing DM in sospeso dopo modifiche di policy o identità. Firme comuni: -- `device identity required` → auth del dispositivo non soddisfatta. +- `device identity required` → auth dispositivo non soddisfatta. - `pairing required` → mittente/dispositivo deve essere approvato. -Se la configurazione del servizio e il runtime continuano a non corrispondere dopo i controlli, reinstalla i metadati del servizio dallo stesso profilo/directory di stato: +Se la configurazione del servizio e il runtime continuano a non corrispondere dopo i controlli, reinstalla i metadati del servizio dalla stessa directory di profilo/stato: ```bash openclaw gateway install --force diff --git a/docs/it/help/faq.md b/docs/it/help/faq.md index e79230cc5..413d0aaa2 100644 --- a/docs/it/help/faq.md +++ b/docs/it/help/faq.md @@ -1,21 +1,21 @@ --- read_when: - - Rispondere alle domande comuni su configurazione, installazione, onboarding o supporto di runtime - - Smistare i problemi segnalati dagli utenti prima di un debug più approfondito -summary: Domande frequenti sulla configurazione, l'impostazione e l'utilizzo di OpenClaw + - Risposte alle domande comuni su configurazione iniziale, installazione, onboarding o supporto runtime + - Triage dei problemi segnalati dagli utenti prima di un debug più approfondito +summary: Domande frequenti sulla configurazione, l'impostazione e l'uso di OpenClaw title: FAQ x-i18n: - generated_at: "2026-04-19T08:09:40Z" + generated_at: "2026-04-20T08:31:19Z" model: gpt-5.4 provider: openai - source_hash: f569fb0412797314a11c41a1bbfa14f5892d2d368544fa67800823a6457000e6 + source_hash: ae8efda399e34f59f22f6ea8ce218eaf7b872e4117d8596ec19c09891d70813b source_path: help/faq.md workflow: 15 --- # FAQ -Risposte rapide più una risoluzione dei problemi più approfondita per configurazioni reali (sviluppo locale, VPS, multi-agent, OAuth/chiavi API, failover dei modelli). Per la diagnostica di runtime, vedi [Risoluzione dei problemi](/it/gateway/troubleshooting). Per il riferimento completo della configurazione, vedi [Configurazione](/it/gateway/configuration). +Risposte rapide più una risoluzione più approfondita dei problemi per configurazioni reali (sviluppo locale, VPS, multi-agent, OAuth/chiavi API, failover dei modelli). Per la diagnostica runtime, vedi [Risoluzione dei problemi](/it/gateway/troubleshooting). Per il riferimento completo della configurazione, vedi [Configurazione](/it/gateway/configuration). ## I primi 60 secondi se qualcosa non funziona @@ -25,7 +25,7 @@ Risposte rapide più una risoluzione dei problemi più approfondita per configur openclaw status ``` - Riepilogo locale rapido: OS + aggiornamento, raggiungibilità del gateway/servizio, agenti/sessioni, configurazione del provider + problemi di runtime (quando il gateway è raggiungibile). + Riepilogo locale rapido: OS + aggiornamento, raggiungibilità del gateway/servizio, agent/sessioni, configurazione del provider + problemi runtime (quando il gateway è raggiungibile). 2. **Report condivisibile (sicuro da condividere)** @@ -33,23 +33,23 @@ Risposte rapide più una risoluzione dei problemi più approfondita per configur openclaw status --all ``` - Diagnosi in sola lettura con coda dei log (token oscurati). + Diagnostica in sola lettura con coda dei log (token oscurati). -3. **Stato del demone + della porta** +3. **Stato del demone + porta** ```bash openclaw gateway status ``` - Mostra il runtime del supervisore rispetto alla raggiungibilità RPC, l'URL di destinazione della sonda e quale configurazione ha probabilmente usato il servizio. + Mostra il runtime del supervisore rispetto alla raggiungibilità RPC, l'URL di destinazione del probe e quale configurazione probabilmente ha usato il servizio. -4. **Sonde approfondite** +4. **Probe approfonditi** ```bash openclaw status --deep ``` - Esegue una sonda live sullo stato di salute del gateway, incluse le sonde dei canali quando supportate + Esegue un probe live dello stato di salute del gateway, inclusi i probe dei canali quando supportati (richiede un gateway raggiungibile). Vedi [Health](/it/gateway/health). 5. **Segui l'ultimo log** @@ -78,7 +78,7 @@ Risposte rapide più una risoluzione dei problemi più approfondita per configur ```bash openclaw health --json - openclaw health --verbose # mostra l'URL di destinazione + il percorso della configurazione in caso di errori + openclaw health --verbose # mostra l'URL di destinazione + il percorso della config in caso di errori ``` Chiede al gateway in esecuzione uno snapshot completo (solo WS). Vedi [Health](/it/gateway/health). @@ -86,30 +86,30 @@ Risposte rapide più una risoluzione dei problemi più approfondita per configur ## Avvio rapido e configurazione iniziale - + Usa un agente AI locale che possa **vedere la tua macchina**. È molto più efficace che chiedere - su Discord, perché la maggior parte dei casi di "sono bloccato" sono **problemi locali di configurazione o ambiente** che - gli aiutanti remoti non possono ispezionare. + su Discord, perché la maggior parte dei casi "sono bloccato" sono **problemi locali di configurazione o ambiente** che + chi aiuta da remoto non può ispezionare. - **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/) - **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/) - Questi strumenti possono leggere il repository, eseguire comandi, ispezionare i log e aiutarti a sistemare - la configurazione a livello di macchina (PATH, servizi, permessi, file di autenticazione). Fornisci loro il **checkout completo del sorgente** tramite + Questi strumenti possono leggere il repo, eseguire comandi, ispezionare i log e aiutarti a correggere la configurazione + a livello di macchina (PATH, servizi, permessi, file di autenticazione). Fornisci loro il **checkout completo del sorgente** tramite l'installazione hackable (git): ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Questo installa OpenClaw **da un checkout git**, così l'agente può leggere codice + documentazione e - ragionare sulla versione esatta che stai eseguendo. Puoi sempre tornare alla versione stabile più avanti + Questo installa OpenClaw **da un checkout git**, così l'agente può leggere il codice + la documentazione e + ragionare sulla versione esatta che stai eseguendo. Puoi sempre tornare alla versione stabile in seguito rieseguendo l'installer senza `--install-method git`. - Suggerimento: chiedi all'agente di **pianificare e supervisionare** la correzione (passo dopo passo), poi eseguire solo i - comandi necessari. Così le modifiche restano piccole e più facili da verificare. + Suggerimento: chiedi all'agente di **pianificare e supervisionare** la correzione (passo dopo passo), quindi eseguire solo i + comandi necessari. Così le modifiche restano piccole e più facili da controllare. - Se scopri un bug reale o una correzione, apri un issue su GitHub o invia una PR: + Se scopri un vero bug o una correzione, apri un issue su GitHub o invia una PR: [https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues) [https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls) @@ -125,7 +125,7 @@ Risposte rapide più una risoluzione dei problemi più approfondita per configur - `openclaw status`: snapshot rapido dello stato di salute di gateway/agente + configurazione di base. - `openclaw models status`: controlla l'autenticazione del provider + la disponibilità dei modelli. - - `openclaw doctor`: valida e ripara i problemi comuni di configurazione/stato. + - `openclaw doctor`: convalida e ripara i problemi comuni di configurazione/stato. Altri controlli CLI utili: `openclaw status --all`, `openclaw logs --follow`, `openclaw gateway status`, `openclaw health --verbose`. @@ -135,32 +135,32 @@ Risposte rapide più una risoluzione dei problemi più approfondita per configur - - Motivi comuni di salto di Heartbeat: + + Motivi comuni per cui Heartbeat viene saltato: - `quiet-hours`: fuori dalla finestra configurata di ore attive - `empty-heartbeat-file`: `HEARTBEAT.md` esiste ma contiene solo una struttura vuota o solo intestazioni - - `no-tasks-due`: la modalità attività di `HEARTBEAT.md` è attiva ma nessuno degli intervalli delle attività è ancora in scadenza - - `alerts-disabled`: tutta la visibilità di heartbeat è disabilitata (`showOk`, `showAlerts` e `useIndicator` sono tutti disattivati) + - `no-tasks-due`: la modalità attività di `HEARTBEAT.md` è attiva ma nessuno degli intervalli delle attività è ancora scaduto + - `alerts-disabled`: tutta la visibilità di Heartbeat è disabilitata (`showOk`, `showAlerts` e `useIndicator` sono tutti disattivati) - In modalità attività, i timestamp di scadenza vengono avanzati solo dopo che - un'esecuzione reale di heartbeat è stata completata. Le esecuzioni saltate non contrassegnano le attività come completate. + In modalità attività, i timestamp di scadenza avanzano solo dopo che una vera esecuzione di Heartbeat + viene completata. Le esecuzioni saltate non segnano le attività come completate. Documentazione: [Heartbeat](/it/gateway/heartbeat), [Automazione e attività](/it/automation). - - Il repository consiglia di eseguire dal sorgente e usare l'onboarding: + + Il repo consiglia di eseguire dal sorgente e usare l'onboarding: ```bash curl -fsSL https://openclaw.ai/install.sh | bash openclaw onboard --install-daemon ``` - La procedura guidata può anche creare automaticamente le risorse UI. Dopo l'onboarding, in genere esegui il Gateway sulla porta **18789**. + La procedura guidata può anche compilare automaticamente le risorse UI. Dopo l'onboarding, in genere esegui il Gateway sulla porta **18789**. - Dal sorgente (contributori/sviluppo): + Dal sorgente (collaboratori/sviluppo): ```bash git clone https://github.com/openclaw/openclaw.git @@ -171,7 +171,7 @@ Risposte rapide più una risoluzione dei problemi più approfondita per configur openclaw onboard ``` - Se non hai ancora un'installazione globale, eseguilo tramite `pnpm openclaw onboard`. + Se non hai ancora un'installazione globale, eseguila tramite `pnpm openclaw onboard`. @@ -179,81 +179,81 @@ Risposte rapide più una risoluzione dei problemi più approfondita per configur La procedura guidata apre il browser con un URL della dashboard pulito (senza token) subito dopo l'onboarding e stampa anche il link nel riepilogo. Tieni aperta quella scheda; se non si è avviata, copia/incolla l'URL stampato sulla stessa macchina. - + **Localhost (stessa macchina):** - Apri `http://127.0.0.1:18789/`. - - Se richiede autenticazione con segreto condiviso, incolla il token o la password configurati nelle impostazioni della Control UI. + - Se chiede l'autenticazione con segreto condiviso, incolla il token o la password configurati nelle impostazioni della Control UI. - Origine del token: `gateway.auth.token` (oppure `OPENCLAW_GATEWAY_TOKEN`). - Origine della password: `gateway.auth.password` (oppure `OPENCLAW_GATEWAY_PASSWORD`). - Se non è ancora configurato alcun segreto condiviso, genera un token con `openclaw doctor --generate-gateway-token`. **Non su localhost:** - - **Tailscale Serve** (consigliato): mantieni il bind su loopback, esegui `openclaw gateway --tailscale serve`, apri `https:///`. Se `gateway.auth.allowTailscale` è `true`, le intestazioni di identità soddisfano l'autenticazione di Control UI/WebSocket (senza incollare il segreto condiviso, assumendo un host gateway attendibile); le API HTTP richiedono comunque l'autenticazione con segreto condiviso a meno che tu non usi deliberatamente `none` per ingress privato o l'autenticazione HTTP di trusted-proxy. - I tentativi concorrenti errati di autenticazione Serve dallo stesso client vengono serializzati prima che il limitatore delle autenticazioni fallite li registri, quindi il secondo tentativo errato può già mostrare `retry later`. - - **Bind tailnet**: esegui `openclaw gateway --bind tailnet --token ""` (o configura l'autenticazione con password), apri `http://:18789/`, quindi incolla il segreto condiviso corrispondente nelle impostazioni della dashboard. - - **Reverse proxy con gestione dell'identità**: mantieni il Gateway dietro un trusted-proxy non loopback, configura `gateway.auth.mode: "trusted-proxy"`, quindi apri l'URL del proxy. - - **Tunnel SSH**: `ssh -N -L 18789:127.0.0.1:18789 user@host` quindi apri `http://127.0.0.1:18789/`. L'autenticazione con segreto condiviso si applica comunque attraverso il tunnel; se richiesto, incolla il token o la password configurati. + - **Tailscale Serve** (consigliato): mantieni il bind loopback, esegui `openclaw gateway --tailscale serve`, apri `https:///`. Se `gateway.auth.allowTailscale` è `true`, gli header di identità soddisfano l'autenticazione di Control UI/WebSocket (senza incollare un segreto condiviso, assumendo un host gateway attendibile); le API HTTP richiedono comunque l'autenticazione con segreto condiviso a meno che tu non usi deliberatamente `none` per private-ingress o l'autenticazione HTTP trusted-proxy. + I tentativi contemporanei non validi di autenticazione Serve dallo stesso client vengono serializzati prima che il limitatore delle autenticazioni fallite li registri, quindi il secondo tentativo errato può già mostrare `retry later`. + - **Bind tailnet**: esegui `openclaw gateway --bind tailnet --token ""` (oppure configura l'autenticazione con password), apri `http://:18789/`, quindi incolla il segreto condiviso corrispondente nelle impostazioni della dashboard. + - **Proxy inverso con riconoscimento dell'identità**: mantieni il Gateway dietro un trusted proxy non-loopback, configura `gateway.auth.mode: "trusted-proxy"`, quindi apri l'URL del proxy. + - **Tunnel SSH**: `ssh -N -L 18789:127.0.0.1:18789 user@host` quindi apri `http://127.0.0.1:18789/`. L'autenticazione con segreto condiviso si applica comunque attraverso il tunnel; incolla il token o la password configurati se richiesto. Vedi [Dashboard](/web/dashboard) e [Superfici web](/web) per i dettagli su modalità di bind e autenticazione. - + Controllano livelli diversi: - `approvals.exec`: inoltra i prompt di approvazione alle destinazioni di chat - `channels..execApprovals`: fa sì che quel canale agisca come client di approvazione nativo per le approvazioni exec - La policy exec dell'host rimane comunque il vero punto di controllo dell'approvazione. La configurazione della chat controlla solo dove - compaiono i prompt di approvazione e come le persone possono rispondere. + Il criterio exec dell'host resta comunque il vero gate di approvazione. La configurazione chat controlla solo dove compaiono i prompt di approvazione + e come le persone possono rispondere. - Nella maggior parte delle configurazioni **non** ti servono entrambi: + Nella maggior parte delle configurazioni **non** ti servono entrambe: - Se la chat supporta già comandi e risposte, `/approve` nella stessa chat funziona tramite il percorso condiviso. - - Se un canale nativo supportato può dedurre in modo sicuro gli approvatori, OpenClaw ora abilita automaticamente le approvazioni native DM-first quando `channels..execApprovals.enabled` non è impostato o è `"auto"`. - - Quando sono disponibili schede/pulsanti di approvazione nativi, quella UI nativa è il percorso principale; l'agente dovrebbe includere un comando manuale `/approve` solo se il risultato dello strumento dice che le approvazioni in chat non sono disponibili o che l'approvazione manuale è l'unica opzione. + - Se un canale nativo supportato può dedurre in modo sicuro gli approvatori, OpenClaw ora abilita automaticamente le approvazioni native DM-first quando `channels..execApprovals.enabled` non è impostato oppure è `"auto"`. + - Quando sono disponibili card/pulsanti di approvazione nativi, quella UI nativa è il percorso principale; l'agente dovrebbe includere un comando manuale `/approve` solo se il risultato dello strumento indica che le approvazioni in chat non sono disponibili o che l'approvazione manuale è l'unico percorso. - Usa `approvals.exec` solo quando i prompt devono essere inoltrati anche ad altre chat o a stanze operative esplicite. - - Usa `channels..execApprovals.target: "channel"` o `"both"` solo quando vuoi esplicitamente che i prompt di approvazione vengano pubblicati di nuovo nella stanza/topic di origine. - - Le approvazioni dei Plugin sono ancora separate: usano per impostazione predefinita `/approve` nella stessa chat, inoltro opzionale `approvals.plugin` e solo alcuni canali nativi mantengono anche la gestione nativa dell'approvazione dei plugin. + - Usa `channels..execApprovals.target: "channel"` oppure `"both"` solo quando vuoi esplicitamente che i prompt di approvazione vengano pubblicati di nuovo nella stanza/topic di origine. + - Le approvazioni dei Plugin sono ancora separate: usano per impostazione predefinita `/approve` nella stessa chat, l'inoltro opzionale `approvals.plugin`, e solo alcuni canali nativi mantengono anche la gestione nativa delle approvazioni dei plugin. - In breve: l'inoltro serve per il routing, la configurazione del client nativo serve per una UX più ricca e specifica del canale. + Versione breve: l'inoltro serve per il routing, la configurazione del client nativo serve per una UX specifica del canale più ricca. Vedi [Approvazioni exec](/it/tools/exec-approvals). - + È richiesto Node **>= 22**. `pnpm` è consigliato. Bun **non è consigliato** per il Gateway. Sì. Il Gateway è leggero: la documentazione indica **512MB-1GB di RAM**, **1 core** e circa **500MB** - di disco come sufficienti per uso personale, e nota che un **Raspberry Pi 4 può eseguirlo**. + di disco come sufficienti per un uso personale, e nota che un **Raspberry Pi 4 può eseguirlo**. - Se vuoi più margine (log, contenuti multimediali, altri servizi), sono consigliati **2GB**, - ma non è un minimo rigido. + Se vuoi più margine (log, media, altri servizi), **2GB sono consigliati**, ma + non sono un minimo rigido. - Suggerimento: un piccolo Pi/VPS può ospitare il Gateway, e puoi associare dei **Node** al tuo laptop/telefono per - schermo/fotocamera/canvas locali o esecuzione di comandi. Vedi [Nodes](/it/nodes). + Suggerimento: un piccolo Pi/VPS può ospitare il Gateway, e puoi associare **Node** sul tuo laptop/telefono per + schermo/fotocamera/canvas locale o esecuzione di comandi. Vedi [Nodes](/it/nodes). - In breve: funziona, ma aspettati qualche imperfezione. + Versione breve: funziona, ma aspettati qualche spigolosità. - - Usa un OS **64-bit** e mantieni Node >= 22. - - Preferisci l'installazione **hackable (git)** così puoi vedere i log e aggiornare rapidamente. + - Usa un OS **a 64 bit** e mantieni Node >= 22. + - Preferisci l'**installazione hackable (git)** così puoi vedere i log e aggiornare rapidamente. - Inizia senza canali/Skills, poi aggiungili uno alla volta. - - Se incontri strani problemi binari, di solito si tratta di un problema di **compatibilità ARM**. + - Se incontri strani problemi binari, di solito è un problema di **compatibilità ARM**. Documentazione: [Linux](/it/platforms/linux), [Installazione](/it/install). - + Quella schermata dipende dal fatto che il Gateway sia raggiungibile e autenticato. La TUI invia anche - automaticamente "Wake up, my friend!" al primo avvio. Se vedi quella riga **senza risposta** + automaticamente "Wake up, my friend!" al primo avvio completo. Se vedi quella riga senza **nessuna risposta** e i token restano a 0, l'agente non è mai stato eseguito. 1. Riavvia il Gateway: @@ -287,39 +287,39 @@ Risposte rapide più una risoluzione dei problemi più approfondita per configur stato del canale) purché tu copi **entrambe** le posizioni: 1. Installa OpenClaw sulla nuova macchina. - 2. Copia `$OPENCLAW_STATE_DIR` (predefinita: `~/.openclaw`) dalla vecchia macchina. + 2. Copia `$OPENCLAW_STATE_DIR` (predefinito: `~/.openclaw`) dalla vecchia macchina. 3. Copia il tuo workspace (predefinito: `~/.openclaw/workspace`). 4. Esegui `openclaw doctor` e riavvia il servizio Gateway. - Questo preserva configurazione, profili di autenticazione, credenziali di WhatsApp, sessioni e memoria. Se sei in + Questo preserva configurazione, profili di autenticazione, credenziali WhatsApp, sessioni e memoria. Se sei in modalità remota, ricorda che l'host del gateway possiede l'archivio delle sessioni e il workspace. - **Importante:** se esegui solo il commit/push del tuo workspace su GitHub, stai eseguendo il backup - di **memoria + file bootstrap**, ma **non** della cronologia delle sessioni o dell'autenticazione. Questi si trovano + **Importante:** se esegui solo commit/push del tuo workspace su GitHub, stai facendo il backup + di **memoria + file di bootstrap**, ma **non** della cronologia delle sessioni né dell'autenticazione. Questi elementi si trovano sotto `~/.openclaw/` (per esempio `~/.openclaw/agents//sessions/`). - Correlati: [Migrazione](/it/install/migrating), [Dove si trova tutto sul disco](#where-things-live-on-disk), + Correlati: [Migrazione](/it/install/migrating), [Dove si trova tutto sul disco](#dove-si-trova-tutto-sul-disco), [Workspace dell'agente](/it/concepts/agent-workspace), [Doctor](/it/gateway/doctor), [Modalità remota](/it/gateway/remote). - + Controlla il changelog su GitHub: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - Le voci più recenti sono in alto. Se la sezione in cima è contrassegnata come **Unreleased**, la successiva sezione - datata è l'ultima versione distribuita. Le voci sono raggruppate in **Highlights**, **Changes** e - **Fixes** (più sezioni docs/altre quando necessario). + Le voci più recenti sono in cima. Se la sezione in cima è contrassegnata come **Unreleased**, la successiva + sezione con data è l'ultima versione distribuita. Le voci sono raggruppate in **Highlights**, **Changes** e + **Fixes** (più sezioni docs/altro quando necessario). - Alcune connessioni Comcast/Xfinity bloccano in modo errato `docs.openclaw.ai` tramite Xfinity - Advanced Security. Disattivala oppure aggiungi `docs.openclaw.ai` all'allowlist, poi riprova. - Aiutaci a sbloccarlo segnalando qui: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). + Alcune connessioni Comcast/Xfinity bloccano erroneamente `docs.openclaw.ai` tramite Xfinity + Advanced Security. Disattivalo oppure aggiungi `docs.openclaw.ai` all'allowlist, quindi riprova. + Aiutaci a sbloccarlo segnalandolo qui: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). - Se ancora non riesci a raggiungere il sito, la documentazione è duplicata su GitHub: + Se ancora non riesci a raggiungere il sito, la documentazione è disponibile in mirror su GitHub: [https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs) @@ -332,19 +332,19 @@ Risposte rapide più una risoluzione dei problemi più approfondita per configur Di solito, una release stable arriva prima su **beta**, poi un passaggio esplicito di promozione sposta quella stessa versione su `latest`. I maintainer possono anche - pubblicare direttamente su `latest` quando necessario. Per questo beta e stable possono + pubblicare direttamente su `latest` quando necessario. Ecco perché beta e stable possono puntare alla **stessa versione** dopo la promozione. Vedi cosa è cambiato: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - Per i comandi di installazione rapida e la differenza tra beta e dev, vedi l'accordion qui sotto. + Per i comandi di installazione rapidi e la differenza tra beta e dev, vedi l'accordion qui sotto. - **Beta** è il dist-tag npm `beta` (può corrispondere a `latest` dopo la promozione). - **Dev** è la head in movimento di `main` (git); quando viene pubblicata, usa il dist-tag npm `dev`. + **Beta** è il npm dist-tag `beta` (può coincidere con `latest` dopo la promozione). + **Dev** è la head mobile di `main` (git); quando viene pubblicata, usa il npm dist-tag `dev`. Comandi rapidi (macOS/Linux): @@ -356,14 +356,14 @@ Risposte rapide più una risoluzione dei problemi più approfondita per configur curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Installer Windows (PowerShell): + Installer per Windows (PowerShell): [https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1) - Maggiori dettagli: [Canali di sviluppo](/it/install/development-channels) e [Flag dell'installer](/it/install/installer). + Più dettagli: [Canali di sviluppo](/it/install/development-channels) e [Flag dell'installer](/it/install/installer). - + Due opzioni: 1. **Canale dev (checkout git):** @@ -380,9 +380,9 @@ Risposte rapide più una risoluzione dei problemi più approfondita per configur curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - In questo modo ottieni un repository locale che puoi modificare, quindi aggiornare tramite git. + In questo modo ottieni un repo locale che puoi modificare, poi aggiornare tramite git. - Se preferisci un clone pulito manualmente, usa: + Se preferisci fare manualmente un clone pulito, usa: ```bash git clone https://github.com/openclaw/openclaw.git @@ -396,14 +396,14 @@ Risposte rapide più una risoluzione dei problemi più approfondita per configur - - Guida approssimativa: + + Indicativamente: - **Installazione:** 2-5 minuti - **Onboarding:** 5-15 minuti a seconda di quanti canali/modelli configuri - Se si blocca, usa [Installer bloccato](#quick-start-and-first-run-setup) - e il ciclo rapido di debug in [Sono bloccato](#quick-start-and-first-run-setup). + Se si blocca, usa [Installer bloccato](#avvio-rapido-e-configurazione-iniziale) + e il ciclo rapido di debug in [Sono bloccato](#avvio-rapido-e-configurazione-iniziale). @@ -414,7 +414,7 @@ Risposte rapide più una risoluzione dei problemi più approfondita per configur curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose ``` - Installazione beta con output dettagliato: + Installazione beta con verbose: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose @@ -439,15 +439,15 @@ Risposte rapide più una risoluzione dei problemi più approfondita per configur - + Due problemi comuni su Windows: - **1) errore npm spawn git / git non trovato** + **1) errore npm spawn git / git not found** - Installa **Git for Windows** e assicurati che `git` sia nel tuo PATH. - Chiudi e riapri PowerShell, poi riesegui l'installer. - **2) openclaw non è riconosciuto dopo l'installazione** + **2) openclaw is not recognized dopo l'installazione** - La cartella bin globale di npm non è nel PATH. - Controlla il percorso: @@ -456,7 +456,7 @@ Risposte rapide più una risoluzione dei problemi più approfondita per configur npm config get prefix ``` - - Aggiungi quella directory al PATH utente (su Windows non serve il suffisso `\bin`; sulla maggior parte dei sistemi è `%AppData%\npm`). + - Aggiungi quella directory al PATH utente (su Windows non serve il suffisso `\bin`; nella maggior parte dei sistemi è `%AppData%\npm`). - Chiudi e riapri PowerShell dopo aver aggiornato il PATH. Se vuoi la configurazione più fluida su Windows, usa **WSL2** invece di Windows nativo. @@ -464,13 +464,13 @@ Risposte rapide più una risoluzione dei problemi più approfondita per configur - - Di solito si tratta di una mancata corrispondenza della code page della console nelle shell Windows native. + + Di solito si tratta di una mancata corrispondenza del code page della console nelle shell Windows native. Sintomi: - - l'output di `system.run`/`exec` visualizza il cinese come testo corrotto - - lo stesso comando appare corretto in un altro profilo del terminale + - l'output di `system.run`/`exec` mostra il cinese come mojibake + - lo stesso comando appare correttamente in un altro profilo terminale Soluzione rapida in PowerShell: @@ -487,21 +487,21 @@ Risposte rapide più una risoluzione dei problemi più approfondita per configur openclaw gateway restart ``` - Se riesci ancora a riprodurre questo problema sull'ultima versione di OpenClaw, seguilo/segnalalo qui: + Se continui a riprodurre il problema nell'ultima versione di OpenClaw, traccialo/segnalalo in: - [Issue #30640](https://github.com/openclaw/openclaw/issues/30640) - - Usa l'**installazione hackable (git)** così avrai localmente l'intero sorgente e la documentazione, poi chiedi - al tuo bot (o a Claude/Codex) _da quella cartella_ in modo che possa leggere il repository e rispondere con precisione. + + Usa l'**installazione hackable (git)** così avrai il sorgente completo e la documentazione in locale, poi fai la domanda + al tuo bot (o a Claude/Codex) _da quella cartella_ in modo che possa leggere il repo e rispondere con precisione. ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Maggiori dettagli: [Installazione](/it/install) e [Flag dell'installer](/it/install/installer). + Più dettagli: [Installazione](/it/install) e [Flag dell'installer](/it/install/installer). @@ -509,7 +509,7 @@ Risposte rapide più una risoluzione dei problemi più approfondita per configur Risposta breve: segui la guida Linux, poi esegui l'onboarding. - Percorso rapido Linux + installazione del servizio: [Linux](/it/platforms/linux). - - Guida completa: [Per iniziare](/it/start/getting-started). + - Procedura completa: [Per iniziare](/it/start/getting-started). - Installer + aggiornamenti: [Installazione e aggiornamenti](/it/install/updating). @@ -530,13 +530,13 @@ Risposte rapide più una risoluzione dei problemi più approfondita per configur - [Hetzner](/it/install/hetzner) - [exe.dev](/it/install/exe-dev) - Come funziona nel cloud: il **Gateway viene eseguito sul server**, e tu vi accedi - dal laptop/telefono tramite la Control UI (o Tailscale/SSH). Il tuo stato + workspace - risiedono sul server, quindi considera l'host come fonte di verità ed eseguine il backup. + Come funziona nel cloud: il **Gateway viene eseguito sul server** e vi accedi + dal tuo laptop/telefono tramite la Control UI (o Tailscale/SSH). Il tuo stato + workspace + si trovano sul server, quindi tratta l'host come fonte di verità ed esegui il backup. - Puoi associare dei **Node** (Mac/iOS/Android/headless) a quel Gateway cloud per accedere a - schermo/fotocamera/canvas locali o eseguire comandi sul laptop mantenendo il - Gateway nel cloud. + Puoi associare **Node** (Mac/iOS/Android/headless) a quel Gateway cloud per accedere + a schermo/fotocamera/canvas locali o eseguire comandi sul tuo laptop mantenendo + il Gateway nel cloud. Hub: [Piattaforme](/it/platforms). Accesso remoto: [Gateway remoto](/it/gateway/remote). Nodes: [Nodes](/it/nodes), [CLI Nodes](/cli/nodes). @@ -544,8 +544,8 @@ Risposte rapide più una risoluzione dei problemi più approfondita per configur - Risposta breve: **possibile, non consigliato**. Il flusso di aggiornamento può riavviare il - Gateway (il che interrompe la sessione attiva), può richiedere un checkout git pulito e + Risposta breve: **possibile, ma non consigliato**. Il flusso di aggiornamento può riavviare il + Gateway (interrompendo la sessione attiva), può richiedere un checkout git pulito e può chiedere conferma. Più sicuro: eseguire gli aggiornamenti da una shell come operatore. Usa la CLI: @@ -558,7 +558,7 @@ Risposte rapide più una risoluzione dei problemi più approfondita per configur openclaw update --no-restart ``` - Se devi automatizzarlo da un agente: + Se devi automatizzare da un agente: ```bash openclaw update --yes --no-restart @@ -569,35 +569,35 @@ Risposte rapide più una risoluzione dei problemi più approfondita per configur - + `openclaw onboard` è il percorso di configurazione consigliato. In **modalità locale** ti guida attraverso: - - **Configurazione di modello/autenticazione** (OAuth del provider, chiavi API, setup-token di Anthropic, più opzioni per modelli locali come LM Studio) - - Posizione del **workspace** + file bootstrap + - **Configurazione modello/autenticazione** (OAuth del provider, chiavi API, setup-token Anthropic, più opzioni per modelli locali come LM Studio) + - Posizione del **workspace** + file di bootstrap - **Impostazioni del Gateway** (bind/porta/autenticazione/tailscale) - - **Canali** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, più plugin di canale bundled come QQ Bot) + - **Canali** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, più plugin di canale inclusi come QQ Bot) - **Installazione del demone** (LaunchAgent su macOS; unità utente systemd su Linux/WSL2) - **Controlli di salute** e selezione delle **Skills** - Avvisa anche se il modello configurato è sconosciuto o manca l'autenticazione. + Inoltre avvisa se il modello configurato è sconosciuto o manca l'autenticazione. - + No. Puoi eseguire OpenClaw con **chiavi API** (Anthropic/OpenAI/altri) oppure con **modelli solo locali** così i tuoi dati restano sul tuo dispositivo. Gli abbonamenti (Claude - Pro/Max o OpenAI Codex) sono modi facoltativi per autenticare questi provider. + Pro/Max o OpenAI Codex) sono modi opzionali per autenticare quei provider. - Per Anthropic in OpenClaw, la suddivisione pratica è: + Per Anthropic in OpenClaw, la distinzione pratica è: - **Chiave API Anthropic**: normale fatturazione API Anthropic - **Autenticazione Claude CLI / abbonamento Claude in OpenClaw**: il personale Anthropic - ci ha detto che questo utilizzo è di nuovo consentito, e OpenClaw considera l'uso di `claude -p` + ci ha detto che questo utilizzo è di nuovo consentito e OpenClaw tratta l'uso di `claude -p` come autorizzato per questa integrazione, a meno che Anthropic non pubblichi una nuova policy - Per host gateway di lunga durata, le chiavi API Anthropic restano comunque la - configurazione più prevedibile. L'OAuth di OpenAI Codex è esplicitamente supportato per strumenti esterni + Per host Gateway di lunga durata, le chiavi API Anthropic restano comunque la configurazione + più prevedibile. L'OAuth di OpenAI Codex è esplicitamente supportato per strumenti esterni come OpenClaw. OpenClaw supporta anche altre opzioni ospitate in stile abbonamento, tra cui @@ -615,22 +615,22 @@ Risposte rapide più una risoluzione dei problemi più approfondita per configur Sì. Il personale di Anthropic ci ha detto che l'uso di Claude CLI nello stile di OpenClaw è di nuovo consentito, quindi - OpenClaw considera autorizzata per questa integrazione l'autenticazione tramite abbonamento Claude e l'uso di `claude -p` - a meno che Anthropic non pubblichi una nuova policy. Se desideri + OpenClaw tratta l'autenticazione con abbonamento Claude e l'uso di `claude -p` come autorizzati + per questa integrazione, a meno che Anthropic non pubblichi una nuova policy. Se vuoi la configurazione lato server più prevedibile, usa invece una chiave API Anthropic. - + Sì. - Il personale di Anthropic ci ha detto che questo utilizzo è di nuovo consentito, quindi OpenClaw considera - autorizzato per questa integrazione il riutilizzo di Claude CLI e l'uso di `claude -p` + Il personale di Anthropic ci ha detto che questo utilizzo è di nuovo consentito, quindi OpenClaw tratta + il riutilizzo di Claude CLI e l'uso di `claude -p` come autorizzati per questa integrazione a meno che Anthropic non pubblichi una nuova policy. - Il setup-token Anthropic è ancora disponibile come percorso token supportato in OpenClaw, ma OpenClaw ora preferisce il riutilizzo di Claude CLI e `claude -p` quando disponibili. - Per carichi di lavoro di produzione o multiutente, l'autenticazione con chiave API Anthropic resta la - scelta più sicura e prevedibile. Se desideri altre opzioni ospitate in stile abbonamento + Il setup-token Anthropic è ancora disponibile come percorso di token supportato in OpenClaw, ma OpenClaw ora preferisce il riutilizzo di Claude CLI e `claude -p` quando disponibili. + Per carichi di lavoro di produzione o multiutente, l'autenticazione con chiave API Anthropic resta comunque la + scelta più sicura e prevedibile. Se vuoi altre opzioni ospitate in stile abbonamento in OpenClaw, vedi [OpenAI](/it/providers/openai), [Qwen / Model Cloud](/it/providers/qwen), [MiniMax](/it/providers/minimax) e [Modelli GLM](/it/providers/glm). @@ -639,33 +639,33 @@ Risposte rapide più una risoluzione dei problemi più approfondita per configur -Questo significa che la tua **quota/limite di velocità Anthropic** è esaurita per la finestra corrente. Se -usi **Claude CLI**, attendi il reset della finestra oppure aggiorna il tuo piano. Se -usi una **chiave API Anthropic**, controlla la console Anthropic -per utilizzo/fatturazione e aumenta i limiti se necessario. +Significa che la tua **quota/limite di velocità Anthropic** è esaurita per la finestra corrente. Se +usi **Claude CLI**, aspetta che la finestra si resetti oppure fai l'upgrade del piano. Se +usi una **chiave API Anthropic**, controlla la Console Anthropic +per uso/fatturazione e aumenta i limiti se necessario. - Se il messaggio è in particolare: + Se il messaggio è specificamente: `Extra usage is required for long context requests`, la richiesta sta tentando di usare - la beta di Anthropic per il contesto 1M (`context1m: true`). Funziona solo quando la tua + la beta del contesto 1M di Anthropic (`context1m: true`). Questo funziona solo quando la tua credenziale è idonea per la fatturazione long-context (fatturazione con chiave API o il percorso di login Claude di OpenClaw con Extra Usage abilitato). - Suggerimento: imposta un **modello di fallback** così OpenClaw può continuare a rispondere mentre un provider è soggetto a limitazione della velocità. + Suggerimento: imposta un **modello di fallback** così OpenClaw può continuare a rispondere mentre un provider è soggetto a rate limit. Vedi [Models](/cli/models), [OAuth](/it/concepts/oauth) e [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/it/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context). - Sì. OpenClaw dispone di un provider bundled **Amazon Bedrock (Converse)**. Con i marker env AWS presenti, OpenClaw può individuare automaticamente il catalogo Bedrock streaming/testo e unirlo come provider implicito `amazon-bedrock`; in alternativa puoi abilitare esplicitamente `plugins.entries.amazon-bedrock.config.discovery.enabled` o aggiungere una voce provider manuale. Vedi [Amazon Bedrock](/it/providers/bedrock) e [Provider di modelli](/it/providers/models). Se preferisci un flusso di chiavi gestito, anche un proxy compatibile con OpenAI davanti a Bedrock resta un'opzione valida. + Sì. OpenClaw include un provider **Amazon Bedrock (Converse)**. Con i marker env AWS presenti, OpenClaw può individuare automaticamente il catalogo Bedrock streaming/testo e unirlo come provider implicito `amazon-bedrock`; altrimenti puoi abilitare esplicitamente `plugins.entries.amazon-bedrock.config.discovery.enabled` o aggiungere una voce provider manuale. Vedi [Amazon Bedrock](/it/providers/bedrock) e [Provider di modelli](/it/providers/models). Se preferisci un flusso con chiavi gestite, anche un proxy compatibile con OpenAI davanti a Bedrock è un'opzione valida. - OpenClaw supporta **OpenAI Code (Codex)** tramite OAuth (accesso ChatGPT). L'onboarding può eseguire il flusso OAuth e imposterà il modello predefinito su `openai-codex/gpt-5.4` quando opportuno. Vedi [Provider di modelli](/it/concepts/model-providers) e [Onboarding (CLI)](/it/start/wizard). + OpenClaw supporta **OpenAI Code (Codex)** tramite OAuth (accesso ChatGPT). L'onboarding può eseguire il flusso OAuth e imposterà il modello predefinito su `openai-codex/gpt-5.4` quando appropriato. Vedi [Provider di modelli](/it/concepts/model-providers) e [Onboarding (CLI)](/it/start/wizard). - OpenClaw gestisce separatamente i due percorsi: + OpenClaw tratta i due percorsi separatamente: - `openai-codex/gpt-5.4` = OAuth ChatGPT/Codex - `openai/gpt-5.4` = API diretta della piattaforma OpenAI @@ -677,21 +677,20 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. - + `openai-codex/*` usa il percorso OAuth Codex, e le sue finestre di quota utilizzabili sono - gestite da OpenAI e dipendono dal piano. In pratica, questi limiti possono differire dall'esperienza - del sito/app ChatGPT, anche quando entrambi sono collegati allo stesso account. + gestite da OpenAI e dipendono dal piano. In pratica, quei limiti possono differire dall'esperienza + del sito/app ChatGPT, anche quando entrambi sono legati allo stesso account. - OpenClaw può mostrare le finestre di utilizzo/quota attualmente visibili del provider in - `openclaw models status`, ma non inventa né normalizza i - diritti del web ChatGPT in accesso diretto API. Se vuoi il percorso diretto di - fatturazione/limiti della piattaforma OpenAI, usa `openai/*` con una chiave API. + OpenClaw può mostrare le finestre di utilizzo/quota del provider attualmente visibili in + `openclaw models status`, ma non inventa né normalizza i diritti del web ChatGPT in accesso API diretto. Se vuoi il percorso diretto di fatturazione/limiti della piattaforma OpenAI, + usa `openai/*` con una chiave API. - + Sì. OpenClaw supporta pienamente **OpenAI Code (Codex) subscription OAuth**. - OpenAI consente esplicitamente l'uso di OAuth in abbonamento in strumenti/flussi di lavoro esterni + OpenAI consente esplicitamente l'uso dell'OAuth di abbonamento in strumenti/workflow esterni come OpenClaw. L'onboarding può eseguire il flusso OAuth per te. Vedi [OAuth](/it/concepts/oauth), [Provider di modelli](/it/concepts/model-providers) e [Onboarding (CLI)](/it/start/wizard). @@ -699,7 +698,7 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. - Gemini CLI usa un **flusso di autenticazione del Plugin**, non un client id o un secret in `openclaw.json`. + Gemini CLI usa un **flusso di autenticazione del plugin**, non un client id o un secret in `openclaw.json`. Passaggi: @@ -709,38 +708,38 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. 2. Abilita il plugin: `openclaw plugins enable google` 3. Accedi: `openclaw models auth login --provider google-gemini-cli --set-default` 4. Modello predefinito dopo l'accesso: `google-gemini-cli/gemini-3-flash-preview` - 5. Se le richieste non riescono, imposta `GOOGLE_CLOUD_PROJECT` o `GOOGLE_CLOUD_PROJECT_ID` sull'host del gateway + 5. Se le richieste falliscono, imposta `GOOGLE_CLOUD_PROJECT` o `GOOGLE_CLOUD_PROJECT_ID` sull'host del gateway - Questo archivia i token OAuth nei profili di autenticazione sull'host del gateway. Dettagli: [Provider di modelli](/it/concepts/model-providers). + Questo memorizza i token OAuth nei profili di autenticazione sull'host del gateway. Dettagli: [Provider di modelli](/it/concepts/model-providers). - - Di solito no. OpenClaw richiede un contesto ampio + una sicurezza robusta; i modelli piccoli troncano e lasciano passare contenuti. Se proprio devi, esegui localmente la build del modello **più grande** che puoi (LM Studio) e vedi [/gateway/local-models](/it/gateway/local-models). I modelli più piccoli/quantizzati aumentano il rischio di prompt injection - vedi [Sicurezza](/it/gateway/security). + + Di solito no. OpenClaw richiede contesto ampio + sicurezza robusta; i modelli piccoli troncano e lasciano trapelare. Se proprio devi, esegui la build del modello **più grande** che puoi in locale (LM Studio) e vedi [/gateway/local-models](/it/gateway/local-models). I modelli più piccoli/quantizzati aumentano il rischio di prompt injection - vedi [Sicurezza](/it/gateway/security). - Scegli endpoint vincolati alla regione. OpenRouter espone opzioni ospitate negli Stati Uniti per MiniMax, Kimi e GLM; scegli la variante ospitata negli Stati Uniti per mantenere i dati nella regione. Puoi comunque elencare Anthropic/OpenAI insieme a questi usando `models.mode: "merge"` così i fallback restano disponibili rispettando il provider regionalizzato che selezioni. + Scegli endpoint fissati per regione. OpenRouter espone opzioni ospitate negli Stati Uniti per MiniMax, Kimi e GLM; scegli la variante ospitata negli Stati Uniti per mantenere i dati nella regione. Puoi comunque elencare Anthropic/OpenAI insieme a questi usando `models.mode: "merge"` così i fallback restano disponibili rispettando al tempo stesso il provider regionalizzato che selezioni. - No. OpenClaw funziona su macOS o Linux (Windows tramite WSL2). Un Mac mini è facoltativo: alcune persone - ne acquistano uno come host sempre acceso, ma va bene anche un piccolo VPS, un server domestico o un dispositivo della classe Raspberry Pi. + No. OpenClaw gira su macOS o Linux (Windows tramite WSL2). Un Mac mini è opzionale: alcune persone + ne comprano uno come host sempre acceso, ma vanno bene anche un piccolo VPS, un server domestico o una macchina della classe Raspberry Pi. - Ti serve un Mac solo **per strumenti esclusivi di macOS**. Per iMessage, usa [BlueBubbles](/it/channels/bluebubbles) (consigliato): il server BlueBubbles gira su qualsiasi Mac, mentre il Gateway può essere eseguito su Linux o altrove. Se vuoi altri strumenti esclusivi di macOS, esegui il Gateway su un Mac o associa un Node macOS. + Ti serve un Mac **solo per gli strumenti esclusivi di macOS**. Per iMessage, usa [BlueBubbles](/it/channels/bluebubbles) (consigliato) - il server BlueBubbles gira su qualsiasi Mac, e il Gateway può girare su Linux o altrove. Se vuoi altri strumenti esclusivi di macOS, esegui il Gateway su un Mac o associa un Node macOS. Documentazione: [BlueBubbles](/it/channels/bluebubbles), [Nodes](/it/nodes), [Modalità remota Mac](/it/platforms/mac/remote). - Ti serve **un qualsiasi dispositivo macOS** connesso a Messaggi. **Non** deve essere per forza un Mac mini: - va bene qualsiasi Mac. **Usa [BlueBubbles](/it/channels/bluebubbles)** (consigliato) per iMessage: il server BlueBubbles gira su macOS, mentre il Gateway può essere eseguito su Linux o altrove. + Ti serve **un qualsiasi dispositivo macOS** connesso a Messaggi. **Non** deve essere per forza un Mac mini - + va bene qualsiasi Mac. **Usa [BlueBubbles](/it/channels/bluebubbles)** (consigliato) per iMessage - il server BlueBubbles gira su macOS, mentre il Gateway può girare su Linux o altrove. Configurazioni comuni: - Esegui il Gateway su Linux/VPS e il server BlueBubbles su qualsiasi Mac connesso a Messaggi. - - Esegui tutto sul Mac se vuoi la configurazione più semplice su un'unica macchina. + - Esegui tutto sul Mac se vuoi la configurazione più semplice su una singola macchina. Documentazione: [BlueBubbles](/it/channels/bluebubbles), [Nodes](/it/nodes), [Modalità remota Mac](/it/platforms/mac/remote). @@ -748,22 +747,22 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. - Sì. Il **Mac mini può eseguire il Gateway**, e il tuo MacBook Pro può collegarsi come - **Node** (dispositivo complementare). I Node non eseguono il Gateway: forniscono - funzionalità aggiuntive come schermo/fotocamera/canvas e `system.run` su quel dispositivo. + Sì. Il **Mac mini può eseguire il Gateway**, e il tuo MacBook Pro può connettersi come + **Node** (dispositivo companion). I Nodes non eseguono il Gateway: forniscono capacità + aggiuntive come schermo/fotocamera/canvas e `system.run` su quel dispositivo. - Modello comune: + Pattern comune: - Gateway sul Mac mini (sempre acceso). - Il MacBook Pro esegue l'app macOS o un host Node e si associa al Gateway. - - Usa `openclaw nodes status` / `openclaw nodes list` per vederlo. + - Usa `openclaw nodes status` / `openclaw nodes list` per visualizzarlo. Documentazione: [Nodes](/it/nodes), [CLI Nodes](/cli/nodes). - Bun **non è consigliato**. Riscontriamo bug di runtime, soprattutto con WhatsApp e Telegram. + Bun **non è consigliato**. Osserviamo bug runtime, soprattutto con WhatsApp e Telegram. Usa **Node** per gateway stabili. Se vuoi comunque sperimentare con Bun, fallo su un gateway non di produzione @@ -771,20 +770,20 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. - + `channels.telegram.allowFrom` è **l'ID utente Telegram del mittente umano** (numerico). Non è il nome utente del bot. - L'onboarding accetta input `@username` e lo risolve in un ID numerico, ma l'autorizzazione OpenClaw usa solo ID numerici. + La configurazione richiede solo ID utente numerici. Se hai già voci legacy `@username` nella configurazione, `openclaw doctor --fix` può provare a risolverle. - Più sicuro (senza bot di terze parti): + Più sicuro (nessun bot di terze parti): - - Invia un DM al bot, poi esegui `openclaw logs --follow` e leggi `from.id`. + - Invia un DM al tuo bot, poi esegui `openclaw logs --follow` e leggi `from.id`. - Bot API ufficiale: + API Bot ufficiale: - - Invia un DM al bot, poi chiama `https://api.telegram.org/bot/getUpdates` e leggi `message.from.id`. + - Invia un DM al tuo bot, poi chiama `https://api.telegram.org/bot/getUpdates` e leggi `message.from.id`. - Terze parti (meno private): + Terze parti (meno privato): - Invia un DM a `@userinfobot` o `@getidsbot`. @@ -793,11 +792,11 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. - Sì, tramite **routing multi-agent**. Associa il **DM** WhatsApp di ogni mittente (peer `kind: "direct"`, mittente E.164 come `+15551234567`) a un `agentId` diverso, così ogni persona avrà il proprio workspace e il proprio archivio sessioni. Le risposte continueranno comunque a provenire dallo **stesso account WhatsApp**, e il controllo degli accessi DM (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) è globale per account WhatsApp. Vedi [Routing multi-agent](/it/concepts/multi-agent) e [WhatsApp](/it/channels/whatsapp). + Sì, tramite **routing multi-agent**. Associa il **DM** WhatsApp di ogni mittente (peer `kind: "direct"`, mittente E.164 come `+15551234567`) a un `agentId` diverso, così ogni persona avrà il proprio workspace e archivio sessioni. Le risposte continueranno comunque a provenire dallo **stesso account WhatsApp**, e il controllo accessi dei DM (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) è globale per account WhatsApp. Vedi [Routing multi-agent](/it/concepts/multi-agent) e [WhatsApp](/it/channels/whatsapp). - - Sì. Usa il routing multi-agent: assegna a ogni agent il proprio modello predefinito, poi associa le route in ingresso (account provider o peer specifici) a ciascun agent. Un esempio di configurazione si trova in [Routing multi-agent](/it/concepts/multi-agent). Vedi anche [Models](/it/concepts/models) e [Configurazione](/it/gateway/configuration). + + Sì. Usa il routing multi-agent: assegna a ogni agent il proprio modello predefinito, quindi associa i percorsi in ingresso (account provider o peer specifici) a ciascun agent. Un esempio di configurazione si trova in [Routing multi-agent](/it/concepts/multi-agent). Vedi anche [Modelli](/it/concepts/models) e [Configurazione](/it/gateway/configuration). @@ -811,14 +810,14 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. ``` Se esegui OpenClaw tramite systemd, assicurati che il PATH del servizio includa `/home/linuxbrew/.linuxbrew/bin` (o il tuo prefisso brew) in modo che gli strumenti installati con `brew` vengano risolti nelle shell non di login. - Le build recenti antepongono anche le comuni directory bin utente nei servizi Linux systemd (per esempio `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) e rispettano `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR` e `FNM_DIR` quando impostati. + Le build recenti antepongono anche le directory bin utente comuni nei servizi Linux systemd (per esempio `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) e rispettano `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR` e `FNM_DIR` quando impostati. - - - **Installazione hackable (git):** checkout completo del sorgente, modificabile, ideale per i contributori. + + - **Installazione hackable (git):** checkout completo del sorgente, modificabile, ideale per i collaboratori. Esegui le build localmente e puoi correggere codice/documentazione. - - **Installazione npm:** installazione CLI globale, senza repository, ideale per "basta eseguirlo". + - **npm install:** installazione globale della CLI, senza repo, ideale per "basta eseguirlo". Gli aggiornamenti arrivano dai dist-tag npm. Documentazione: [Per iniziare](/it/start/getting-started), [Aggiornamento](/it/install/updating). @@ -849,68 +848,68 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. openclaw gateway restart ``` - Doctor rileva una mancata corrispondenza dell'entrypoint del servizio gateway e propone di riscrivere la configurazione del servizio per allinearla all'installazione corrente (usa `--repair` nelle automazioni). + Doctor rileva una mancata corrispondenza dell'entrypoint del servizio gateway e offre di riscrivere la configurazione del servizio in modo che corrisponda all'installazione corrente (usa `--repair` nelle automazioni). - Per i suggerimenti sul backup, vedi [Strategia di backup](#where-things-live-on-disk). + Suggerimenti per il backup: vedi [Strategia di backup](#dove-si-trova-tutto-sul-disco). Risposta breve: **se vuoi affidabilità 24/7, usa un VPS**. Se vuoi il - minimo attrito e per te vanno bene sospensioni/riavvii, eseguilo in locale. + minor attrito possibile e per te vanno bene sospensioni/riavvii, eseguilo in locale. **Laptop (Gateway locale)** - - **Pro:** nessun costo del server, accesso diretto ai file locali, finestra del browser visibile in tempo reale. - - **Contro:** sospensione/interruzioni di rete = disconnessioni, aggiornamenti/riavvii del sistema operativo interrompono, deve restare attivo. + - **Pro:** nessun costo server, accesso diretto ai file locali, finestra del browser visibile. + - **Contro:** sospensione/cadute di rete = disconnessioni, aggiornamenti/riavvii del sistema operativo interrompono l'esecuzione, la macchina deve restare attiva. **VPS / cloud** - - **Pro:** sempre attivo, rete stabile, nessun problema di sospensione del laptop, più facile da mantenere in esecuzione. - - **Contro:** spesso esecuzione headless (usa screenshot), accesso solo remoto ai file, devi usare SSH per gli aggiornamenti. + - **Pro:** sempre acceso, rete stabile, nessun problema di sospensione del laptop, più facile da mantenere in esecuzione. + - **Contro:** spesso gira headless (usa screenshot), accesso solo remoto ai file, devi usare SSH per gli aggiornamenti. - **Nota specifica di OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord funzionano tutti bene da un VPS. L'unico vero compromesso è **browser headless** rispetto a una finestra visibile. Vedi [Browser](/it/tools/browser). + **Nota specifica di OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord funzionano tutti bene da un VPS. L'unico vero compromesso è **browser headless** contro finestra visibile. Vedi [Browser](/it/tools/browser). - **Predefinito consigliato:** VPS se in passato hai avuto disconnessioni del gateway. L'esecuzione locale è ottima quando stai usando attivamente il Mac e vuoi accesso ai file locali o automazione UI con un browser visibile. + **Scelta predefinita consigliata:** VPS se in passato hai avuto disconnessioni del gateway. La modalità locale è ottima quando stai usando attivamente il Mac e vuoi accesso ai file locali o automazione UI con un browser visibile. - Non è obbligatorio, ma **consigliato per affidabilità e isolamento**. + Non è obbligatorio, ma è **consigliato per affidabilità e isolamento**. - - **Host dedicato (VPS/Mac mini/Pi):** sempre attivo, meno interruzioni dovute a sospensione/riavvio, permessi più puliti, più facile da mantenere in esecuzione. - - **Laptop/desktop condiviso:** assolutamente valido per test e uso attivo, ma aspettati pause quando la macchina va in sospensione o si aggiorna. + - **Host dedicato (VPS/Mac mini/Pi):** sempre acceso, meno interruzioni dovute a sospensioni/riavvii, permessi più puliti, più facile da mantenere in esecuzione. + - **Laptop/desktop condiviso:** va benissimo per test e uso attivo, ma aspettati pause quando la macchina va in sospensione o si aggiorna. - Se vuoi il meglio di entrambi i mondi, mantieni il Gateway su un host dedicato e associa il tuo laptop come **Node** per strumenti locali di schermo/fotocamera/exec. Vedi [Nodes](/it/nodes). + Se vuoi il meglio di entrambi i mondi, tieni il Gateway su un host dedicato e associa il tuo laptop come **Node** per strumenti locali di schermo/fotocamera/exec. Vedi [Nodes](/it/nodes). Per indicazioni sulla sicurezza, leggi [Sicurezza](/it/gateway/security). - + OpenClaw è leggero. Per un Gateway di base + un canale chat: - - **Minimo assoluto:** 1 vCPU, 1GB di RAM, ~500MB di disco. - - **Consigliato:** 1-2 vCPU, 2GB di RAM o più per maggiore margine (log, contenuti multimediali, canali multipli). Gli strumenti Node e l'automazione del browser possono richiedere molte risorse. + - **Minimo assoluto:** 1 vCPU, 1GB RAM, ~500MB di disco. + - **Consigliato:** 1-2 vCPU, 2GB di RAM o più per avere margine (log, media, più canali). Gli strumenti Node e l'automazione del browser possono richiedere molte risorse. - OS: usa **Ubuntu LTS** (o qualsiasi Debian/Ubuntu moderno). Il percorso di installazione Linux è testato soprattutto lì. + OS: usa **Ubuntu LTS** (o qualsiasi Debian/Ubuntu moderno). Il percorso di installazione Linux è testato meglio lì. Documentazione: [Linux](/it/platforms/linux), [Hosting VPS](/it/vps). - Sì. Tratta una VM come un VPS: deve essere sempre attiva, raggiungibile e avere abbastanza - RAM per il Gateway e per qualsiasi canale tu abiliti. + Sì. Tratta una VM come un VPS: deve essere sempre accesa, raggiungibile e avere RAM sufficiente + per il Gateway e gli eventuali canali che abiliti. Indicazioni di base: - - **Minimo assoluto:** 1 vCPU, 1GB di RAM. - - **Consigliato:** 2GB di RAM o più se esegui più canali, automazione del browser o strumenti multimediali. - - **OS:** Ubuntu LTS o un'altra Debian/Ubuntu moderna. + - **Minimo assoluto:** 1 vCPU, 1GB RAM. + - **Consigliato:** 2GB di RAM o più se esegui più canali, automazione del browser o strumenti media. + - **OS:** Ubuntu LTS o un altro Debian/Ubuntu moderno. Se sei su Windows, **WSL2 è la configurazione in stile VM più semplice** e offre la migliore - compatibilità con gli strumenti. Vedi [Windows](/it/platforms/windows), [Hosting VPS](/it/vps). - Se stai eseguendo macOS in una VM, vedi [VM macOS](/it/install/macos-vm). + compatibilità degli strumenti. Vedi [Windows](/it/platforms/windows), [Hosting VPS](/it/vps). + Se stai eseguendo macOS in una VM, vedi [macOS VM](/it/install/macos-vm). @@ -919,11 +918,11 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. - OpenClaw è un assistente AI personale che esegui sui tuoi dispositivi. Risponde sulle superfici di messaggistica che usi già (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat e plugin di canale bundled come QQ Bot) e può anche gestire voce + un Canvas live sulle piattaforme supportate. Il **Gateway** è il control plane sempre attivo; l'assistente è il prodotto. + OpenClaw è un assistente AI personale che esegui sui tuoi dispositivi. Risponde sulle superfici di messaggistica che già usi (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat e plugin di canale inclusi come QQ Bot) e può anche gestire voce + un Canvas live sulle piattaforme supportate. Il **Gateway** è il piano di controllo sempre attivo; l'assistente è il prodotto. - OpenClaw non è "solo un wrapper di Claude". È un **control plane local-first** che ti permette di eseguire un + OpenClaw non è "solo un wrapper di Claude". È un **piano di controllo local-first** che ti permette di eseguire un assistente capace sul **tuo hardware**, raggiungibile dalle app di chat che già usi, con sessioni con stato, memoria e strumenti, senza cedere il controllo dei tuoi flussi di lavoro a un SaaS ospitato. @@ -934,49 +933,49 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. locali il workspace + la cronologia delle sessioni. - **Canali reali, non una sandbox web:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage/ecc., più voce mobile e Canvas sulle piattaforme supportate. - - **Indipendente dal modello:** usa Anthropic, OpenAI, MiniMax, OpenRouter ecc., con routing + - **Indipendente dal modello:** usa Anthropic, OpenAI, MiniMax, OpenRouter, ecc., con routing per agent e failover. - **Opzione solo locale:** esegui modelli locali così **tutti i dati possono restare sul tuo dispositivo** se lo desideri. - - **Routing multi-agent:** agenti separati per canale, account o attività, ognuno con il proprio + - **Routing multi-agent:** agent separati per canale, account o attività, ciascuno con il proprio workspace e le proprie impostazioni predefinite. - - **Open source e hackable:** ispeziona, estendi ed esegui in self-hosting senza vendor lock-in. + - **Open source e hackable:** ispeziona, estendi e fai self-host senza lock-in del fornitore. Documentazione: [Gateway](/it/gateway), [Canali](/it/channels), [Multi-agent](/it/concepts/multi-agent), - [Memory](/it/concepts/memory). + [Memoria](/it/concepts/memory). Buoni primi progetti: - - Costruire un sito web (WordPress, Shopify o un semplice sito statico). + - Creare un sito web (WordPress, Shopify o un semplice sito statico). - Prototipare un'app mobile (struttura, schermate, piano API). - - Organizzare file e cartelle (pulizia, denominazione, tagging). + - Organizzare file e cartelle (pulizia, nomi, tag). - Collegare Gmail e automatizzare riepiloghi o follow-up. - Può gestire attività grandi, ma funziona meglio quando le suddividi in fasi e + Può gestire attività grandi, ma funziona meglio quando le dividi in fasi e usi sub-agent per il lavoro in parallelo. - - Le utilità quotidiane di solito sono queste: + + I vantaggi quotidiani di solito sono questi: - - **Briefing personali:** riepiloghi di posta in arrivo, calendario e notizie che ti interessano. + - **Briefing personali:** riepiloghi di inbox, calendario e notizie che ti interessano. - **Ricerca e stesura:** ricerca rapida, riepiloghi e prime bozze per email o documenti. - **Promemoria e follow-up:** solleciti e checklist guidati da Cron o Heartbeat. - **Automazione del browser:** compilazione di moduli, raccolta dati e ripetizione di attività web. - - **Coordinamento tra dispositivi:** invia un'attività dal telefono, lascia che il Gateway la esegua su un server e ricevi il risultato di nuovo in chat. + - **Coordinamento tra dispositivi:** invia un'attività dal telefono, lascia che il Gateway la esegua su un server e ricevi il risultato in chat. - + Sì per **ricerca, qualificazione e stesura**. Può analizzare siti, creare shortlist, - riepilogare potenziali clienti e scrivere bozze di outreach o di testi pubblicitari. + riepilogare prospect e scrivere bozze di outreach o copy per annunci. - Per **outreach o campagne pubblicitarie**, mantieni una persona nel flusso. Evita lo spam, rispetta le leggi locali e - le policy della piattaforma, e controlla tutto prima dell'invio. Il modello più sicuro è lasciare che - OpenClaw prepari la bozza e che tu la approvi. + Per **outreach o campagne pubblicitarie**, mantieni una persona nel loop. Evita spam, rispetta le leggi locali e + le policy delle piattaforme, e rivedi tutto prima dell'invio. Il pattern più sicuro è + lasciare che OpenClaw prepari la bozza e che tu la approvi. Documentazione: [Sicurezza](/it/gateway/security). @@ -984,18 +983,18 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. OpenClaw è un **assistente personale** e un livello di coordinamento, non un sostituto dell'IDE. Usa - Claude Code o Codex per il ciclo di coding diretto più veloce all'interno di un repository. Usa OpenClaw quando - vuoi memoria persistente, accesso cross-device e orchestrazione degli strumenti. + Claude Code o Codex per il ciclo di coding diretto più rapido dentro un repo. Usa OpenClaw quando + vuoi memoria durevole, accesso cross-device e orchestrazione degli strumenti. Vantaggi: - - **Memory + workspace persistenti** tra le sessioni + - **Memoria + workspace persistenti** tra le sessioni - **Accesso multipiattaforma** (WhatsApp, Telegram, TUI, WebChat) - **Orchestrazione degli strumenti** (browser, file, pianificazione, hook) - - **Gateway sempre attivo** (esecuzione su un VPS, interazione da ovunque) + - **Gateway sempre attivo** (eseguilo su un VPS, interagisci da qualsiasi luogo) - **Nodes** per browser/schermo/fotocamera/exec locali - Showcase: [https://openclaw.ai/showcase](https://openclaw.ai/showcase) + Vetrina: [https://openclaw.ai/showcase](https://openclaw.ai/showcase) @@ -1003,30 +1002,30 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. ## Skills e automazione - - Usa override gestiti invece di modificare la copia nel repository. Inserisci le modifiche in `~/.openclaw/skills//SKILL.md` (oppure aggiungi una cartella tramite `skills.load.extraDirs` in `~/.openclaw/openclaw.json`). La precedenza è `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`, quindi gli override gestiti hanno comunque la precedenza sulle Skills bundled senza toccare git. Se ti serve che la skill sia installata globalmente ma visibile solo ad alcuni agenti, mantieni la copia condivisa in `~/.openclaw/skills` e controlla la visibilità con `agents.defaults.skills` e `agents.list[].skills`. Solo le modifiche adatte all'upstream dovrebbero stare nel repository ed essere inviate come PR. + + Usa override gestiti invece di modificare la copia del repo. Inserisci le tue modifiche in `~/.openclaw/skills//SKILL.md` (oppure aggiungi una cartella tramite `skills.load.extraDirs` in `~/.openclaw/openclaw.json`). La precedenza è `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → incluse → `skills.load.extraDirs`, quindi gli override gestiti hanno comunque priorità sulle Skills incluse senza toccare git. Se hai bisogno che la skill sia installata globalmente ma visibile solo ad alcuni agent, conserva la copia condivisa in `~/.openclaw/skills` e controlla la visibilità con `agents.defaults.skills` e `agents.list[].skills`. Solo le modifiche adatte all'upstream dovrebbero stare nel repo ed essere inviate come PR. - - Sì. Aggiungi directory extra tramite `skills.load.extraDirs` in `~/.openclaw/openclaw.json` (precedenza più bassa). La precedenza predefinita è `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`. `clawhub` installa in `./skills` per impostazione predefinita, che OpenClaw tratta come `/skills` nella sessione successiva. Se la skill deve essere visibile solo a determinati agenti, abbinala a `agents.defaults.skills` o `agents.list[].skills`. + + Sì. Aggiungi directory extra tramite `skills.load.extraDirs` in `~/.openclaw/openclaw.json` (precedenza più bassa). La precedenza predefinita è `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → incluse → `skills.load.extraDirs`. `clawhub` installa per impostazione predefinita in `./skills`, che OpenClaw tratta come `/skills` nella sessione successiva. Se la skill deve essere visibile solo a certi agent, abbinala a `agents.defaults.skills` o `agents.list[].skills`. - Oggi i modelli supportati sono: + Oggi i pattern supportati sono: - - **Processi Cron**: i job isolati possono impostare un override `model` per singolo job. - - **Sub-agent**: instrada le attività verso agenti separati con modelli predefiniti diversi. + - **Cron jobs**: i job isolati possono impostare un override `model` per job. + - **Sub-agent**: instrada le attività verso agent separati con modelli predefiniti diversi. - **Cambio on-demand**: usa `/model` per cambiare in qualsiasi momento il modello della sessione corrente. - Vedi [Processi Cron](/it/automation/cron-jobs), [Routing multi-agent](/it/concepts/multi-agent) e [Comandi slash](/it/tools/slash-commands). + Vedi [Cron jobs](/it/automation/cron-jobs), [Routing multi-agent](/it/concepts/multi-agent) e [Comandi slash](/it/tools/slash-commands). - + Usa **sub-agent** per attività lunghe o parallele. I sub-agent vengono eseguiti nella propria sessione, - restituiscono un riepilogo e mantengono reattiva la chat principale. + restituiscono un riepilogo e mantengono reattiva la tua chat principale. - Chiedi al bot di "generare un sub-agent per questa attività" oppure usa `/subagents`. + Chiedi al tuo bot di "avviare un sub-agent per questa attività" oppure usa `/subagents`. Usa `/status` in chat per vedere cosa sta facendo il Gateway in questo momento (e se è occupato). Suggerimento sui token: sia le attività lunghe sia i sub-agent consumano token. Se il costo è un problema, imposta un @@ -1036,36 +1035,36 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. - - Usa i binding dei thread. Puoi associare un thread Discord a un target di subagent o di sessione in modo che i messaggi successivi in quel thread rimangano su quella sessione associata. + + Usa gli associazioni di thread. Puoi associare un thread Discord a un subagent o a una destinazione di sessione, così i messaggi successivi in quel thread restano su quella sessione associata. Flusso di base: - - Genera con `sessions_spawn` usando `thread: true` (e facoltativamente `mode: "session"` per follow-up persistenti). + - Avvia con `sessions_spawn` usando `thread: true` (e facoltativamente `mode: "session"` per un follow-up persistente). - Oppure associa manualmente con `/focus `. - - Usa `/agents` per ispezionare lo stato del binding. - - Usa `/session idle ` e `/session max-age ` per controllare la perdita automatica del focus. + - Usa `/agents` per ispezionare lo stato dell'associazione. + - Usa `/session idle ` e `/session max-age ` per controllare il disassociamento automatico. - Usa `/unfocus` per scollegare il thread. Configurazione richiesta: - Impostazioni predefinite globali: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. - Override Discord: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. - - Associazione automatica alla generazione: imposta `channels.discord.threadBindings.spawnSubagentSessions: true`. + - Associazione automatica all'avvio: imposta `channels.discord.threadBindings.spawnSubagentSessions: true`. Documentazione: [Sub-agent](/it/tools/subagents), [Discord](/it/channels/discord), [Riferimento configurazione](/it/gateway/configuration-reference), [Comandi slash](/it/tools/slash-commands). - - Controlla prima la route del richiedente risolta: + + Controlla prima il percorso del richiedente risolto: - - La consegna del sub-agent in modalità completamento preferisce qualsiasi thread associato o route di conversazione quando ne esiste una. - - Se l'origine del completamento contiene solo un canale, OpenClaw ripiega sulla route memorizzata della sessione del richiedente (`lastChannel` / `lastTo` / `lastAccountId`) così la consegna diretta può comunque riuscire. - - Se non esistono né una route associata né una route memorizzata utilizzabile, la consegna diretta può fallire e il risultato ripiega invece sulla consegna in coda della sessione, anziché essere pubblicato immediatamente in chat. - - Target non validi o obsoleti possono comunque forzare il fallback alla coda o il fallimento della consegna finale. - - Se l'ultima risposta visibile dell'assistente del child è esattamente il token silenzioso `NO_REPLY` / `no_reply`, oppure esattamente `ANNOUNCE_SKIP`, OpenClaw sopprime intenzionalmente l'annuncio invece di pubblicare progressi precedenti non aggiornati. - - Se il child è andato in timeout dopo sole chiamate a strumenti, l'annuncio può comprimere il tutto in un breve riepilogo del progresso parziale invece di riprodurre l'output grezzo degli strumenti. + - La consegna del subagent in modalità completamento preferisce qualsiasi thread associato o percorso di conversazione quando ne esiste uno. + - Se l'origine del completamento porta solo un canale, OpenClaw ripiega sul percorso memorizzato della sessione del richiedente (`lastChannel` / `lastTo` / `lastAccountId`) in modo che la consegna diretta possa comunque riuscire. + - Se non esistono né un percorso associato né un percorso memorizzato utilizzabile, la consegna diretta può fallire e il risultato ripiega invece sulla consegna in coda della sessione anziché essere pubblicato immediatamente in chat. + - Target non validi o obsoleti possono comunque forzare il ripiego sulla coda o il fallimento finale della consegna. + - Se l'ultima risposta visibile dell'assistente del figlio è esattamente il token silenzioso `NO_REPLY` / `no_reply`, oppure esattamente `ANNOUNCE_SKIP`, OpenClaw sopprime intenzionalmente l'annuncio invece di pubblicare progressi precedenti non più aggiornati. + - Se il figlio è andato in timeout dopo sole chiamate agli strumenti, l'annuncio può comprimere il tutto in un breve riepilogo del progresso parziale invece di riprodurre l'output grezzo degli strumenti. Debug: @@ -1077,14 +1076,14 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. - + Cron viene eseguito all'interno del processo Gateway. Se il Gateway non è in esecuzione continua, i job pianificati non verranno eseguiti. Checklist: - - Conferma che cron sia abilitato (`cron.enabled`) e che `OPENCLAW_SKIP_CRON` non sia impostato. - - Verifica che il Gateway sia in esecuzione 24/7 (senza sospensioni/riavvii). + - Conferma che Cron sia abilitato (`cron.enabled`) e che `OPENCLAW_SKIP_CRON` non sia impostato. + - Controlla che il Gateway sia attivo 24/7 (senza sospensioni/riavvii). - Verifica le impostazioni del fuso orario per il job (`--tz` rispetto al fuso orario dell'host). Debug: @@ -1094,22 +1093,22 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. openclaw cron runs --id --limit 50 ``` - Documentazione: [Job Cron](/it/automation/cron-jobs), [Automazione e attività](/it/automation). + Documentazione: [Cron jobs](/it/automation/cron-jobs), [Automazione e attività](/it/automation). - + Controlla prima la modalità di consegna: - `--no-deliver` / `delivery.mode: "none"` significa che non è previsto alcun messaggio esterno. - Un target di annuncio mancante o non valido (`channel` / `to`) significa che il runner ha saltato la consegna in uscita. - - Errori di autenticazione del canale (`unauthorized`, `Forbidden`) significano che il runner ha provato a consegnare ma le credenziali lo hanno impedito. - - Un risultato isolato silenzioso (`NO_REPLY` / `no_reply` soltanto) viene considerato intenzionalmente non consegnabile, quindi il runner sopprime anche la consegna fallback in coda. + - Errori di autenticazione del canale (`unauthorized`, `Forbidden`) significano che il runner ha provato a consegnare ma le credenziali lo hanno bloccato. + - Un risultato isolato silenzioso (`NO_REPLY` / `no_reply` soltanto) viene trattato come intenzionalmente non consegnabile, quindi il runner sopprime anche il ripiego sulla consegna in coda. - Per i job Cron isolati, il runner gestisce la consegna finale. Ci si aspetta che l'agent - restituisca un riepilogo in testo semplice che il runner possa inviare. `--no-deliver` mantiene - quel risultato interno; non permette invece all'agent di inviare direttamente con lo - strumento messaggio. + Per i cron job isolati, il runner gestisce la consegna finale. L'agent deve + restituire un riepilogo in testo semplice da inviare tramite il runner. `--no-deliver` mantiene + quel risultato interno; non consente invece all'agent di inviare direttamente con lo + strumento di messaggistica. Debug: @@ -1118,27 +1117,27 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. openclaw tasks show ``` - Documentazione: [Job Cron](/it/automation/cron-jobs), [Attività in background](/it/automation/tasks). + Documentazione: [Cron jobs](/it/automation/cron-jobs), [Attività in background](/it/automation/tasks). - + Di solito si tratta del percorso live di cambio modello, non di una pianificazione duplicata. - Cron isolato può rendere persistente un passaggio di modello a runtime e ritentare quando l'esecuzione attiva - genera `LiveSessionModelSwitchError`. Il ritentativo mantiene il - provider/modello cambiato e, se il cambio ha portato con sé un nuovo override del profilo di autenticazione, cron - lo rende persistente prima di ritentare. + Il cron isolato può rendere persistente un handoff di modello runtime e riprovare quando l'esecuzione attiva + genera `LiveSessionModelSwitchError`. Il retry mantiene il + provider/modello cambiato e, se il cambio includeva un nuovo override del profilo di autenticazione, cron + rende persistente anche quello prima di riprovare. Regole di selezione correlate: - - L'override del modello dell'hook Gmail ha la precedenza quando applicabile. + - L'override del modello dell'hook Gmail vince per primo quando applicabile. - Poi il `model` per job. - Poi qualsiasi override del modello della sessione cron memorizzato. - - Poi la normale selezione del modello agent/predefinito. + - Poi la normale selezione del modello predefinito dell'agent. - Il ciclo di ritentativi è limitato. Dopo il tentativo iniziale più 2 ritentativi per cambio, - cron interrompe invece di andare in loop all'infinito. + Il ciclo di retry è limitato. Dopo il tentativo iniziale più 2 retry di cambio, + cron interrompe invece di entrare in un loop infinito. Debug: @@ -1147,13 +1146,13 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. openclaw tasks show ``` - Documentazione: [Job Cron](/it/automation/cron-jobs), [CLI cron](/cli/cron). + Documentazione: [Cron jobs](/it/automation/cron-jobs), [CLI cron](/cli/cron). Usa i comandi nativi `openclaw skills` oppure inserisci le Skills nel tuo workspace. La UI Skills di macOS non è disponibile su Linux. - Sfoglia le Skills su [https://clawhub.ai](https://clawhub.ai). + Esplora le Skills su [https://clawhub.ai](https://clawhub.ai). ```bash openclaw skills search "calendar" @@ -1166,39 +1165,39 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. openclaw skills check ``` - L'installazione nativa `openclaw skills install` scrive nella directory `skills/` + Il comando nativo `openclaw skills install` scrive nella directory `skills/` del workspace attivo. Installa la CLI separata `clawhub` solo se vuoi pubblicare o - sincronizzare le tue Skills. Per installazioni condivise tra agenti, inserisci la skill sotto - `~/.openclaw/skills` e usa `agents.defaults.skills` o - `agents.list[].skills` se vuoi limitare quali agenti possono vederla. + sincronizzare le tue Skills. Per installazioni condivise tra agent, inserisci la skill in + `~/.openclaw/skills` e usa `agents.defaults.skills` oppure + `agents.list[].skills` se vuoi restringere quali agent possano vederla. - - Sì. Usa il pianificatore del Gateway: + + Sì. Usa lo scheduler del Gateway: - - **Job Cron** per attività pianificate o ricorrenti (persistono attraverso i riavvii). + - **Cron jobs** per attività pianificate o ricorrenti (persistono dopo i riavvii). - **Heartbeat** per controlli periodici della "sessione principale". - - **Job isolati** per agenti autonomi che pubblicano riepiloghi o consegnano alle chat. + - **Job isolati** per agent autonomi che pubblicano riepiloghi o consegnano alle chat. - Documentazione: [Job Cron](/it/automation/cron-jobs), [Automazione e attività](/it/automation), + Documentazione: [Cron jobs](/it/automation/cron-jobs), [Automazione e attività](/it/automation), [Heartbeat](/it/gateway/heartbeat). - Non direttamente. Le skill macOS sono controllate da `metadata.openclaw.os` più i binari richiesti, e le skill compaiono nel prompt di sistema solo quando sono idonee sull'**host del Gateway**. Su Linux, le skill solo `darwin` (come `apple-notes`, `apple-reminders`, `things-mac`) non verranno caricate a meno che tu non sovrascriva questo controllo. + Non direttamente. Le Skills macOS sono filtrate da `metadata.openclaw.os` più i binari richiesti, e le Skills compaiono nel prompt di sistema solo quando sono idonee sull'**host Gateway**. Su Linux, le skill solo `darwin` (come `apple-notes`, `apple-reminders`, `things-mac`) non verranno caricate a meno che tu non sovrascriva il filtro. - Hai tre modelli supportati: + Hai tre pattern supportati: **Opzione A - eseguire il Gateway su un Mac (la più semplice).** - Esegui il Gateway dove esistono i binari macOS, poi connettiti da Linux in [modalità remota](#gateway-ports-already-running-and-remote-mode) o tramite Tailscale. Le skill vengono caricate normalmente perché l'host del Gateway è macOS. + Esegui il Gateway dove esistono i binari macOS, poi collegati da Linux in [modalità remota](#gateway-ports-already-running-and-remote-mode) oppure tramite Tailscale. Le Skills vengono caricate normalmente perché l'host Gateway è macOS. **Opzione B - usare un Node macOS (senza SSH).** - Esegui il Gateway su Linux, associa un Node macOS (app menubar) e imposta **Node Run Commands** su "Always Ask" o "Always Allow" sul Mac. OpenClaw può trattare come idonee le skill solo macOS quando i binari richiesti esistono sul Node. L'agente esegue queste skill tramite lo strumento `nodes`. Se scegli "Always Ask", approvare "Always Allow" nel prompt aggiunge quel comando all'allowlist. + Esegui il Gateway su Linux, associa un Node macOS (app menubar) e imposta **Node Run Commands** su "Always Ask" o "Always Allow" sul Mac. OpenClaw può trattare le Skills solo macOS come idonee quando i binari richiesti esistono sul Node. L'agent esegue queste Skills tramite lo strumento `nodes`. Se scegli "Always Ask", approvare "Always Allow" nel prompt aggiunge quel comando all'allowlist. - **Opzione C - proxy dei binari macOS tramite SSH (avanzato).** - Mantieni il Gateway su Linux, ma fai in modo che i binari CLI richiesti vengano risolti in wrapper SSH che vengono eseguiti su un Mac. Poi sovrascrivi la skill per consentire Linux così rimane idonea. + **Opzione C - usare un proxy dei binari macOS tramite SSH (avanzato).** + Mantieni il Gateway su Linux, ma fai in modo che i binari CLI richiesti vengano risolti in wrapper SSH che vengono eseguiti su un Mac. Poi sovrascrivi la skill per consentire Linux in modo che resti idonea. 1. Crea un wrapper SSH per il binario (esempio: `memo` per Apple Notes): @@ -1209,12 +1208,12 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. ``` 2. Inserisci il wrapper nel `PATH` sull'host Linux (per esempio `~/bin/memo`). - 3. Sovrascrivi i metadati della skill (workspace o `~/.openclaw/skills`) per consentire Linux: + 3. Sovrascrivi i metadati della skill (workspace oppure `~/.openclaw/skills`) per consentire Linux: ```markdown --- name: apple-notes - description: Gestisci Apple Notes tramite la CLI memo su macOS. + description: Manage Apple Notes via the memo CLI on macOS. metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } } --- ``` @@ -1224,34 +1223,34 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. - Non integrata in modo nativo al momento. + Al momento non è integrata nativamente. Opzioni: - - **Skill / Plugin personalizzato:** migliore per un accesso API affidabile (sia Notion sia HeyGen hanno API). + - **Skill / plugin personalizzato:** soluzione migliore per un accesso API affidabile (sia Notion sia HeyGen hanno API). - **Automazione del browser:** funziona senza codice ma è più lenta e più fragile. - Se vuoi mantenere il contesto per cliente (flussi di lavoro da agenzia), un modello semplice è: + Se vuoi mantenere il contesto per cliente (workflow da agenzia), un pattern semplice è: - - Una pagina Notion per ogni cliente (contesto + preferenze + lavoro attivo). - - Chiedere all'agente di recuperare quella pagina all'inizio di una sessione. + - Una pagina Notion per cliente (contesto + preferenze + lavoro attivo). + - Chiedi all'agent di recuperare quella pagina all'inizio di una sessione. - Se desideri un'integrazione nativa, apri una richiesta di funzionalità o crea una skill - che usi quelle API. + Se vuoi un'integrazione nativa, apri una richiesta di funzionalità oppure crea una skill + per quelle API. - Installa le Skills: + Installa Skills: ```bash openclaw skills install openclaw skills update --all ``` - Le installazioni native finiscono nella directory `skills/` del workspace attivo. Per Skills condivise tra agenti, inseriscile in `~/.openclaw/skills//SKILL.md`. Se solo alcuni agenti devono vedere un'installazione condivisa, configura `agents.defaults.skills` o `agents.list[].skills`. Alcune Skills si aspettano binari installati tramite Homebrew; su Linux questo significa Linuxbrew (vedi la voce FAQ Homebrew Linux sopra). Vedi [Skills](/it/tools/skills), [Configurazione Skills](/it/tools/skills-config) e [ClawHub](/it/tools/clawhub). + Le installazioni native finiscono nella directory `skills/` del workspace attivo. Per Skills condivise tra agent, inseriscile in `~/.openclaw/skills//SKILL.md`. Se solo alcuni agent devono vedere un'installazione condivisa, configura `agents.defaults.skills` oppure `agents.list[].skills`. Alcune Skills si aspettano binari installati tramite Homebrew; su Linux questo significa Linuxbrew (vedi la voce FAQ su Homebrew Linux qui sopra). Vedi [Skills](/it/tools/skills), [Config delle Skills](/it/tools/skills-config) e [ClawHub](/it/tools/clawhub). - - Usa il profilo browser integrato `user`, che si collega tramite Chrome DevTools MCP: + + Usa il profilo browser `user` integrato, che si collega tramite Chrome DevTools MCP: ```bash openclaw browser --browser-profile user tabs @@ -1265,12 +1264,12 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. openclaw browser --browser-profile chrome-live tabs ``` - Questo percorso è locale all'host. Se il Gateway viene eseguito altrove, esegui un host Node sulla macchina del browser oppure usa invece CDP remoto. + Questo percorso può usare il browser locale dell'host o un browser Node connesso. Se il Gateway è in esecuzione altrove, esegui un host Node sulla macchina del browser oppure usa invece CDP remoto. Limiti attuali di `existing-session` / `user`: - - le azioni sono basate su ref, non su selettori CSS - - gli upload richiedono `ref` / `inputRef` e attualmente supportano un file alla volta + - le azioni sono guidate da ref, non da selettori CSS + - gli upload richiedono `ref` / `inputRef` e al momento supportano un file alla volta - `responsebody`, esportazione PDF, intercettazione dei download e azioni batch richiedono ancora un browser gestito o un profilo CDP grezzo @@ -1280,16 +1279,16 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. - Sì. Vedi [Sandboxing](/it/gateway/sandboxing). Per la configurazione specifica Docker (gateway completo in Docker o immagini sandbox), vedi [Docker](/it/install/docker). + Sì. Vedi [Sandboxing](/it/gateway/sandboxing). Per la configurazione specifica di Docker (Gateway completo in Docker o immagini sandbox), vedi [Docker](/it/install/docker). - - L'immagine predefinita dà priorità alla sicurezza e viene eseguita come utente `node`, quindi non - include pacchetti di sistema, Homebrew o browser bundled. Per una configurazione più completa: + + L'immagine predefinita è orientata prima di tutto alla sicurezza e viene eseguita come utente `node`, quindi non + include pacchetti di sistema, Homebrew o browser inclusi. Per una configurazione più completa: - - Rendi persistente `/home/node` con `OPENCLAW_HOME_VOLUME` così le cache sopravvivono. + - Rendi persistente `/home/node` con `OPENCLAW_HOME_VOLUME` in modo che le cache sopravvivano. - Inserisci le dipendenze di sistema nell'immagine con `OPENCLAW_DOCKER_APT_PACKAGES`. - - Installa i browser Playwright tramite la CLI bundled: + - Installa i browser Playwright tramite la CLI inclusa: `node /app/node_modules/playwright-core/cli.js install chromium` - Imposta `PLAYWRIGHT_BROWSERS_PATH` e assicurati che il percorso sia persistente. @@ -1297,35 +1296,35 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. - - Sì, se il tuo traffico privato è costituito da **DM** e il traffico pubblico da **gruppi**. + + Sì, se il tuo traffico privato è costituito da **DM** e il tuo traffico pubblico da **gruppi**. - Usa `agents.defaults.sandbox.mode: "non-main"` in modo che le sessioni di gruppo/canale (chiavi non principali) vengano eseguite in Docker, mentre la sessione DM principale rimanga sull'host. Poi limita quali strumenti sono disponibili nelle sessioni in sandbox tramite `tools.sandbox.tools`. + Usa `agents.defaults.sandbox.mode: "non-main"` in modo che le sessioni di gruppo/canale (chiavi non principali) vengano eseguite in Docker, mentre la sessione DM principale resti sull'host. Poi limita quali strumenti sono disponibili nelle sessioni in sandbox tramite `tools.sandbox.tools`. Procedura di configurazione + esempio di configurazione: [Gruppi: DM personali + gruppi pubblici](/it/channels/groups#pattern-personal-dms-public-groups-single-agent) - Riferimento della configurazione chiave: [Configurazione Gateway](/it/gateway/configuration-reference#agentsdefaultssandbox) + Riferimento chiave della configurazione: [Configurazione Gateway](/it/gateway/configuration-reference#agentsdefaultssandbox) - - Imposta `agents.defaults.sandbox.docker.binds` su `["host:path:mode"]` (ad esempio `"/home/user/src:/src:ro"`). I bind globali e per-agent vengono uniti; i bind per-agent vengono ignorati quando `scope: "shared"`. Usa `:ro` per qualsiasi elemento sensibile e ricorda che i bind aggirano le barriere del filesystem della sandbox. + + Imposta `agents.defaults.sandbox.docker.binds` su `["host:path:mode"]` (ad es. `"/home/user/src:/src:ro"`). I bind globali + per-agent vengono uniti; i bind per-agent vengono ignorati quando `scope: "shared"`. Usa `:ro` per tutto ciò che è sensibile e ricorda che i bind aggirano le barriere del filesystem della sandbox. - OpenClaw convalida le origini dei bind sia rispetto al percorso normalizzato sia al percorso canonico risolto tramite l'antenato esistente più profondo. Questo significa che le fughe tramite genitore symlink vengono comunque bloccate anche quando l'ultimo segmento del percorso non esiste ancora, e i controlli della radice consentita si applicano ancora dopo la risoluzione del symlink. + OpenClaw convalida le sorgenti dei bind sia rispetto al percorso normalizzato sia rispetto al percorso canonico risolto tramite l'antenato esistente più profondo. Questo significa che le fughe tramite symlink-parent continuano a fallire in modalità sicura anche quando l'ultimo segmento del percorso non esiste ancora, e i controlli delle root consentite continuano ad applicarsi dopo la risoluzione dei symlink. Vedi [Sandboxing](/it/gateway/sandboxing#custom-bind-mounts) e [Sandbox vs Tool Policy vs Elevated](/it/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check) per esempi e note di sicurezza. - La memoria di OpenClaw è semplicemente composta da file Markdown nel workspace dell'agente: + La memoria di OpenClaw è semplicemente costituita da file Markdown nel workspace dell'agent: - Note giornaliere in `memory/YYYY-MM-DD.md` - Note curate a lungo termine in `MEMORY.md` (solo sessioni principali/private) - OpenClaw esegue anche un **flush silenzioso della memoria prima della Compaction** per ricordare al modello - di scrivere note persistenti prima della Compaction automatica. Questo viene eseguito solo quando il workspace - è scrivibile (le sandbox in sola lettura lo saltano). Vedi [Memory](/it/concepts/memory). + OpenClaw esegue anche uno **svuotamento silenzioso della memoria prima della Compaction** per ricordare al modello + di scrivere note durevoli prima della compattazione automatica. Questo viene eseguito solo quando il workspace + è scrivibile (le sandbox in sola lettura lo saltano). Vedi [Memoria](/it/concepts/memory). @@ -1337,31 +1336,31 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. saprà cosa fare. Se continua a dimenticare, verifica che il Gateway stia usando lo stesso workspace a ogni esecuzione. - Documentazione: [Memory](/it/concepts/memory), [Workspace dell'agente](/it/concepts/agent-workspace). + Documentazione: [Memoria](/it/concepts/memory), [Workspace dell'agent](/it/concepts/agent-workspace). - I file di memoria risiedono su disco e persistono finché non li elimini. Il limite è lo - spazio di archiviazione, non il modello. Il **contesto della sessione** è comunque limitato dalla finestra di contesto - del modello, quindi le conversazioni lunghe possono essere compattate o troncate. Per questo + I file di memoria vivono su disco e persistono finché non li elimini. Il limite è il tuo + spazio di archiviazione, non il modello. Il **contesto della sessione** è comunque limitato dalla + finestra di contesto del modello, quindi le conversazioni lunghe possono essere compattate o troncate. Ecco perché esiste la ricerca nella memoria: riporta nel contesto solo le parti rilevanti. - Documentazione: [Memory](/it/concepts/memory), [Contesto](/it/concepts/context). + Documentazione: [Memoria](/it/concepts/memory), [Contesto](/it/concepts/context). Solo se usi gli **embedding OpenAI**. Codex OAuth copre chat/completions e - **non** concede accesso agli embedding, quindi **effettuare l'accesso con Codex (OAuth o il - login CLI di Codex)** non aiuta per la ricerca semantica nella memoria. Gli embedding OpenAI - richiedono ancora una vera chiave API (`OPENAI_API_KEY` o `models.providers.openai.apiKey`). + **non** concede l'accesso agli embedding, quindi **accedere con Codex (OAuth o il + login della CLI Codex)** non aiuta per la ricerca semantica nella memoria. Gli embedding OpenAI + richiedono comunque una vera chiave API (`OPENAI_API_KEY` o `models.providers.openai.apiKey`). Se non imposti esplicitamente un provider, OpenClaw seleziona automaticamente un provider quando riesce a risolvere una chiave API (profili di autenticazione, `models.providers.*.apiKey` o variabili env). - Preferisce OpenAI se viene risolta una chiave OpenAI, altrimenti Gemini se viene risolta una chiave Gemini, - poi Voyage, poi Mistral. Se non è disponibile alcuna chiave remota, la ricerca nella memoria - resta disabilitata finché non la configuri. Se hai configurato ed è presente un percorso di modello locale, OpenClaw + Preferisce OpenAI se riesce a risolvere una chiave OpenAI, altrimenti Gemini se una chiave Gemini + è disponibile, poi Voyage, poi Mistral. Se non è disponibile alcuna chiave remota, la ricerca nella + memoria resta disabilitata finché non la configuri. Se hai configurato e reso disponibile un percorso verso un modello locale, OpenClaw preferisce `local`. Ollama è supportato quando imposti esplicitamente `memorySearch.provider = "ollama"`. @@ -1369,7 +1368,7 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. `memorySearch.fallback = "none"`). Se vuoi embedding Gemini, imposta `memorySearch.provider = "gemini"` e fornisci `GEMINI_API_KEY` (oppure `memorySearch.remote.apiKey`). Supportiamo modelli di embedding **OpenAI, Gemini, Voyage, Mistral, Ollama o local** - - vedi [Memory](/it/concepts/memory) per i dettagli di configurazione. + vedi [Memoria](/it/concepts/memory) per i dettagli di configurazione. @@ -1378,48 +1377,48 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. - No - **lo stato di OpenClaw è locale**, ma **i servizi esterni vedono comunque ciò che invii loro**. + No: **lo stato di OpenClaw è locale**, ma **i servizi esterni vedono comunque ciò che invii loro**. - - **Locale per impostazione predefinita:** sessioni, file di memoria, configurazione e workspace risiedono sull'host Gateway - (`~/.openclaw` + la tua directory workspace). - - **Remoto per necessità:** i messaggi che invii ai provider di modelli (Anthropic/OpenAI/ecc.) vengono inviati alle - loro API, e le piattaforme di chat (WhatsApp/Telegram/Slack/ecc.) memorizzano i dati dei messaggi sui loro + - **Locale per impostazione predefinita:** sessioni, file di memoria, configurazione e workspace si trovano sull'host Gateway + (`~/.openclaw` + la directory del tuo workspace). + - **Remoto per necessità:** i messaggi che invii ai provider di modelli (Anthropic/OpenAI/ecc.) vanno alle + loro API, e le piattaforme di chat (WhatsApp/Telegram/Slack/ecc.) memorizzano i dati dei messaggi sui propri server. - - **Controlli tu l'impronta:** l'uso di modelli locali mantiene i prompt sulla tua macchina, ma il traffico - del canale passa comunque attraverso i server del canale. + - **Controlli tu l'impronta:** usare modelli locali mantiene i prompt sulla tua macchina, ma il + traffico del canale passa comunque attraverso i server del canale. - Correlati: [Workspace dell'agente](/it/concepts/agent-workspace), [Memory](/it/concepts/memory). + Correlati: [Workspace dell'agent](/it/concepts/agent-workspace), [Memoria](/it/concepts/memory). - + Tutto si trova sotto `$OPENCLAW_STATE_DIR` (predefinito: `~/.openclaw`): - | Path | Scopo | + | Percorso | Scopo | | --------------------------------------------------------------- | ------------------------------------------------------------------ | - | `$OPENCLAW_STATE_DIR/openclaw.json` | Configurazione principale (JSON5) | - | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Importazione OAuth legacy (copiata nei profili di autenticazione al primo utilizzo) | - | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Profili di autenticazione (OAuth, chiavi API e `keyRef`/`tokenRef` facoltativi) | - | `$OPENCLAW_STATE_DIR/secrets.json` | Payload segreto facoltativo basato su file per i provider `file` SecretRef | - | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | File di compatibilità legacy (voci statiche `api_key` ripulite) | - | `$OPENCLAW_STATE_DIR/credentials/` | Stato del provider (ad es. `whatsapp//creds.json`) | + | `$OPENCLAW_STATE_DIR/openclaw.json` | Config principale (JSON5) | + | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Import OAuth legacy (copiato nei profili di autenticazione al primo utilizzo) | + | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Profili di autenticazione (OAuth, chiavi API e `keyRef`/`tokenRef` facoltativi) | + | `$OPENCLAW_STATE_DIR/secrets.json` | Payload segreto facoltativo basato su file per provider SecretRef `file` | + | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | File di compatibilità legacy (voci statiche `api_key` ripulite) | + | `$OPENCLAW_STATE_DIR/credentials/` | Stato del provider (es. `whatsapp//creds.json`) | | `$OPENCLAW_STATE_DIR/agents/` | Stato per agent (agentDir + sessioni) | - | `$OPENCLAW_STATE_DIR/agents//sessions/` | Cronologia e stato delle conversazioni (per agent) | - | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Metadati della sessione (per agent) | + | `$OPENCLAW_STATE_DIR/agents//sessions/` | Cronologia e stato delle conversazioni (per agent) | + | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Metadati delle sessioni (per agent) | Percorso legacy per singolo agent: `~/.openclaw/agent/*` (migrato da `openclaw doctor`). - Il tuo **workspace** (`AGENTS.md`, file di memoria, Skills, ecc.) è separato e configurato tramite `agents.defaults.workspace` (predefinito: `~/.openclaw/workspace`). + Il tuo **workspace** (`AGENTS.md`, file di memoria, Skills, ecc.) è separato ed è configurato tramite `agents.defaults.workspace` (predefinito: `~/.openclaw/workspace`). - Questi file risiedono nel **workspace dell'agente**, non in `~/.openclaw`. + Questi file si trovano nel **workspace dell'agent**, non in `~/.openclaw`. - **Workspace (per agent):** `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, - `MEMORY.md` (o il fallback legacy `memory.md` quando `MEMORY.md` è assente), - `memory/YYYY-MM-DD.md`, `HEARTBEAT.md` facoltativo. - - **Directory di stato (`~/.openclaw`)**: configurazione, stato di canali/provider, profili di autenticazione, sessioni, log, + `MEMORY.md` (oppure il fallback legacy `memory.md` quando `MEMORY.md` è assente), + `memory/YYYY-MM-DD.md`, facoltativamente `HEARTBEAT.md`. + - **Directory di stato (`~/.openclaw`)**: configurazione, stato del canale/provider, profili di autenticazione, sessioni, log, e Skills condivise (`~/.openclaw/skills`). Il workspace predefinito è `~/.openclaw/workspace`, configurabile tramite: @@ -1434,23 +1433,23 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. workspace a ogni avvio (e ricorda: la modalità remota usa il workspace dell'**host gateway**, non quello del tuo laptop locale). - Suggerimento: se vuoi un comportamento o una preferenza persistente, chiedi al bot di **scriverla in - AGENTS.md o MEMORY.md** invece di fare affidamento sulla cronologia della chat. + Suggerimento: se vuoi un comportamento o una preferenza durevoli, chiedi al bot di **scriverli in + AGENTS.md o MEMORY.md** invece di affidarti alla cronologia della chat. - Vedi [Workspace dell'agente](/it/concepts/agent-workspace) e [Memory](/it/concepts/memory). + Vedi [Workspace dell'agent](/it/concepts/agent-workspace) e [Memoria](/it/concepts/memory). - Inserisci il tuo **workspace dell'agente** in un repository git **privato** ed esegui il backup da qualche parte - privata (per esempio GitHub privato). Questo cattura memoria + file AGENTS/SOUL/USER - e ti permette di ripristinare in seguito la "mente" dell'assistente. + Metti il tuo **workspace dell'agent** in un repo git **privato** ed esegui il backup in un luogo + privato (per esempio GitHub privato). Questo acquisisce memoria + file AGENTS/SOUL/USER + e ti consente di ripristinare in seguito la "mente" dell'assistente. - **Non** eseguire il commit di nulla sotto `~/.openclaw` (credenziali, sessioni, token o payload di segreti cifrati). - Se ti serve un ripristino completo, esegui separatamente il backup sia del workspace sia della directory di stato - (vedi la domanda sulla migrazione sopra). + **Non** fare commit di nulla sotto `~/.openclaw` (credenziali, sessioni, token o payload di segreti cifrati). + Se hai bisogno di un ripristino completo, esegui il backup sia del workspace sia della directory di stato + separatamente (vedi la domanda sulla migrazione qui sopra). - Documentazione: [Workspace dell'agente](/it/concepts/agent-workspace). + Documentazione: [Workspace dell'agent](/it/concepts/agent-workspace). @@ -1459,15 +1458,15 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. - Sì. Il workspace è il **cwd predefinito** e l'ancora della memoria, non una sandbox rigida. + Sì. Il workspace è la **cwd predefinita** e l'ancora della memoria, non una sandbox rigida. I percorsi relativi vengono risolti all'interno del workspace, ma i percorsi assoluti possono accedere ad altre posizioni dell'host a meno che il sandboxing non sia abilitato. Se hai bisogno di isolamento, usa - [`agents.defaults.sandbox`](/it/gateway/sandboxing) o impostazioni sandbox per-agent. Se vuoi che - un repository sia la directory di lavoro predefinita, punta il `workspace` di quell'agent - alla root del repository. Il repository OpenClaw è solo codice sorgente; mantieni il - workspace separato, a meno che tu non voglia intenzionalmente che l'agent lavori al suo interno. + [`agents.defaults.sandbox`](/it/gateway/sandboxing) o le impostazioni sandbox per agent. Se vuoi che un + repo sia la directory di lavoro predefinita, punta il `workspace` di quell'agent + alla root del repo. Il repo OpenClaw è solo codice sorgente; tieni il + workspace separato a meno che tu non voglia intenzionalmente far lavorare l'agent al suo interno. - Esempio (repository come cwd predefinito): + Esempio (repo come cwd predefinita): ```json5 { @@ -1481,30 +1480,30 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. - - Lo stato della sessione appartiene all'**host gateway**. Se sei in modalità remota, l'archivio delle sessioni che ti interessa si trova sulla macchina remota, non sul tuo laptop locale. Vedi [Gestione delle sessioni](/it/concepts/session). + + Lo stato delle sessioni appartiene all'**host gateway**. Se sei in modalità remota, l'archivio delle sessioni che ti interessa si trova sulla macchina remota, non sul tuo laptop locale. Vedi [Gestione delle sessioni](/it/concepts/session). -## Nozioni di base della configurazione +## Nozioni di base sulla configurazione - OpenClaw legge una configurazione facoltativa in **JSON5** da `$OPENCLAW_CONFIG_PATH` (predefinito: `~/.openclaw/openclaw.json`): + OpenClaw legge una configurazione **JSON5** facoltativa da `$OPENCLAW_CONFIG_PATH` (predefinito: `~/.openclaw/openclaw.json`): ``` $OPENCLAW_CONFIG_PATH ``` - Se il file non esiste, usa valori predefiniti ragionevolmente sicuri (incluso un workspace predefinito di `~/.openclaw/workspace`). + Se il file non esiste, usa impostazioni predefinite abbastanza sicure (incluso un workspace predefinito di `~/.openclaw/workspace`). - - I bind non loopback **richiedono un percorso di autenticazione gateway valido**. In pratica questo significa: + + I bind non-loopback **richiedono un percorso di autenticazione del gateway valido**. In pratica questo significa: - autenticazione con segreto condiviso: token o password - - `gateway.auth.mode: "trusted-proxy"` dietro un reverse proxy non loopback correttamente configurato e con riconoscimento dell'identità + - `gateway.auth.mode: "trusted-proxy"` dietro un reverse proxy con riconoscimento dell'identità non-loopback configurato correttamente ```json5 { @@ -1520,24 +1519,24 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. Note: - - `gateway.remote.token` / `.password` da soli **non** abilitano l'autenticazione del gateway locale. - - I percorsi di chiamata locale possono usare `gateway.remote.*` come fallback solo quando `gateway.auth.*` non è impostato. + - `gateway.remote.token` / `.password` **non** abilitano da soli l'autenticazione del gateway locale. + - I percorsi di chiamata locali possono usare `gateway.remote.*` come fallback solo quando `gateway.auth.*` non è impostato. - Per l'autenticazione con password, imposta invece `gateway.auth.mode: "password"` più `gateway.auth.password` (oppure `OPENCLAW_GATEWAY_PASSWORD`). - - Se `gateway.auth.token` / `gateway.auth.password` è configurato esplicitamente tramite SecretRef e non viene risolto, la risoluzione fallisce in modalità chiusa (nessun fallback remoto che mascheri il problema). - - Le configurazioni Control UI con segreto condiviso si autenticano tramite `connect.params.auth.token` o `connect.params.auth.password` (memorizzati nelle impostazioni app/UI). Le modalità con identità, come Tailscale Serve o `trusted-proxy`, usano invece intestazioni della richiesta. Evita di inserire segreti condivisi negli URL. - - Con `gateway.auth.mode: "trusted-proxy"`, i reverse proxy loopback sullo stesso host **non** soddisfano comunque l'autenticazione trusted-proxy. Il trusted proxy deve essere una sorgente non loopback configurata. + - Se `gateway.auth.token` / `gateway.auth.password` è configurato esplicitamente tramite SecretRef e non risolto, la risoluzione fallisce in modalità chiusa (nessun fallback remoto che mascheri il problema). + - Le configurazioni Control UI con segreto condiviso si autenticano tramite `connect.params.auth.token` o `connect.params.auth.password` (memorizzati nelle impostazioni dell'app/UI). Le modalità con identità come Tailscale Serve o `trusted-proxy` usano invece gli header della richiesta. Evita di inserire segreti condivisi negli URL. + - Con `gateway.auth.mode: "trusted-proxy"`, i reverse proxy loopback sullo stesso host **non** soddisfano comunque l'autenticazione trusted-proxy. Il trusted proxy deve essere una sorgente non-loopback configurata. - - OpenClaw applica l'autenticazione del gateway per impostazione predefinita, incluso loopback. Nel normale percorso predefinito questo significa autenticazione tramite token: se non è configurato alcun percorso di autenticazione esplicito, l'avvio del gateway passa alla modalità token e ne genera automaticamente uno, salvandolo in `gateway.auth.token`, quindi **i client WS locali devono autenticarsi**. Questo impedisce ad altri processi locali di chiamare il Gateway. + + OpenClaw impone per impostazione predefinita l'autenticazione del gateway, incluso il loopback. Nel percorso predefinito normale questo significa autenticazione tramite token: se non è configurato alcun percorso di autenticazione esplicito, l'avvio del gateway passa alla modalità token e ne genera automaticamente uno, salvandolo in `gateway.auth.token`, quindi **i client WS locali devono autenticarsi**. Questo impedisce ad altri processi locali di chiamare il Gateway. - Se preferisci un percorso di autenticazione diverso, puoi scegliere esplicitamente la modalità password (oppure, per reverse proxy non loopback con riconoscimento dell'identità, `trusted-proxy`). Se **vuoi davvero** loopback aperto, imposta esplicitamente `gateway.auth.mode: "none"` nella tua configurazione. Doctor può generare un token per te in qualsiasi momento: `openclaw doctor --generate-gateway-token`. + Se preferisci un percorso di autenticazione diverso, puoi scegliere esplicitamente la modalità password (o, per reverse proxy non-loopback con riconoscimento dell'identità, `trusted-proxy`). Se **vuoi davvero** un loopback aperto, imposta esplicitamente `gateway.auth.mode: "none"` nella tua configurazione. Doctor può generare un token per te in qualsiasi momento: `openclaw doctor --generate-gateway-token`. - Il Gateway osserva la configurazione e supporta il ricaricamento a caldo: + Il Gateway osserva la configurazione e supporta il hot-reload: - `gateway.reload.mode: "hybrid"` (predefinito): applica a caldo le modifiche sicure, riavvia per quelle critiche - Sono supportati anche `hot`, `restart`, `off` @@ -1557,8 +1556,8 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. } ``` - - `off`: nasconde il testo del tagline ma mantiene la riga titolo/versione del banner. - - `default`: usa ogni volta `All your chats, one OpenClaw.`. + - `off`: nasconde il testo del tagline ma mantiene la riga del titolo/versione del banner. + - `default`: usa sempre `All your chats, one OpenClaw.`. - `random`: tagline divertenti/stagionali a rotazione (comportamento predefinito). - Se non vuoi alcun banner, imposta la variabile env `OPENCLAW_HIDE_BANNER=1`. @@ -1568,13 +1567,13 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. `web_fetch` funziona senza una chiave API. `web_search` dipende dal provider selezionato: - - I provider basati su API come Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity e Tavily richiedono la normale configurazione della relativa chiave API. + - I provider supportati da API come Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity e Tavily richiedono la normale configurazione della loro chiave API. - Ollama Web Search non richiede chiavi, ma usa l'host Ollama configurato e richiede `ollama signin`. - DuckDuckGo non richiede chiavi, ma è un'integrazione non ufficiale basata su HTML. - - SearXNG non richiede chiavi/è self-hosted; configura `SEARXNG_BASE_URL` o `plugins.entries.searxng.config.webSearch.baseUrl`. + - SearXNG è senza chiavi/self-hosted; configura `SEARXNG_BASE_URL` o `plugins.entries.searxng.config.webSearch.baseUrl`. **Consigliato:** esegui `openclaw configure --section web` e scegli un provider. - Alternative tramite environment: + Alternative tramite variabili d'ambiente: - Brave: `BRAVE_API_KEY` - Exa: `EXA_API_KEY` @@ -1616,22 +1615,22 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. } ``` - La configurazione specifica del provider per la ricerca web ora si trova sotto `plugins.entries..config.webSearch.*`. - I percorsi legacy del provider `tools.web.search.*` vengono ancora caricati temporaneamente per compatibilità, ma non dovrebbero essere usati per le nuove configurazioni. - La configurazione di fallback Firecrawl per web-fetch si trova sotto `plugins.entries.firecrawl.config.webFetch.*`. + La configurazione della ricerca web specifica del provider ora si trova sotto `plugins.entries..config.webSearch.*`. + I percorsi legacy del provider `tools.web.search.*` vengono ancora caricati temporaneamente per compatibilità, ma non dovrebbero essere usati per nuove configurazioni. + La configurazione di fallback per il recupero web di Firecrawl si trova sotto `plugins.entries.firecrawl.config.webFetch.*`. Note: - Se usi allowlist, aggiungi `web_search`/`web_fetch`/`x_search` o `group:web`. - - `web_fetch` è abilitato per impostazione predefinita (a meno che non venga esplicitamente disabilitato). - - Se `tools.web.fetch.provider` viene omesso, OpenClaw rileva automaticamente il primo provider di fallback fetch pronto in base alle credenziali disponibili. Al momento il provider bundled è Firecrawl. - - I demoni leggono le variabili env da `~/.openclaw/.env` (oppure dall'environment del servizio). + - `web_fetch` è abilitato per impostazione predefinita (a meno che non venga disabilitato esplicitamente). + - Se `tools.web.fetch.provider` viene omesso, OpenClaw rileva automaticamente il primo provider di fallback pronto per il recupero in base alle credenziali disponibili. Attualmente il provider incluso è Firecrawl. + - I demoni leggono le variabili env da `~/.openclaw/.env` (oppure dall'ambiente del servizio). Documentazione: [Strumenti web](/it/tools/web). - + `config.apply` sostituisce l'**intera configurazione**. Se invii un oggetto parziale, tutto il resto viene rimosso. @@ -1639,35 +1638,35 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. - Ripristina da un backup (git o una copia di `~/.openclaw/openclaw.json`). - Se non hai un backup, riesegui `openclaw doctor` e riconfigura canali/modelli. - - Se non te lo aspettavi, segnala un bug e includi la tua ultima configurazione nota o qualsiasi backup. - - Un agente di coding locale può spesso ricostruire una configurazione funzionante dai log o dalla cronologia. + - Se questo era inatteso, segnala un bug e includi la tua ultima configurazione nota o qualsiasi backup. + - Un agente di coding locale spesso può ricostruire una configurazione funzionante dai log o dalla cronologia. Per evitarlo: - Usa `openclaw config set` per piccole modifiche. - Usa `openclaw configure` per modifiche interattive. - - Usa prima `config.schema.lookup` quando non sei sicuro del percorso esatto o della forma di un campo; restituisce un nodo di schema superficiale più riepiloghi immediati dei figli per approfondire. + - Usa prima `config.schema.lookup` quando non sei sicuro di un percorso esatto o della forma di un campo; restituisce un nodo di schema superficiale più riepiloghi immediati dei figli per approfondire. - Usa `config.patch` per modifiche RPC parziali; mantieni `config.apply` solo per la sostituzione completa della configurazione. - - Se stai usando lo strumento `gateway` riservato al proprietario da un'esecuzione agent, continuerà comunque a rifiutare le scritture su `tools.exec.ask` / `tools.exec.security` (incluse le alias legacy `tools.bash.*` che vengono normalizzate agli stessi percorsi exec protetti). + - Se stai usando lo strumento `gateway` riservato al proprietario da un'esecuzione agent, continuerà comunque a rifiutare le scritture in `tools.exec.ask` / `tools.exec.security` (incluse le alias legacy `tools.bash.*` che vengono normalizzate negli stessi percorsi exec protetti). Documentazione: [Config](/cli/config), [Configure](/cli/configure), [Doctor](/it/gateway/doctor). - - Il modello più comune è **un Gateway** (ad es. Raspberry Pi) più **Nodes** e **agent**: + + Il pattern più comune è **un Gateway** (ad es. Raspberry Pi) più **Nodes** e **agent**: - **Gateway (centrale):** possiede canali (Signal/WhatsApp), routing e sessioni. - - **Nodes (dispositivi):** Mac/iOS/Android si collegano come periferiche ed espongono strumenti locali (`system.run`, `canvas`, `camera`). - - **Agent (worker):** cervelli/workspace separati per ruoli speciali (ad es. "Hetzner ops", "Dati personali"). + - **Nodes (dispositivi):** Mac/iOS/Android si connettono come periferiche ed espongono strumenti locali (`system.run`, `canvas`, `camera`). + - **Agent (worker):** cervelli/workspace separati per ruoli specializzati (ad es. "Hetzner ops", "Dati personali"). - **Sub-agent:** avviano lavoro in background da un agent principale quando vuoi parallelismo. - - **TUI:** si collega al Gateway e cambia agent/sessioni. + - **TUI:** si connette al Gateway e cambia agent/sessioni. Documentazione: [Nodes](/it/nodes), [Accesso remoto](/it/gateway/remote), [Routing multi-agent](/it/concepts/multi-agent), [Sub-agent](/it/tools/subagents), [TUI](/web/tui). - + Sì. È un'opzione di configurazione: ```json5 @@ -1681,17 +1680,17 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. } ``` - Il valore predefinito è `false` (con interfaccia). La modalità headless ha maggiori probabilità di attivare controlli anti-bot su alcuni siti. Vedi [Browser](/it/tools/browser). + Il valore predefinito è `false` (headful). La modalità headless ha maggiori probabilità di attivare controlli anti-bot su alcuni siti. Vedi [Browser](/it/tools/browser). - La modalità headless usa lo **stesso motore Chromium** e funziona per la maggior parte delle automazioni (moduli, clic, scraping, accessi). Le differenze principali: + La modalità headless usa lo **stesso motore Chromium** e funziona per la maggior parte dell'automazione (moduli, clic, scraping, login). Le principali differenze: - - Nessuna finestra del browser visibile (usa screenshot se hai bisogno di elementi visivi). - - Alcuni siti sono più rigidi con l'automazione in modalità headless (CAPTCHA, anti-bot). + - Nessuna finestra del browser visibile (usa screenshot se ti servono elementi visivi). + - Alcuni siti sono più rigidi verso l'automazione in modalità headless (CAPTCHA, anti-bot). Per esempio, X/Twitter spesso blocca le sessioni headless. - + Imposta `browser.executablePath` sul binario di Brave (o di qualsiasi browser basato su Chromium) e riavvia il Gateway. Vedi gli esempi completi di configurazione in [Browser](/it/tools/browser#use-brave-or-another-chromium-based-browser). @@ -1700,27 +1699,27 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. ## Gateway remoti e Nodes - - I messaggi Telegram sono gestiti dal **gateway**. Il gateway esegue l'agent e - solo dopo chiama i node tramite il **Gateway WebSocket** quando serve uno strumento node: + + I messaggi Telegram vengono gestiti dal **gateway**. Il gateway esegue l'agent e + solo dopo chiama i nodes tramite il **Gateway WebSocket** quando serve uno strumento node: Telegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram - I Nodes non vedono il traffico del provider in ingresso; ricevono solo chiamate RPC del node. + I Nodes non vedono il traffico in ingresso del provider; ricevono solo chiamate RPC del node. - Risposta breve: **associa il tuo computer come Node**. Il Gateway viene eseguito altrove, ma può - chiamare gli strumenti `node.*` (schermo, fotocamera, sistema) sulla tua macchina locale tramite il Gateway WebSocket. + Risposta breve: **associa il tuo computer come un Node**. Il Gateway viene eseguito altrove, ma può + chiamare strumenti `node.*` (schermo, fotocamera, sistema) sulla tua macchina locale tramite il Gateway WebSocket. Configurazione tipica: - 1. Esegui il Gateway sull'host sempre attivo (VPS/server domestico). - 2. Metti l'host Gateway e il tuo computer sulla stessa tailnet. + 1. Esegui il Gateway sull'host sempre acceso (VPS/server domestico). + 2. Metti l'host Gateway + il tuo computer sulla stessa tailnet. 3. Assicurati che il WS del Gateway sia raggiungibile (bind tailnet o tunnel SSH). - 4. Apri localmente l'app macOS e collegati in modalità **Remote over SSH** (o tailnet diretto) - così può registrarsi come Node. + 4. Apri localmente l'app macOS e connettiti in modalità **Remote over SSH** (o tailnet diretto) + in modo che possa registrarsi come un Node. 5. Approva il Node sul Gateway: ```bash @@ -1728,7 +1727,7 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. openclaw devices approve ``` - Non è necessario alcun bridge TCP separato; i Nodes si collegano tramite il Gateway WebSocket. + Non serve alcun bridge TCP separato; i Nodes si connettono tramite il Gateway WebSocket. Promemoria di sicurezza: associare un Node macOS consente `system.run` su quella macchina. Associa solo dispositivi di cui ti fidi e consulta [Sicurezza](/it/gateway/security). @@ -1742,12 +1741,12 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. - Il Gateway è in esecuzione: `openclaw gateway status` - Stato del Gateway: `openclaw status` - - Stato dei canali: `openclaw channels status` + - Stato del canale: `openclaw channels status` Poi verifica autenticazione e routing: - Se usi Tailscale Serve, assicurati che `gateway.auth.allowTailscale` sia impostato correttamente. - - Se ti connetti tramite tunnel SSH, conferma che il tunnel locale sia attivo e punti alla porta giusta. + - Se ti connetti tramite tunnel SSH, conferma che il tunnel locale sia attivo e punti alla porta corretta. - Conferma che le tue allowlist (DM o gruppo) includano il tuo account. Documentazione: [Tailscale](/it/gateway/tailscale), [Accesso remoto](/it/gateway/remote), [Canali](/it/channels). @@ -1755,76 +1754,76 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. - Sì. Non esiste un bridge "bot-to-bot" integrato, ma puoi collegarlo in alcuni - modi affidabili: + Sì. Non esiste un bridge "bot-to-bot" integrato, ma puoi collegarle in alcuni modi + affidabili: - **Più semplice:** usa un normale canale di chat a cui entrambi i bot possono accedere (Telegram/Slack/WhatsApp). + **Più semplice:** usa un normale canale chat a cui entrambi i bot possono accedere (Telegram/Slack/WhatsApp). Fai in modo che il Bot A invii un messaggio al Bot B, poi lascia che il Bot B risponda come di consueto. **Bridge CLI (generico):** esegui uno script che chiama l'altro Gateway con - `openclaw agent --message ... --deliver`, puntando a una chat dove l'altro bot + `openclaw agent --message ... --deliver`, indirizzandolo a una chat in cui l'altro bot è in ascolto. Se un bot si trova su un VPS remoto, punta la tua CLI a quel Gateway remoto tramite SSH/Tailscale (vedi [Accesso remoto](/it/gateway/remote)). - Modello di esempio (esegui da una macchina che può raggiungere il Gateway di destinazione): + Pattern di esempio (eseguito da una macchina che può raggiungere il Gateway di destinazione): ```bash openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to ``` - Suggerimento: aggiungi una protezione in modo che i due bot non entrino in un loop infinito (solo mention, allowlist - del canale o una regola "non rispondere ai messaggi dei bot"). + Suggerimento: aggiungi una protezione per evitare che i due bot entrino in un loop infinito (solo menzione, allowlist del canale + o una regola "non rispondere ai messaggi dei bot"). Documentazione: [Accesso remoto](/it/gateway/remote), [CLI Agent](/cli/agent), [Invio agent](/it/tools/agent-send). - - No. Un Gateway può ospitare più agenti, ciascuno con il proprio workspace, i propri modelli predefiniti - e il proprio routing. Questa è la configurazione normale ed è molto più economica e semplice che eseguire - un VPS per agent. + + No. Un Gateway può ospitare più agent, ciascuno con il proprio workspace, modelli predefiniti + e routing. Questa è la configurazione normale ed è molto più economica e semplice rispetto a eseguire + un VPS per ogni agent. - Usa VPS separati solo quando hai bisogno di isolamento rigido (confini di sicurezza) o di - configurazioni molto diverse che non vuoi condividere. Altrimenti, mantieni un solo Gateway e + Usa VPS separati solo quando hai bisogno di un isolamento rigido (confini di sicurezza) o di configurazioni + molto diverse che non vuoi condividere. Altrimenti, mantieni un solo Gateway e usa più agent o sub-agent. Sì: i Nodes sono il modo di prima classe per raggiungere il tuo laptop da un Gateway remoto e - offrono molto più del semplice accesso shell. Il Gateway viene eseguito su macOS/Linux (Windows tramite WSL2) ed è + sbloccano più del semplice accesso shell. Il Gateway gira su macOS/Linux (Windows tramite WSL2) ed è leggero (va bene un piccolo VPS o una macchina della classe Raspberry Pi; 4 GB di RAM sono più che sufficienti), quindi una configurazione - comune è un host sempre attivo più il tuo laptop come Node. + comune è un host sempre acceso più il tuo laptop come Node. - - **Nessun SSH in ingresso richiesto.** I Nodes si collegano in uscita al Gateway WebSocket e usano l'associazione del dispositivo. - - **Controlli di esecuzione più sicuri.** `system.run` è controllato da allowlist/approvazioni del node su quel laptop. + - **Non serve SSH in ingresso.** I Nodes si connettono in uscita al Gateway WebSocket e usano l'associazione del dispositivo. + - **Controlli di esecuzione più sicuri.** `system.run` è protetto da allowlist/approvazioni del node su quel laptop. - **Più strumenti del dispositivo.** I Nodes espongono `canvas`, `camera` e `screen` oltre a `system.run`. - **Automazione del browser locale.** Mantieni il Gateway su un VPS, ma esegui Chrome localmente tramite un host node sul laptop, oppure collegati a Chrome locale sull'host tramite Chrome MCP. - SSH va bene per accesso shell ad hoc, ma i Nodes sono più semplici per flussi di lavoro continui degli agenti e + SSH va bene per accesso shell ad hoc, ma i Nodes sono più semplici per workflow continuativi dell'agent e automazione del dispositivo. Documentazione: [Nodes](/it/nodes), [CLI Nodes](/cli/nodes), [Browser](/it/tools/browser). - - No. Dovrebbe essere in esecuzione un solo **gateway** per host, a meno che tu non esegua intenzionalmente profili isolati (vedi [Gateway multipli](/it/gateway/multiple-gateways)). I Nodes sono periferiche che si collegano - al gateway (Nodes iOS/Android oppure "node mode" macOS nell'app della barra dei menu). Per host node headless - e controllo CLI, vedi [CLI host Node](/cli/node). + + No. Dovrebbe essere eseguito un solo **gateway** per host, a meno che tu non stia intenzionalmente eseguendo profili isolati (vedi [Gateway multipli](/it/gateway/multiple-gateways)). I Nodes sono periferiche che si connettono + al gateway (nodes iOS/Android, oppure "modalità node" macOS nell'app menubar). Per host node headless + e controllo CLI, vedi [CLI Node host](/cli/node). - Per le modifiche a `gateway`, `discovery` e `canvasHost` è richiesto un riavvio completo. + È richiesto un riavvio completo per le modifiche a `gateway`, `discovery` e `canvasHost`. Sì. - - `config.schema.lookup`: ispeziona un sottoalbero di configurazione con il relativo nodo di schema superficiale, suggerimento UI corrispondente e riepiloghi immediati dei figli prima della scrittura + - `config.schema.lookup`: ispeziona un sottoalbero della configurazione con il suo nodo di schema superficiale, il suggerimento UI corrispondente e i riepiloghi immediati dei figli prima della scrittura - `config.get`: recupera lo snapshot corrente + hash - `config.patch`: aggiornamento parziale sicuro (preferito per la maggior parte delle modifiche RPC); ricarica a caldo quando possibile e riavvia quando richiesto - - `config.apply`: convalida + sostituisce l'intera configurazione; ricarica a caldo quando possibile e riavvia quando richiesto - - Lo strumento runtime `gateway`, riservato al proprietario, continua comunque a rifiutare la riscrittura di `tools.exec.ask` / `tools.exec.security`; le alias legacy `tools.bash.*` vengono normalizzate agli stessi percorsi exec protetti + - `config.apply`: convalida + sostituisce la configurazione completa; ricarica a caldo quando possibile e riavvia quando richiesto + - Lo strumento runtime `gateway`, riservato al proprietario, continua a rifiutare la riscrittura di `tools.exec.ask` / `tools.exec.security`; gli alias legacy `tools.bash.*` vengono normalizzati sugli stessi percorsi exec protetti @@ -1840,7 +1839,7 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. - + Passaggi minimi: 1. **Installa + accedi sul VPS** @@ -1869,13 +1868,13 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. - Serve espone la **Control UI + WS del Gateway**. I Nodes si collegano tramite lo stesso endpoint WS del Gateway. + Serve espone la **Gateway Control UI + WS**. I Nodes si connettono tramite lo stesso endpoint WS del Gateway. Configurazione consigliata: 1. **Assicurati che VPS + Mac siano sulla stessa tailnet**. - 2. **Usa l'app macOS in modalità Remote** (il target SSH può essere il nome host tailnet). - L'app creerà un tunnel sulla porta del Gateway e si collegherà come Node. + 2. **Usa l'app macOS in modalità Remota** (la destinazione SSH può essere il nome host tailnet). + L'app eseguirà il tunneling della porta del Gateway e si connetterà come un Node. 3. **Approva il Node** sul gateway: ```bash @@ -1887,10 +1886,10 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. - + Se ti servono solo **strumenti locali** (schermo/fotocamera/exec) sul secondo laptop, aggiungilo come - **Node**. Questo mantiene un unico Gateway ed evita configurazioni duplicate. Gli strumenti node locali sono - attualmente solo per macOS, ma prevediamo di estenderli ad altri sistemi operativi. + **Node**. In questo modo mantieni un unico Gateway ed eviti configurazioni duplicate. Gli strumenti node locali sono + attualmente solo per macOS, ma prevediamo di estenderli ad altri OS. Installa un secondo Gateway solo quando hai bisogno di **isolamento rigido** o di due bot completamente separati. @@ -1902,15 +1901,15 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. ## Variabili env e caricamento .env - + OpenClaw legge le variabili env dal processo padre (shell, launchd/systemd, CI, ecc.) e inoltre carica: - `.env` dalla directory di lavoro corrente - - un fallback globale `.env` da `~/.openclaw/.env` (ovvero `$OPENCLAW_STATE_DIR/.env`) + - un `.env` di fallback globale da `~/.openclaw/.env` (ossia `$OPENCLAW_STATE_DIR/.env`) - Nessuno dei file `.env` sovrascrive variabili env esistenti. + Nessuno dei due file `.env` sovrascrive variabili env già esistenti. - Puoi anche definire variabili env inline nella configurazione (applicate solo se mancanti nell'env del processo): + Puoi anche definire variabili env inline nella configurazione (applicate solo se mancanti nel processo env): ```json5 { @@ -1921,14 +1920,14 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. } ``` - Vedi [/environment](/it/help/environment) per la precedenza completa e le sorgenti. + Vedi [/environment](/it/help/environment) per precedenza e fonti complete. - + Due soluzioni comuni: - 1. Inserisci le chiavi mancanti in `~/.openclaw/.env` in modo che vengano caricate anche quando il servizio non eredita l'env della tua shell. + 1. Inserisci le chiavi mancanti in `~/.openclaw/.env` in modo che vengano recuperate anche quando il servizio non eredita l'env della shell. 2. Abilita l'importazione della shell (comodità opt-in): ```json5 @@ -1942,18 +1941,18 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. } ``` - Questo esegue la tua shell di login e importa solo le chiavi previste mancanti (senza mai sovrascrivere). Equivalenti come variabili env: + Questo esegue la tua shell di login e importa solo le chiavi attese mancanti (senza mai sovrascrivere). Equivalenti come variabili env: `OPENCLAW_LOAD_SHELL_ENV=1`, `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`. - `openclaw models status` riporta se l'**importazione dell'env della shell** è abilitata. "Shell env: off" - **non** significa che manchino le tue variabili env: significa solo che OpenClaw non caricherà + `openclaw models status` segnala se l'**importazione dell'env della shell** è abilitata. "Shell env: off" + **non** significa che le tue variabili env siano mancanti: significa solo che OpenClaw non caricherà automaticamente la tua shell di login. - Se il Gateway viene eseguito come servizio (launchd/systemd), non erediterà l'ambiente - della tua shell. Correggi in uno di questi modi: + Se il Gateway gira come servizio (launchd/systemd), non erediterà l'ambiente + della tua shell. Risolvi in uno di questi modi: 1. Inserisci il token in `~/.openclaw/.env`: @@ -1962,7 +1961,7 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. ``` 2. Oppure abilita l'importazione della shell (`env.shellEnv.enabled: true`). - 3. Oppure aggiungilo al blocco `env` della tua configurazione (si applica solo se mancante). + 3. Oppure aggiungilo al blocco `env` della configurazione (si applica solo se manca). Poi riavvia il gateway e ricontrolla: @@ -1976,18 +1975,18 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. -## Sessioni e chat multiple +## Sessioni e più chat Invia `/new` o `/reset` come messaggio autonomo. Vedi [Gestione delle sessioni](/it/concepts/session). - - Le sessioni possono scadere dopo `session.idleMinutes`, ma questo è **disabilitato per impostazione predefinita** (predefinito **0**). - Impostalo su un valore positivo per abilitare la scadenza per inattività. Quando abilitato, il messaggio **successivo** + + Le sessioni possono scadere dopo `session.idleMinutes`, ma questa funzione è **disabilitata per impostazione predefinita** (valore predefinito **0**). + Impostala su un valore positivo per abilitare la scadenza per inattività. Quando è abilitata, il messaggio **successivo** dopo il periodo di inattività avvia un nuovo ID sessione per quella chiave chat. - Questo non elimina le trascrizioni: avvia semplicemente una nuova sessione. + Questo non elimina le trascrizioni: avvia solo una nuova sessione. ```json5 { @@ -1999,35 +1998,35 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. - - Sì, tramite **routing multi-agent** e **sub-agent**. Puoi creare un agent - coordinatore e diversi agent worker con i propri workspace e modelli. + + Sì, tramite **routing multi-agent** e **sub-agent**. Puoi creare un agent coordinatore + e diversi agent worker con i propri workspace e modelli. - Detto questo, è meglio considerarlo come un **esperimento divertente**. Consuma molti token e spesso - è meno efficiente che usare un solo bot con sessioni separate. Il modello tipico che - immaginiamo è un solo bot con cui parli, con sessioni diverse per il lavoro in parallelo. Quel - bot può anche generare sub-agent quando serve. + Detto questo, è meglio considerarlo come un **esperimento divertente**. Consuma molti token ed è spesso + meno efficiente che usare un bot con sessioni separate. Il modello tipico che + immaginiamo è un solo bot con cui parlare, con sessioni diverse per il lavoro in parallelo. Quel + bot può anche avviare sub-agent quando necessario. Documentazione: [Routing multi-agent](/it/concepts/multi-agent), [Sub-agent](/it/tools/subagents), [CLI Agents](/cli/agents). - Il contesto della sessione è limitato dalla finestra del modello. Chat lunghe, output di strumenti di grandi dimensioni o molti + Il contesto della sessione è limitato dalla finestra del modello. Chat lunghe, output di strumenti molto grandi o molti file possono attivare Compaction o troncamento. Cosa aiuta: - - Chiedi al bot di riepilogare lo stato attuale e scriverlo in un file. + - Chiedi al bot di riepilogare lo stato corrente e scriverlo in un file. - Usa `/compact` prima di attività lunghe e `/new` quando cambi argomento. - Mantieni il contesto importante nel workspace e chiedi al bot di rileggerlo. - - Usa sub-agent per attività lunghe o parallele così la chat principale resta più piccola. + - Usa sub-agent per lavori lunghi o paralleli in modo che la chat principale resti più piccola. - Scegli un modello con una finestra di contesto più ampia se succede spesso. - - Usa il comando reset: + + Usa il comando di reset: ```bash openclaw reset @@ -2048,8 +2047,8 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. Note: - L'onboarding offre anche **Reset** se rileva una configurazione esistente. Vedi [Onboarding (CLI)](/it/start/wizard). - - Se hai usato profili (`--profile` / `OPENCLAW_PROFILE`), reimposta ogni directory di stato (i predefiniti sono `~/.openclaw-`). - - Reset di sviluppo: `openclaw gateway --dev --reset` (solo sviluppo; cancella configurazione di sviluppo + credenziali + sessioni + workspace). + - Se hai usato profili (`--profile` / `OPENCLAW_PROFILE`), reimposta ogni directory di stato (i valori predefiniti sono `~/.openclaw-`). + - Reset dev: `openclaw gateway --dev --reset` (solo dev; cancella configurazione dev + credenziali + sessioni + workspace). @@ -2064,7 +2063,7 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. oppure `/compact ` per guidare il riepilogo. - - **Reset** (nuovo ID sessione per la stessa chiave chat): + - **Resetta** (nuovo ID sessione per la stessa chiave chat): ``` /new @@ -2073,24 +2072,24 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. Se continua a succedere: - - Abilita o regola la **potatura della sessione** (`agents.defaults.contextPruning`) per ridurre il vecchio output degli strumenti. + - Abilita o regola il **session pruning** (`agents.defaults.contextPruning`) per ridurre il vecchio output degli strumenti. - Usa un modello con una finestra di contesto più ampia. - Documentazione: [Compaction](/it/concepts/compaction), [Potatura della sessione](/it/concepts/session-pruning), [Gestione delle sessioni](/it/concepts/session). + Documentazione: [Compaction](/it/concepts/compaction), [Session pruning](/it/concepts/session-pruning), [Gestione delle sessioni](/it/concepts/session). Questo è un errore di convalida del provider: il modello ha emesso un blocco `tool_use` senza il campo `input` richiesto. Di solito significa che la cronologia della sessione è obsoleta o corrotta (spesso dopo thread lunghi - o una modifica dello strumento/schema). + o una modifica a uno strumento/schema). Correzione: avvia una nuova sessione con `/new` (messaggio autonomo). - Gli Heartbeat vengono eseguiti ogni **30m** per impostazione predefinita (**1h** quando si usa autenticazione OAuth). Regolali o disabilitali: + Heartbeat viene eseguito ogni **30m** per impostazione predefinita (**1h** quando si usa autenticazione OAuth). Regolalo o disabilitalo: ```json5 { @@ -2105,18 +2104,18 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. ``` Se `HEARTBEAT.md` esiste ma è di fatto vuoto (solo righe vuote e intestazioni - markdown come `# Heading`), OpenClaw salta l'esecuzione di heartbeat per risparmiare chiamate API. - Se il file manca, heartbeat viene comunque eseguito e il modello decide cosa fare. + markdown come `# Heading`), OpenClaw salta l'esecuzione di Heartbeat per risparmiare chiamate API. + Se il file manca, Heartbeat viene comunque eseguito e il modello decide cosa fare. - Gli override per-agent usano `agents.list[].heartbeat`. Documentazione: [Heartbeat](/it/gateway/heartbeat). + Gli override per agent usano `agents.list[].heartbeat`. Documentazione: [Heartbeat](/it/gateway/heartbeat). - No. OpenClaw viene eseguito sul **tuo account**, quindi se sei nel gruppo, OpenClaw può vederlo. + No. OpenClaw gira sul **tuo stesso account**, quindi se sei nel gruppo, OpenClaw può vederlo. Per impostazione predefinita, le risposte nei gruppi sono bloccate finché non consenti i mittenti (`groupPolicy: "allowlist"`). - Se vuoi che solo **tu** possa attivare risposte nel gruppo: + Se vuoi che solo **tu** possa attivare le risposte nel gruppo: ```json5 { @@ -2132,13 +2131,13 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. - Opzione 1 (più veloce): segui i log e invia un messaggio di prova nel gruppo: + Opzione 1 (la più rapida): segui i log e invia un messaggio di prova nel gruppo: ```bash openclaw logs --follow --json ``` - Cerca `chatId` (oppure `from`) che termina con `@g.us`, ad esempio: + Cerca `chatId` (o `from`) che termina con `@g.us`, ad esempio: `1234567890-1234567890@g.us`. Opzione 2 (se già configurato/in allowlist): elenca i gruppi dalla configurazione: @@ -2154,46 +2153,46 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. Due cause comuni: - - Il controllo tramite mention è attivo (predefinito). Devi fare @mention del bot (o corrispondere a `mentionPatterns`). + - Il filtro per menzione è attivo (predefinito). Devi fare @mention del bot (oppure corrispondere a `mentionPatterns`). - Hai configurato `channels.whatsapp.groups` senza `"*"` e il gruppo non è nell'allowlist. Vedi [Gruppi](/it/channels/groups) e [Messaggi di gruppo](/it/channels/group-messages). - - Le chat dirette confluiscono nella sessione principale per impostazione predefinita. Gruppi/canali hanno le proprie chiavi di sessione, e gli argomenti Telegram / thread Discord sono sessioni separate. Vedi [Gruppi](/it/channels/groups) e [Messaggi di gruppo](/it/channels/group-messages). + + Le chat dirette confluiscono per impostazione predefinita nella sessione principale. Gruppi/canali hanno chiavi di sessione proprie, e topic Telegram / thread Discord sono sessioni separate. Vedi [Gruppi](/it/channels/groups) e [Messaggi di gruppo](/it/channels/group-messages). Nessun limite rigido. Decine (persino centinaia) vanno bene, ma fai attenzione a: - - **Crescita del disco:** sessioni + trascrizioni si trovano in `~/.openclaw/agents//sessions/`. - - **Costo dei token:** più agenti significano più utilizzo concorrente dei modelli. - - **Overhead operativo:** profili di autenticazione, workspace e routing dei canali per-agent. + - **Crescita del disco:** sessioni + trascrizioni si trovano sotto `~/.openclaw/agents//sessions/`. + - **Costo dei token:** più agent significa più utilizzo concorrente dei modelli. + - **Overhead operativo:** profili di autenticazione per agent, workspace e routing dei canali. Suggerimenti: - Mantieni un workspace **attivo** per agent (`agents.defaults.workspace`). - - Pota le vecchie sessioni (elimina JSONL o voci di archivio) se il disco cresce. - - Usa `openclaw doctor` per individuare workspace dispersi e incongruenze dei profili. + - Elimina le vecchie sessioni (cancella file JSONL o voci di archivio) se il disco cresce troppo. + - Usa `openclaw doctor` per individuare workspace dispersi e discrepanze nei profili. - Sì. Usa **Routing multi-agent** per eseguire più agenti isolati e instradare i messaggi in ingresso per - canale/account/peer. Slack è supportato come canale e può essere associato ad agenti specifici. + Sì. Usa **Routing multi-agent** per eseguire più agent isolati e instradare i messaggi in ingresso per + canale/account/peer. Slack è supportato come canale e può essere associato ad agent specifici. - L'accesso al browser è potente ma non equivale a "fare tutto ciò che può fare un umano": anti-bot, CAPTCHA e MFA possono + L'accesso al browser è potente ma non equivale a "fare tutto ciò che può fare un essere umano": anti-bot, CAPTCHA e MFA possono comunque bloccare l'automazione. Per il controllo del browser più affidabile, usa Chrome MCP locale sull'host, - oppure usa CDP sulla macchina che esegue realmente il browser. + oppure usa CDP sulla macchina che esegue effettivamente il browser. Configurazione consigliata: - Host Gateway sempre attivo (VPS/Mac mini). - - Un agent per ruolo (binding). - - Canale/i Slack associati a quegli agenti. - - Browser locale tramite Chrome MCP o un Node quando necessario. + - Un agent per ruolo (associazioni). + - Canali Slack associati a quegli agent. + - Browser locale tramite Chrome MCP o un node quando necessario. Documentazione: [Routing multi-agent](/it/concepts/multi-agent), [Slack](/it/channels/slack), [Browser](/it/tools/browser), [Nodes](/it/nodes). @@ -2205,38 +2204,38 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. - Il modello predefinito di OpenClaw è quello che imposti come: + Il modello predefinito di OpenClaw è qualunque modello tu imposti come: ``` agents.defaults.model.primary ``` - I modelli sono referenziati come `provider/model` (esempio: `openai/gpt-5.4`). Se ometti il provider, OpenClaw prima prova un alias, poi una corrispondenza univoca tra i provider configurati per quell'esatto ID modello, e solo dopo ripiega sul provider predefinito configurato come percorso di compatibilità deprecato. Se quel provider non espone più il modello predefinito configurato, OpenClaw ripiega sul primo provider/modello configurato invece di mostrare un predefinito obsoleto di un provider rimosso. Dovresti comunque impostare **esplicitamente** `provider/model`. + I modelli sono referenziati come `provider/model` (esempio: `openai/gpt-5.4`). Se ometti il provider, OpenClaw prova prima un alias, poi una corrispondenza univoca con un provider configurato per quell'esatto ID modello, e solo dopo ricade sul provider predefinito configurato come percorso di compatibilità deprecato. Se quel provider non espone più il modello predefinito configurato, OpenClaw ripiega sul primo provider/modello configurato invece di mostrare un valore predefinito obsoleto di un provider rimosso. Dovresti comunque impostare **esplicitamente** `provider/model`. - **Predefinito consigliato:** usa il modello di ultima generazione più potente disponibile nel tuo stack di provider. + **Predefinito consigliato:** usa il modello di ultima generazione più potente disponibile nel tuo stack provider. **Per agent con strumenti abilitati o input non attendibili:** dai priorità alla potenza del modello rispetto al costo. - **Per chat di routine o a basso rischio:** usa modelli di fallback più economici e instrada per ruolo dell'agent. + **Per chat di routine/a basso rischio:** usa modelli di fallback più economici e instrada per ruolo dell'agent. - MiniMax ha una propria documentazione: [MiniMax](/it/providers/minimax) e + MiniMax ha una documentazione dedicata: [MiniMax](/it/providers/minimax) e [Modelli locali](/it/gateway/local-models). - Regola pratica: usa il **miglior modello che puoi permetterti** per attività ad alta criticità e un modello - più economico per chat di routine o riepiloghi. Puoi instradare i modelli per agent e usare sub-agent per + Regola pratica: usa il **miglior modello che puoi permetterti** per attività ad alto rischio, e un modello più economico + per chat di routine o riepiloghi. Puoi instradare i modelli per agent e usare sub-agent per parallelizzare attività lunghe (ogni sub-agent consuma token). Vedi [Modelli](/it/concepts/models) e [Sub-agent](/it/tools/subagents). - Avvertenza importante: i modelli più deboli o eccessivamente quantizzati sono più vulnerabili alla prompt - injection e a comportamenti non sicuri. Vedi [Sicurezza](/it/gateway/security). + Avvertenza importante: i modelli più deboli o eccessivamente quantizzati sono più vulnerabili a prompt + injection e comportamenti non sicuri. Vedi [Sicurezza](/it/gateway/security). Più contesto: [Modelli](/it/concepts/models). - - Usa i **comandi del modello** oppure modifica solo i campi del **modello**. Evita la sostituzione completa della configurazione. + + Usa i **comandi del modello** oppure modifica solo i campi del **modello**. Evita sostituzioni complete della configurazione. Opzioni sicure: @@ -2245,8 +2244,8 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. - `openclaw configure --section model` (interattivo) - modifica `agents.defaults.model` in `~/.openclaw/openclaw.json` - Evita `config.apply` con un oggetto parziale, a meno che tu non intenda sostituire l'intera configurazione. - Per modifiche RPC, ispeziona prima con `config.schema.lookup` e preferisci `config.patch`. Il payload di lookup ti fornisce il percorso normalizzato, la documentazione/vincoli dello schema superficiale e i riepiloghi immediati dei figli. + Evita `config.apply` con un oggetto parziale a meno che tu non intenda sostituire l'intera configurazione. + Per modifiche RPC, ispeziona prima con `config.schema.lookup` e preferisci `config.patch`. Il payload di lookup ti fornisce il percorso normalizzato, documentazione/vincoli superficiali dello schema e riepiloghi immediati dei figli. per aggiornamenti parziali. Se hai sovrascritto la configurazione, ripristina da un backup oppure riesegui `openclaw doctor` per ripararla. @@ -2260,20 +2259,20 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. Configurazione più rapida: 1. Installa Ollama da `https://ollama.com/download` - 2. Scarica un modello locale, ad esempio `ollama pull gemma4` + 2. Scarica un modello locale come `ollama pull gemma4` 3. Se vuoi anche modelli cloud, esegui `ollama signin` 4. Esegui `openclaw onboard` e scegli `Ollama` 5. Scegli `Local` oppure `Cloud + Local` Note: - - `Cloud + Local` ti offre modelli cloud più i tuoi modelli locali Ollama + - `Cloud + Local` ti offre modelli cloud più i tuoi modelli Ollama locali - i modelli cloud come `kimi-k2.5:cloud` non richiedono un download locale - per il cambio manuale, usa `openclaw models list` e `openclaw models set ollama/` - Nota di sicurezza: i modelli più piccoli o fortemente quantizzati sono più vulnerabili alla prompt + Nota di sicurezza: i modelli più piccoli o fortemente quantizzati sono più vulnerabili a prompt injection. Consigliamo fortemente **modelli grandi** per qualsiasi bot che possa usare strumenti. - Se vuoi comunque modelli piccoli, abilita il sandboxing e allowlist rigorose degli strumenti. + Se vuoi comunque modelli piccoli, abilita il sandboxing e allowlist rigide per gli strumenti. Documentazione: [Ollama](/it/providers/ollama), [Modelli locali](/it/gateway/local-models), [Provider di modelli](/it/concepts/model-providers), [Sicurezza](/it/gateway/security), @@ -2281,13 +2280,13 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. - - - Queste distribuzioni possono differire e cambiare nel tempo; non esiste una raccomandazione fissa sul provider. - - Controlla l'impostazione di runtime corrente su ciascun gateway con `openclaw models status`. + + - Queste installazioni possono differire e cambiare nel tempo; non esiste una raccomandazione fissa sul provider. + - Controlla l'impostazione runtime corrente su ogni gateway con `openclaw models status`. - Per agent sensibili alla sicurezza/con strumenti abilitati, usa il modello di ultima generazione più potente disponibile. - + Usa il comando `/model` come messaggio autonomo: ``` @@ -2300,11 +2299,11 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. /model gemini-flash-lite ``` - Questi sono gli alias integrati. Alias personalizzati possono essere aggiunti tramite `agents.defaults.models`. + Questi sono gli alias integrati. Puoi aggiungere alias personalizzati tramite `agents.defaults.models`. Puoi elencare i modelli disponibili con `/model`, `/model list` o `/model status`. - `/model` (e `/model list`) mostra un selettore compatto e numerato. Seleziona per numero: + `/model` (e `/model list`) mostra un selettore compatto numerato. Seleziona per numero: ``` /model 3 @@ -2317,39 +2316,39 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. /model opus@anthropic:work ``` - Suggerimento: `/model status` mostra quale agent è attivo, quale file `auth-profiles.json` viene usato e quale profilo di autenticazione verrà provato per primo. + Suggerimento: `/model status` mostra quale agent è attivo, quale file `auth-profiles.json` viene usato e quale profilo di autenticazione verrà provato per il prossimo tentativo. Mostra anche l'endpoint del provider configurato (`baseUrl`) e la modalità API (`api`) quando disponibili. - **Come rimuovo il blocco di un profilo impostato con @profile?** + **Come faccio a rimuovere il profilo fissato che ho impostato con @profile?** - Esegui di nuovo `/model` **senza** il suffisso `@profile`: + Riesegui `/model` **senza** il suffisso `@profile`: ``` /model anthropic/claude-opus-4-6 ``` - Se vuoi tornare al valore predefinito, selezionalo da `/model` (oppure invia `/model `). + Se vuoi tornare al predefinito, selezionalo da `/model` (oppure invia `/model `). Usa `/model status` per confermare quale profilo di autenticazione è attivo. - Sì. Impostane uno come predefinito e cambia secondo necessità: + Sì. Impostane uno come predefinito e cambia quando serve: - - **Cambio rapido (per sessione):** `/model gpt-5.4` per attività quotidiane, `/model openai-codex/gpt-5.4` per coding con Codex OAuth. - - **Predefinito + cambio:** imposta `agents.defaults.model.primary` su `openai/gpt-5.4`, poi passa a `openai-codex/gpt-5.4` quando fai coding (o al contrario). - - **Sub-agent:** instrada le attività di coding verso sub-agent con un modello predefinito diverso. + - **Cambio rapido (per sessione):** `/model gpt-5.4` per le attività quotidiane, `/model openai-codex/gpt-5.4` per il coding con Codex OAuth. + - **Predefinito + cambio:** imposta `agents.defaults.model.primary` su `openai/gpt-5.4`, poi passa a `openai-codex/gpt-5.4` quando fai coding (o viceversa). + - **Sub-agent:** instrada le attività di coding a sub-agent con un modello predefinito diverso. Vedi [Modelli](/it/concepts/models) e [Comandi slash](/it/tools/slash-commands). - - Usa un toggle di sessione oppure un valore predefinito nella configurazione: + + Usa un toggle per sessione oppure un valore predefinito in configurazione: - - **Per sessione:** invia `/fast on` mentre la sessione sta usando `openai/gpt-5.4` o `openai-codex/gpt-5.4`. + - **Per sessione:** invia `/fast on` mentre la sessione usa `openai/gpt-5.4` o `openai-codex/gpt-5.4`. - **Predefinito per modello:** imposta `agents.defaults.models["openai/gpt-5.4"].params.fastMode` su `true`. - - **Anche per Codex OAuth:** se usi anche `openai-codex/gpt-5.4`, imposta lì lo stesso flag. + - **Anche per Codex OAuth:** se usi anche `openai-codex/gpt-5.4`, imposta lo stesso flag anche lì. Esempio: @@ -2374,21 +2373,21 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. } ``` - Per OpenAI, la modalità veloce corrisponde a `service_tier = "priority"` nelle richieste native Responses supportate. Gli override di sessione `/fast` hanno la precedenza sui valori predefiniti della configurazione. + Per OpenAI, la modalità fast corrisponde a `service_tier = "priority"` nelle richieste native Responses supportate. Gli override `/fast` della sessione prevalgono sui valori predefiniti della configurazione. - Vedi [Thinking e modalità veloce](/it/tools/thinking) e [Modalità veloce OpenAI](/it/providers/openai#openai-fast-mode). + Vedi [Thinking e modalità fast](/it/tools/thinking) e [Modalità fast OpenAI](/it/providers/openai#openai-fast-mode). Se `agents.defaults.models` è impostato, diventa l'**allowlist** per `/model` e per qualsiasi - override di sessione. La scelta di un modello non presente in tale elenco restituisce: + override di sessione. Se scegli un modello che non è in quell'elenco, viene restituito: ``` Model "provider/model" is not allowed. Use /model to list available models. ``` - Questo errore viene restituito **invece** di una normale risposta. Correzione: aggiungi il modello a + Questo errore viene restituito **al posto** di una normale risposta. Correzione: aggiungi il modello a `agents.defaults.models`, rimuovi l'allowlist oppure scegli un modello da `/model list`. @@ -2399,15 +2398,15 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. Checklist di correzione: - 1. Aggiorna a una release OpenClaw corrente (oppure esegui dal sorgente `main`), poi riavvia il gateway. - 2. Assicurati che MiniMax sia configurato (wizard o JSON), oppure che l'autenticazione MiniMax - esista in env/profili di autenticazione in modo che il provider corrispondente possa essere inserito - (`MINIMAX_API_KEY` per `minimax`, `MINIMAX_OAUTH_TOKEN` o autenticazione MiniMax - OAuth memorizzata per `minimax-portal`). - 3. Usa l'ID modello esatto (con distinzione tra maiuscole e minuscole) per il tuo percorso di autenticazione: - `minimax/MiniMax-M2.7` oppure `minimax/MiniMax-M2.7-highspeed` per configurazione - con chiave API, oppure `minimax-portal/MiniMax-M2.7` / - `minimax-portal/MiniMax-M2.7-highspeed` per configurazione OAuth. + 1. Aggiorna a una release recente di OpenClaw (oppure esegui da `main` del sorgente), poi riavvia il gateway. + 2. Assicurati che MiniMax sia configurato (wizard o JSON), oppure che esista un'autenticazione MiniMax + in env/profili di autenticazione così da poter iniettare il provider corrispondente + (`MINIMAX_API_KEY` per `minimax`, `MINIMAX_OAUTH_TOKEN` oppure OAuth + MiniMax memorizzato per `minimax-portal`). + 3. Usa l'ID modello esatto (case-sensitive) per il tuo percorso di autenticazione: + `minimax/MiniMax-M2.7` oppure `minimax/MiniMax-M2.7-highspeed` per configurazioni con + chiave API, oppure `minimax-portal/MiniMax-M2.7` / + `minimax-portal/MiniMax-M2.7-highspeed` per configurazioni OAuth. 4. Esegui: ```bash @@ -2422,7 +2421,7 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. Sì. Usa **MiniMax come predefinito** e cambia modello **per sessione** quando necessario. - I fallback servono per gli **errori**, non per "attività difficili", quindi usa `/model` o un agent separato. + I fallback servono per gli **errori**, non per le "attività difficili", quindi usa `/model` oppure un agent separato. **Opzione A: cambio per sessione** @@ -2469,7 +2468,7 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. - `gemini-flash` → `google/gemini-3-flash-preview` - `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview` - Se imposti un tuo alias con lo stesso nome, prevale il tuo valore. + Se imposti un tuo alias con lo stesso nome, il tuo valore ha la precedenza. @@ -2496,7 +2495,7 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. - OpenRouter (pagamento per token; molti modelli): + OpenRouter (pay-per-token; molti modelli): ```json5 { @@ -2524,12 +2523,12 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. } ``` - Se fai riferimento a un provider/modello ma manca la chiave richiesta del provider, riceverai un errore di autenticazione a runtime (ad esempio `No API key found for provider "zai"`). + Se fai riferimento a un provider/modello ma manca la chiave richiesta del provider, otterrai un errore di autenticazione a runtime (ad esempio `No API key found for provider "zai"`). - **Nessuna chiave API trovata per il provider dopo aver aggiunto un nuovo agent** + **No API key found for provider dopo aver aggiunto un nuovo agent** - Di solito significa che il **nuovo agent** ha un archivio di autenticazione vuoto. L'autenticazione è per-agent e - viene archiviata in: + Questo di solito significa che il **nuovo agent** ha un archivio di autenticazione vuoto. L'autenticazione è per agent ed è + memorizzata in: ``` ~/.openclaw/agents//agent/auth-profiles.json @@ -2538,9 +2537,9 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. Opzioni di correzione: - Esegui `openclaw agents add ` e configura l'autenticazione durante la procedura guidata. - - Oppure copia `auth-profiles.json` da `agentDir` dell'agent principale nel nuovo `agentDir` dell'agent. + - Oppure copia `auth-profiles.json` dalla `agentDir` dell'agent principale nella `agentDir` del nuovo agent. - **Non** riutilizzare `agentDir` tra agenti; causa collisioni di autenticazione/sessione. + **Non** riutilizzare `agentDir` tra agent; questo provoca collisioni di autenticazione/sessione. @@ -2554,57 +2553,56 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. 1. **Rotazione del profilo di autenticazione** all'interno dello stesso provider. 2. **Fallback del modello** al modello successivo in `agents.defaults.model.fallbacks`. - Ai profili che falliscono vengono applicati cooldown (backoff esponenziale), così OpenClaw può continuare a rispondere anche quando un provider è soggetto a rate limit o fallisce temporaneamente. + I cooldown si applicano ai profili che falliscono (backoff esponenziale), così OpenClaw può continuare a rispondere anche quando un provider è soggetto a rate limit o temporaneamente in errore. - Il bucket di rate limit include più delle sole risposte `429`. OpenClaw - considera degni di failover anche messaggi come `Too many concurrent requests`, + Il bucket del rate limit include più che semplici risposte `429`. OpenClaw + tratta come rate limit meritevoli di failover anche messaggi come `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, `resource exhausted` e limiti - periodici della finestra di utilizzo (`weekly/monthly limit reached`). + periodici di finestra d'uso (`weekly/monthly limit reached`). - Alcune risposte che sembrano di fatturazione non sono `402`, e alcune risposte HTTP `402` + Alcune risposte dall'aspetto legato alla fatturazione non sono `402`, e alcune risposte HTTP `402` restano comunque in quel bucket transitorio. Se un provider restituisce - testo esplicito di fatturazione su `401` o `403`, OpenClaw può comunque mantenerlo - nel canale di fatturazione, ma i matcher di testo specifici del provider restano limitati al + testo esplicito di fatturazione su `401` o `403`, OpenClaw può comunque tenerlo nel + percorso di fatturazione, ma i matcher testuali specifici del provider restano limitati al provider che li possiede (ad esempio OpenRouter `Key limit exceeded`). Se invece un messaggio `402` - assomiglia a una finestra di utilizzo ritentabile o a un - limite di spesa di organizzazione/workspace (`daily limit reached, resets tomorrow`, + assomiglia a una finestra d'uso ritentabile o a un + limite di spesa dell'organizzazione/workspace (`daily limit reached, resets tomorrow`, `organization spending limit exceeded`), OpenClaw lo tratta come - `rate_limit`, non come una lunga disabilitazione per fatturazione. + `rate_limit`, non come una disabilitazione lunga per fatturazione. Gli errori di overflow del contesto sono diversi: firme come `request_too_large`, `input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, - `input is too long for the model` oppure `ollama error: context length - exceeded` restano sul percorso di compattazione/ritentativo invece di avanzare al - fallback del modello. + `input is too long for the model` o `ollama error: context length + exceeded` restano sul percorso di Compaction/retry invece di avanzare nel fallback del modello. - Il testo generico di errore del server è intenzionalmente più ristretto di "qualsiasi cosa con - unknown/error dentro". OpenClaw considera degne di failover forme transitorie limitate al provider - come Anthropic `An unknown error occurred` senza altro contesto, OpenRouter `Provider returned error` senza altro contesto, - errori di motivo di arresto come `Unhandled stop reason: - error`, payload JSON `api_error` con testo transitorio del server + Il testo generico degli errori del server è intenzionalmente più ristretto rispetto a "qualsiasi cosa con + unknown/error dentro". OpenClaw tratta come timeout/sovraccarico meritevoli di failover anche forme transitorie specifiche del provider + come Anthropic con il solo `An unknown error occurred`, OpenRouter con il solo + `Provider returned error`, errori stop-reason come `Unhandled stop reason: + error`, payload JSON `api_error` con testo transitorio di server (`internal server error`, `unknown error, 520`, `upstream error`, `backend - error`) ed errori di provider occupato come `ModelNotReadyException` come segnali di timeout/sovraccarico degni di failover quando il contesto del provider + error`) ed errori di provider occupato come `ModelNotReadyException` quando il contesto del provider corrisponde. - Il testo generico di fallback interno come `LLM request failed with an unknown - error.` rimane prudente e non attiva da solo il fallback del modello. + Il testo interno generico di fallback come `LLM request failed with an unknown + error.` resta prudente e non attiva di per sé il fallback del modello. - - Significa che il sistema ha tentato di usare l'ID del profilo di autenticazione `anthropic:default`, ma non ha potuto trovare credenziali per esso nell'archivio di autenticazione previsto. + + Significa che il sistema ha tentato di usare l'ID profilo di autenticazione `anthropic:default`, ma non è riuscito a trovare credenziali corrispondenti nell'archivio di autenticazione previsto. **Checklist di correzione:** - - **Conferma dove si trovano i profili di autenticazione** (nuovi vs percorsi legacy) - - Attuale: `~/.openclaw/agents//agent/auth-profiles.json` + - **Conferma dove si trovano i profili di autenticazione** (percorsi nuovi vs legacy) + - Corrente: `~/.openclaw/agents//agent/auth-profiles.json` - Legacy: `~/.openclaw/agent/*` (migrato da `openclaw doctor`) - **Conferma che la tua variabile env sia caricata dal Gateway** - - Se hai impostato `ANTHROPIC_API_KEY` nella shell ma esegui il Gateway tramite systemd/launchd, potrebbe non ereditarla. Inseriscila in `~/.openclaw/.env` oppure abilita `env.shellEnv`. + - Se imposti `ANTHROPIC_API_KEY` nella shell ma esegui il Gateway tramite systemd/launchd, potrebbe non ereditarla. Inseriscila in `~/.openclaw/.env` oppure abilita `env.shellEnv`. - **Assicurati di modificare l'agent corretto** - - Le configurazioni multi-agent significano che possono esserci più file `auth-profiles.json`. - - **Controllo di base dello stato modello/autenticazione** + - Le configurazioni multi-agent implicano che possano esserci più file `auth-profiles.json`. + - **Verifica di buon senso stato modello/autenticazione** - Usa `openclaw models status` per vedere i modelli configurati e se i provider sono autenticati. **Checklist di correzione per "No credentials found for profile anthropic"** @@ -2613,7 +2611,7 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. non riesce a trovarlo nel proprio archivio di autenticazione. - **Usa Claude CLI** - - Esegui `openclaw models auth login --provider anthropic --method cli --set-default` sull'host gateway. + - Esegui `openclaw models auth login --provider anthropic --method cli --set-default` sull'host del gateway. - **Se invece vuoi usare una chiave API** - Inserisci `ANTHROPIC_API_KEY` in `~/.openclaw/.env` sull'**host gateway**. - Cancella qualsiasi ordine fissato che forza un profilo mancante: @@ -2623,32 +2621,32 @@ per utilizzo/fatturazione e aumenta i limiti se necessario. ``` - **Conferma di eseguire i comandi sull'host gateway** - - In modalità remota, i profili di autenticazione risiedono sulla macchina gateway, non sul tuo laptop. + - In modalità remota, i profili di autenticazione si trovano sulla macchina gateway, non sul tuo laptop. Se la configurazione del tuo modello include Google Gemini come fallback (oppure sei passato a una scorciatoia Gemini), OpenClaw proverà a usarlo durante il fallback del modello. Se non hai configurato le credenziali Google, vedrai `No API key found for provider "google"`. - Correzione: fornisci l'autenticazione Google oppure rimuovi/evita i modelli Google in `agents.defaults.model.fallbacks` / alias, in modo che il fallback non venga instradato lì. + Correzione: fornisci l'autenticazione Google, oppure rimuovi/evita i modelli Google in `agents.defaults.model.fallbacks` / alias in modo che il fallback non venga instradato lì. **LLM request rejected: thinking signature required (Google Antigravity)** - Causa: la cronologia della sessione contiene **blocchi di thinking senza firme** (spesso da - uno stream interrotto/parziale). Google Antigravity richiede firme per i blocchi di thinking. + Causa: la cronologia della sessione contiene **blocchi di thinking senza firme** (spesso dovuti + a uno stream interrotto/parziale). Google Antigravity richiede firme per i blocchi di thinking. - Correzione: OpenClaw ora rimuove i blocchi di thinking senza firma per Google Antigravity Claude. Se compare ancora, avvia una **nuova sessione** oppure imposta `/thinking off` per quell'agent. + Correzione: OpenClaw ora rimuove i blocchi di thinking senza firma per Google Antigravity Claude. Se il problema compare ancora, avvia una **nuova sessione** oppure imposta `/thinking off` per quell'agent. ## Profili di autenticazione: cosa sono e come gestirli -Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione dei token, modelli multi-account) +Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione dei token, pattern multi-account) - Un profilo di autenticazione è un record di credenziali con nome (OAuth o chiave API) legato a un provider. I profili risiedono in: + Un profilo di autenticazione è un record nominato di credenziali (OAuth o chiave API) associato a un provider. I profili si trovano in: ``` ~/.openclaw/agents//agent/auth-profiles.json @@ -2656,64 +2654,64 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de - - OpenClaw usa ID con prefisso provider, come: + + OpenClaw usa ID con prefisso del provider come: - `anthropic:default` (comune quando non esiste un'identità email) - - `anthropic:` per identità OAuth + - `anthropic:` per le identità OAuth - ID personalizzati che scegli tu (ad es. `anthropic:work`) - Sì. La configurazione supporta metadati facoltativi per i profili e un ordinamento per provider (`auth.order.`). Questo **non** archivia segreti; mappa gli ID a provider/modalità e imposta l'ordine di rotazione. + Sì. La configurazione supporta metadati facoltativi per i profili e un ordinamento per provider (`auth.order.`). Questo **non** memorizza segreti; mappa gli ID a provider/modalità e imposta l'ordine di rotazione. - OpenClaw può saltare temporaneamente un profilo se è in un breve **cooldown** (rate limit/timeout/fallimenti di autenticazione) o in uno stato **disabilitato** più lungo (fatturazione/crediti insufficienti). Per ispezionarlo, esegui `openclaw models status --json` e controlla `auth.unusableProfiles`. Regolazione: `auth.cooldowns.billingBackoffHours*`. + OpenClaw può saltare temporaneamente un profilo se si trova in un breve **cooldown** (rate limit/timeout/errori di autenticazione) o in uno stato **disabled** più lungo (fatturazione/crediti insufficienti). Per ispezionarlo, esegui `openclaw models status --json` e controlla `auth.unusableProfiles`. Regolazione: `auth.cooldowns.billingBackoffHours*`. - I cooldown del rate limit possono essere delimitati per modello. Un profilo che è in cooldown - per un modello può essere ancora utilizzabile per un modello fratello sullo stesso provider, - mentre le finestre di fatturazione/disabilitazione bloccano comunque l'intero profilo. + I cooldown del rate limit possono essere limitati al modello. Un profilo che è in cooldown + per un modello può essere ancora utilizzabile per un modello affine sullo stesso provider, + mentre le finestre di fatturazione/disabled continuano a bloccare l'intero profilo. - Puoi anche impostare un override di ordine **per-agent** (memorizzato nell'`auth-state.json` di quell'agent) tramite CLI: + Puoi anche impostare un override di ordine **per agent** (memorizzato in `auth-state.json` di quell'agent) tramite la CLI: ```bash - # Usa per impostazione predefinita l'agent predefinito configurato (ometti --agent) + # Usa per default l'agent predefinito configurato (ometti --agent) openclaw models auth order get --provider anthropic # Blocca la rotazione a un singolo profilo (prova solo questo) openclaw models auth order set --provider anthropic anthropic:default - # Oppure imposta un ordine esplicito (fallback all'interno del provider) + # Oppure imposta un ordine esplicito (fallback nel provider) openclaw models auth order set --provider anthropic anthropic:work anthropic:default # Cancella l'override (torna a config auth.order / round-robin) openclaw models auth order clear --provider anthropic ``` - Per scegliere come target un agent specifico: + Per puntare a un agent specifico: ```bash openclaw models auth order set --provider anthropic --agent main anthropic:default ``` - Per verificare cosa verrà realmente provato, usa: + Per verificare cosa verrà davvero provato, usa: ```bash openclaw models status --probe ``` - Se un profilo memorizzato viene omesso dall'ordine esplicito, la sonda segnala + Se un profilo memorizzato viene omesso dall'ordine esplicito, il probe segnala `excluded_by_auth_order` per quel profilo invece di provarlo in silenzio. - OpenClaw supporta entrambi: + OpenClaw supporta entrambe: - **OAuth** spesso sfrutta l'accesso in abbonamento (dove applicabile). - - **Chiavi API** usano fatturazione per token. + - **Chiavi API** usano la fatturazione pay-per-token. - La procedura guidata supporta esplicitamente Anthropic Claude CLI, OpenAI Codex OAuth e chiavi API. + La procedura guidata supporta esplicitamente Anthropic Claude CLI, OpenAI Codex OAuth e le chiavi API. @@ -2727,24 +2725,24 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de Precedenza: ``` - --port > OPENCLAW_GATEWAY_PORT > gateway.port > predefinita 18789 + --port > OPENCLAW_GATEWAY_PORT > gateway.port > default 18789 ``` - - Perché "running" è la vista del **supervisore** (launchd/systemd/schtasks). La sonda RPC è la CLI che si connette realmente al gateway WebSocket e chiama `status`. + + Perché "running" è il punto di vista del **supervisore** (launchd/systemd/schtasks). Il probe di connettività è invece la CLI che si connette davvero al Gateway WebSocket. - Usa `openclaw gateway status` e fidati di queste righe: + Usa `openclaw gateway status` e fai affidamento su queste righe: - - `Probe target:` (l'URL che la sonda ha realmente usato) - - `Listening:` (ciò che è realmente associato alla porta) - - `Last gateway error:` (causa radice comune quando il processo è vivo ma la porta non è in ascolto) + - `Probe target:` (l'URL che il probe ha effettivamente usato) + - `Listening:` (ciò che è realmente in ascolto sulla porta) + - `Last gateway error:` (causa comune alla radice quando il processo è vivo ma la porta non è in ascolto) - - Stai modificando un file di configurazione mentre il servizio ne sta eseguendo un altro (spesso per una mancata corrispondenza `--profile` / `OPENCLAW_STATE_DIR`). + + Stai modificando un file di configurazione mentre il servizio ne sta eseguendo un altro (spesso a causa di una mancata corrispondenza `--profile` / `OPENCLAW_STATE_DIR`). Correzione: @@ -2752,19 +2750,19 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de openclaw gateway install --force ``` - Eseguilo dallo stesso `--profile` / environment che vuoi far usare al servizio. + Eseguilo dallo stesso `--profile` / ambiente che vuoi far usare al servizio. - - OpenClaw applica un lock di runtime collegando immediatamente il listener WebSocket all'avvio (predefinito `ws://127.0.0.1:18789`). Se il bind fallisce con `EADDRINUSE`, genera `GatewayLockError`, indicando che un'altra istanza è già in ascolto. + + OpenClaw impone un lock runtime associando immediatamente il listener WebSocket all'avvio (predefinito `ws://127.0.0.1:18789`). Se il bind fallisce con `EADDRINUSE`, genera `GatewayLockError` indicando che un'altra istanza è già in ascolto. Correzione: arresta l'altra istanza, libera la porta oppure esegui con `openclaw gateway --port `. - - Imposta `gateway.mode: "remote"` e punta a un URL WebSocket remoto, facoltativamente con credenziali remote a segreto condiviso: + + Imposta `gateway.mode: "remote"` e punta a un URL WebSocket remoto, opzionalmente con credenziali remote a segreto condiviso: ```json5 { @@ -2783,53 +2781,53 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de - `openclaw gateway` si avvia solo quando `gateway.mode` è `local` (oppure se passi il flag di override). - L'app macOS osserva il file di configurazione e cambia modalità in tempo reale quando questi valori cambiano. - - `gateway.remote.token` / `.password` sono solo credenziali remote lato client; da soli non abilitano l'autenticazione del gateway locale. + - `gateway.remote.token` / `.password` sono solo credenziali remote lato client; non abilitano di per sé l'autenticazione del gateway locale. - Il percorso di autenticazione del gateway e il metodo di autenticazione della UI non corrispondono. + Il percorso di autenticazione del tuo gateway e il metodo di autenticazione della UI non corrispondono. Fatti (dal codice): - - La Control UI mantiene il token in `sessionStorage` per la sessione della scheda corrente del browser e per l'URL del gateway selezionato, quindi gli aggiornamenti nella stessa scheda continuano a funzionare senza ripristinare la persistenza del token di lunga durata in localStorage. - - Su `AUTH_TOKEN_MISMATCH`, i client attendibili possono tentare un ritentativo limitato con un token dispositivo in cache quando il gateway restituisce suggerimenti di ritentativo (`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`). - - Quel ritentativo con token in cache ora riutilizza gli ambiti approvati in cache memorizzati con il token dispositivo. I chiamanti espliciti `deviceToken` / `scopes` espliciti continuano invece a mantenere l'insieme di ambiti richiesto senza ereditare gli ambiti in cache. - - Al di fuori di quel percorso di ritentativo, la precedenza dell'autenticazione di connessione è: token/password condiviso esplicito per primo, poi `deviceToken` esplicito, poi token dispositivo memorizzato, poi token bootstrap. - - I controlli degli ambiti del token bootstrap hanno prefisso di ruolo. L'allowlist incorporata dell'operatore bootstrap soddisfa solo le richieste dell'operatore; node o altri ruoli non operatore hanno comunque bisogno di ambiti sotto il proprio prefisso di ruolo. + - La Control UI conserva il token in `sessionStorage` per la sessione della scheda del browser corrente e l'URL del gateway selezionato, quindi i refresh della stessa scheda continuano a funzionare senza ripristinare la persistenza di lungo periodo del token in localStorage. + - Su `AUTH_TOKEN_MISMATCH`, i client attendibili possono tentare un retry limitato con un token dispositivo in cache quando il gateway restituisce suggerimenti di retry (`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`). + - Quel retry con token in cache ora riusa gli scope approvati in cache memorizzati con il token del dispositivo. I chiamanti espliciti `deviceToken` / `scopes` espliciti mantengono comunque il set di scope richiesto invece di ereditare gli scope in cache. + - Fuori da quel percorso di retry, la precedenza dell'autenticazione di connessione è: token/password condivisi espliciti prima, poi `deviceToken` esplicito, poi token dispositivo memorizzato, poi bootstrap token. + - I controlli di scope del bootstrap token hanno prefisso di ruolo. L'allowlist integrata del bootstrap operator soddisfa solo le richieste operator; i ruoli node o altri ruoli non-operator richiedono comunque scope sotto il proprio prefisso di ruolo. Correzione: - Più rapido: `openclaw dashboard` (stampa + copia l'URL della dashboard, prova ad aprirlo; mostra un suggerimento SSH se headless). - Se non hai ancora un token: `openclaw doctor --generate-gateway-token`. - - Se è remoto, prima crea un tunnel: `ssh -N -L 18789:127.0.0.1:18789 user@host` quindi apri `http://127.0.0.1:18789/`. + - Se sei in remoto, crea prima il tunnel: `ssh -N -L 18789:127.0.0.1:18789 user@host` poi apri `http://127.0.0.1:18789/`. - Modalità segreto condiviso: imposta `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` oppure `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`, poi incolla il segreto corrispondente nelle impostazioni della Control UI. - - Modalità Tailscale Serve: assicurati che `gateway.auth.allowTailscale` sia abilitato e che tu stia aprendo l'URL Serve, non un URL loopback/tailnet grezzo che aggira le intestazioni di identità Tailscale. - - Modalità trusted-proxy: assicurati di passare attraverso il proxy con riconoscimento dell'identità non loopback configurato, non tramite un proxy loopback sullo stesso host o un URL gateway grezzo. - - Se la mancata corrispondenza persiste dopo il singolo ritentativo, ruota/riapprova il token del dispositivo associato: + - Modalità Tailscale Serve: assicurati che `gateway.auth.allowTailscale` sia abilitato e che tu stia aprendo l'URL Serve, non un URL loopback/tailnet grezzo che bypassa gli header di identità Tailscale. + - Modalità trusted-proxy: assicurati di passare attraverso il proxy con riconoscimento dell'identità non-loopback configurato, non tramite un proxy loopback sullo stesso host o un URL gateway grezzo. + - Se la mancata corrispondenza persiste dopo il singolo retry, ruota/riapprova il token del dispositivo associato: - `openclaw devices list` - `openclaw devices rotate --device --role operator` - Se quella chiamata di rotazione dice che è stata negata, controlla due cose: - - le sessioni dei dispositivi associati possono ruotare solo il **proprio** dispositivo, a meno che non abbiano anche `operator.admin` - - i valori `--scope` espliciti non possono superare gli attuali ambiti operatore del chiamante + - le sessioni del dispositivo associato possono ruotare solo il **proprio** dispositivo a meno che non abbiano anche `operator.admin` + - i valori espliciti `--scope` non possono superare gli scope operator correnti del chiamante - Ancora bloccato? Esegui `openclaw status --all` e segui [Risoluzione dei problemi](/it/gateway/troubleshooting). Vedi [Dashboard](/web/dashboard) per i dettagli di autenticazione. - - Il bind `tailnet` sceglie un IP Tailscale dalle interfacce di rete (100.64.0.0/10). Se la macchina non è in Tailscale (oppure l'interfaccia è inattiva), non c'è nulla a cui fare il bind. + + Il bind `tailnet` sceglie un IP Tailscale dalle interfacce di rete della macchina (100.64.0.0/10). Se la macchina non è su Tailscale (o l'interfaccia è inattiva), non c'è nulla a cui fare bind. Correzione: - Avvia Tailscale su quell'host (in modo che abbia un indirizzo 100.x), oppure - - Passa a `gateway.bind: "loopback"` / `"lan"`. + - passa a `gateway.bind: "loopback"` / `"lan"`. Nota: `tailnet` è esplicito. `auto` preferisce loopback; usa `gateway.bind: "tailnet"` quando vuoi un bind solo tailnet. - - Di solito no: un Gateway può eseguire più canali di messaggistica e agenti. Usa più Gateway solo quando hai bisogno di ridondanza (es.: rescue bot) o isolamento rigido. + + Di solito no: un Gateway può eseguire più canali di messaggistica e agent. Usa più Gateways solo quando hai bisogno di ridondanza (es: rescue bot) o isolamento rigido. Sì, ma devi isolare: @@ -2841,7 +2839,7 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de Configurazione rapida (consigliata): - Usa `openclaw --profile ...` per istanza (crea automaticamente `~/.openclaw-`). - - Imposta un `gateway.port` univoco nella configurazione di ciascun profilo (oppure passa `--port` per le esecuzioni manuali). + - Imposta un `gateway.port` univoco nella configurazione di ogni profilo (oppure passa `--port` per esecuzioni manuali). - Installa un servizio per profilo: `openclaw --profile gateway install`. I profili aggiungono anche un suffisso ai nomi dei servizi (`ai.openclaw.`; legacy `com.openclaw.*`, `openclaw-gateway-.service`, `OpenClaw Gateway ()`). @@ -2849,16 +2847,16 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de - + Il Gateway è un **server WebSocket** e si aspetta che il primissimo messaggio sia un frame `connect`. Se riceve qualcos'altro, chiude la connessione - con **code 1008** (violazione della policy). + con **codice 1008** (violazione della policy). Cause comuni: - - Hai aperto l'URL **HTTP** in un browser (`http://...`) invece di usare un client WS. - - Hai usato la porta o il percorso sbagliato. - - Un proxy o un tunnel ha rimosso le intestazioni di autenticazione oppure ha inviato una richiesta non Gateway. + - Hai aperto l'URL **HTTP** in un browser (`http://...`) invece che in un client WS. + - Hai usato la porta o il percorso sbagliati. + - Un proxy o un tunnel ha rimosso gli header di autenticazione o ha inviato una richiesta non-Gateway. Correzioni rapide: @@ -2866,7 +2864,7 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de 2. Non aprire la porta WS in una normale scheda del browser. 3. Se l'autenticazione è attiva, includi il token/password nel frame `connect`. - Se stai usando la CLI o la TUI, l'URL dovrebbe essere simile a: + Se stai usando la CLI o la TUI, l'URL dovrebbe avere questo aspetto: ``` openclaw tui --url ws://:18789 --token @@ -2880,22 +2878,22 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de ## Logging e debug - + Log su file (strutturati): ``` /tmp/openclaw/openclaw-YYYY-MM-DD.log ``` - Puoi impostare un percorso stabile tramite `logging.file`. Il livello di log su file è controllato da `logging.level`. La verbosità della console è controllata da `--verbose` e `logging.consoleLevel`. + Puoi impostare un percorso stabile tramite `logging.file`. Il livello del log su file è controllato da `logging.level`. La verbosità della console è controllata da `--verbose` e `logging.consoleLevel`. - Il modo più rapido per seguire i log: + Coda log più rapida: ```bash openclaw logs --follow ``` - Log del servizio/supervisore (quando il gateway viene eseguito tramite launchd/systemd): + Log del servizio/supervisore (quando il gateway gira tramite launchd/systemd): - macOS: `$OPENCLAW_STATE_DIR/logs/gateway.log` e `gateway.err.log` (predefinito: `~/.openclaw/logs/...`; i profili usano `~/.openclaw-/logs/...`) - Linux: `journalctl --user -u openclaw-gateway[-].service -n 200 --no-pager` @@ -2905,7 +2903,7 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de - + Usa gli helper del gateway: ```bash @@ -2913,14 +2911,14 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de openclaw gateway restart ``` - Se esegui il gateway manualmente, `openclaw gateway --force` può reclamare la porta. Vedi [Gateway](/it/gateway). + Se esegui il gateway manualmente, `openclaw gateway --force` può riappropriarsi della porta. Vedi [Gateway](/it/gateway). Esistono **due modalità di installazione Windows**: - **1) WSL2 (consigliato):** il Gateway viene eseguito all'interno di Linux. + **1) WSL2 (consigliata):** il Gateway gira dentro Linux. Apri PowerShell, entra in WSL, poi riavvia: @@ -2936,7 +2934,7 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de openclaw gateway run ``` - **2) Windows nativo (non consigliato):** il Gateway viene eseguito direttamente in Windows. + **2) Windows nativo (non consigliato):** il Gateway gira direttamente in Windows. Apri PowerShell ed esegui: @@ -2955,8 +2953,8 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de - - Inizia con un rapido controllo dello stato: + + Inizia con una rapida verifica generale dello stato: ```bash openclaw status @@ -2967,11 +2965,11 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de Cause comuni: - - Autenticazione del modello non caricata sull'**host gateway** (controlla `models status`). - - Associazione/allowlist del canale che blocca le risposte (controlla configurazione del canale + log). - - WebChat/Dashboard aperta senza il token corretto. + - L'autenticazione del modello non è caricata sull'**host gateway** (controlla `models status`). + - L'associazione/allowlist del canale blocca le risposte (controlla la configurazione del canale + i log). + - WebChat/Dashboard è aperta senza il token corretto. - Se sei in remoto, conferma che il tunnel/la connessione Tailscale sia attiva e che il + Se sei in remoto, conferma che la connessione tunnel/Tailscale sia attiva e che il Gateway WebSocket sia raggiungibile. Documentazione: [Canali](/it/channels), [Risoluzione dei problemi](/it/gateway/troubleshooting), [Accesso remoto](/it/gateway/remote). @@ -2979,12 +2977,12 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de - Di solito significa che la UI ha perso la connessione WebSocket. Controlla: + Questo di solito significa che la UI ha perso la connessione WebSocket. Controlla: 1. Il Gateway è in esecuzione? `openclaw gateway status` - 2. Il Gateway è in salute? `openclaw status` - 3. La UI ha il token giusto? `openclaw dashboard` - 4. Se è remoto, il collegamento tunnel/Tailscale è attivo? + 2. Il Gateway è sano? `openclaw status` + 3. La UI ha il token corretto? `openclaw dashboard` + 4. Se sei in remoto, il collegamento tunnel/Tailscale è attivo? Poi segui i log: @@ -2996,26 +2994,26 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de - - Inizia da log e stato del canale: + + Inizia con i log e lo stato del canale: ```bash openclaw channels status openclaw channels logs --channel telegram ``` - Poi abbina l'errore: + Poi confronta l'errore: - - `BOT_COMMANDS_TOO_MUCH`: il menu Telegram ha troppe voci. OpenClaw riduce già l'elenco al limite Telegram e riprova con meno comandi, ma alcune voci del menu devono comunque essere rimosse. Riduci plugin/skill/comandi personalizzati, oppure disabilita `channels.telegram.commands.native` se non ti serve il menu. - - `TypeError: fetch failed`, `Network request for 'setMyCommands' failed!` o errori di rete simili: se sei su un VPS o dietro un proxy, conferma che HTTPS in uscita sia consentito e che DNS funzioni per `api.telegram.org`. + - `BOT_COMMANDS_TOO_MUCH`: il menu Telegram ha troppe voci. OpenClaw lo riduce già al limite Telegram e riprova con meno comandi, ma alcune voci del menu devono comunque essere rimosse. Riduci i comandi di plugin/skill/personalizzati oppure disabilita `channels.telegram.commands.native` se non ti serve il menu. + - `TypeError: fetch failed`, `Network request for 'setMyCommands' failed!` o errori di rete simili: se sei su un VPS o dietro un proxy, conferma che l'HTTPS in uscita sia consentito e che il DNS funzioni per `api.telegram.org`. - Se il Gateway è remoto, assicurati di guardare i log sull'host gateway. + Se il Gateway è remoto, assicurati di guardare i log sull'host Gateway. - Documentazione: [Telegram](/it/channels/telegram), [Risoluzione dei problemi dei canali](/it/channels/troubleshooting). + Documentazione: [Telegram](/it/channels/telegram), [Risoluzione dei problemi del canale](/it/channels/troubleshooting). - + Per prima cosa conferma che il Gateway sia raggiungibile e che l'agent possa essere eseguito: ```bash @@ -3024,14 +3022,14 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de openclaw logs --follow ``` - Nella TUI, usa `/status` per vedere lo stato corrente. Se ti aspetti risposte in un canale - chat, assicurati che la consegna sia abilitata (`/deliver on`). + Nella TUI, usa `/status` per vedere lo stato corrente. Se ti aspetti risposte in un canale chat, + assicurati che la consegna sia abilitata (`/deliver on`). Documentazione: [TUI](/web/tui), [Comandi slash](/it/tools/slash-commands). - + Se hai installato il servizio: ```bash @@ -3040,9 +3038,9 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de ``` Questo arresta/avvia il **servizio supervisionato** (launchd su macOS, systemd su Linux). - Usalo quando il Gateway viene eseguito in background come demone. + Usalo quando il Gateway gira in background come demone. - Se lo stai eseguendo in foreground, arrestalo con Ctrl-C, poi: + Se stai eseguendo in foreground, arresta con Ctrl-C, poi: ```bash openclaw gateway run @@ -3052,17 +3050,17 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de - + - `openclaw gateway restart`: riavvia il **servizio in background** (launchd/systemd). - `openclaw gateway`: esegue il gateway **in foreground** per questa sessione del terminale. Se hai installato il servizio, usa i comandi gateway. Usa `openclaw gateway` quando - vuoi un'esecuzione una tantum in foreground. + vuoi un'esecuzione occasionale in foreground. - - Avvia il Gateway con `--verbose` per ottenere più dettagli nella console. Poi ispeziona il file di log per autenticazione del canale, routing del modello ed errori RPC. + + Avvia il Gateway con `--verbose` per ottenere più dettagli nella console. Poi ispeziona il file di log per autenticazione del canale, instradamento del modello ed errori RPC. @@ -3070,9 +3068,9 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de - Gli allegati in uscita dall'agente devono includere una riga `MEDIA:` (su una riga separata). Vedi [Configurazione dell'assistente OpenClaw](/it/start/openclaw) e [Invio agent](/it/tools/agent-send). + Gli allegati in uscita dall'agent devono includere una riga `MEDIA:` (su una riga separata). Vedi [Configurazione dell'assistente OpenClaw](/it/start/openclaw) e [Invio agent](/it/tools/agent-send). - Invio CLI: + Invio da CLI: ```bash openclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png @@ -3080,70 +3078,70 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de Controlla anche: - - Il canale di destinazione supporta media in uscita e non è bloccato dalle allowlist. - - Il file rientra nei limiti di dimensione del provider (le immagini vengono ridimensionate a un massimo di 2048 px). - - `tools.fs.workspaceOnly=true` mantiene gli invii con percorso locale limitati a workspace, temp/media-store e file convalidati dalla sandbox. - - `tools.fs.workspaceOnly=false` permette a `MEDIA:` di inviare file locali dell'host che l'agente può già leggere, ma solo per media più tipi di documenti sicuri (immagini, audio, video, PDF e documenti Office). I file di testo normale e quelli simili a segreti restano comunque bloccati. + - Il canale di destinazione supporta i media in uscita e non è bloccato dalle allowlist. + - Il file rientra nei limiti di dimensione del provider (le immagini vengono ridimensionate a max 2048px). + - `tools.fs.workspaceOnly=true` mantiene gli invii da percorso locale limitati al workspace, temp/media-store e file convalidati dalla sandbox. + - `tools.fs.workspaceOnly=false` consente a `MEDIA:` di inviare file locali dell'host che l'agent può già leggere, ma solo per media più tipi di documenti sicuri (immagini, audio, video, PDF e documenti Office). Testo semplice e file simili a segreti restano comunque bloccati. Vedi [Immagini](/it/nodes/images). -## Sicurezza e controllo degli accessi +## Sicurezza e controllo accessi - Tratta i DM in ingresso come input non attendibili. Le impostazioni predefinite sono progettate per ridurre il rischio: + Tratta i DM in ingresso come input non attendibile. I valori predefiniti sono progettati per ridurre il rischio: - Il comportamento predefinito sui canali compatibili con DM è **pairing**: - I mittenti sconosciuti ricevono un codice di pairing; il bot non elabora il loro messaggio. - Approva con: `openclaw pairing approve --channel [--account ] ` - Le richieste in sospeso sono limitate a **3 per canale**; controlla `openclaw pairing list --channel [--account ]` se un codice non è arrivato. - - Aprire pubblicamente i DM richiede un opt-in esplicito (`dmPolicy: "open"` e allowlist `"*"`). + - Aprire pubblicamente i DM richiede opt-in esplicito (`dmPolicy: "open"` e allowlist `"*"`). - Esegui `openclaw doctor` per far emergere policy DM rischiose. + Esegui `openclaw doctor` per far emergere criteri DM rischiosi. No. La prompt injection riguarda il **contenuto non attendibile**, non solo chi può inviare DM al bot. - Se il tuo assistente legge contenuti esterni (web search/fetch, pagine del browser, email, + Se il tuo assistente legge contenuti esterni (ricerca/recupero web, pagine del browser, email, documenti, allegati, log incollati), quel contenuto può includere istruzioni che tentano - di dirottare il modello. Questo può accadere anche se **tu sei l'unico mittente**. + di dirottare il modello. Questo può accadere anche se **sei tu l'unico mittente**. - Il rischio maggiore si ha quando gli strumenti sono abilitati: il modello può essere indotto a - esfiltrare contesto o chiamare strumenti per tuo conto. Riduci il raggio d'azione: + Il rischio maggiore si ha quando gli strumenti sono abilitati: il modello può essere indotto + a esfiltrare contesto o a chiamare strumenti per tuo conto. Riduci il raggio d'azione in questo modo: - - usando un agent "reader" in sola lettura o senza strumenti per riepilogare contenuti non attendibili - - mantenendo `web_search` / `web_fetch` / `browser` disattivati per agent con strumenti abilitati - - trattando come non attendibile anche il testo decodificato da file/documenti: OpenResponses - `input_file` e l'estrazione da allegati multimediali avvolgono entrambi il testo estratto in - marcatori espliciti di confine del contenuto esterno invece di passare testo grezzo del file - - sandboxing e allowlist rigorose degli strumenti + - usa un agent "reader" in sola lettura o senza strumenti per riepilogare contenuti non attendibili + - mantieni `web_search` / `web_fetch` / `browser` disattivati per gli agent con strumenti abilitati + - tratta come non attendibile anche il testo decodificato di file/documenti: OpenResponses + `input_file` e l'estrazione di allegati media racchiudono entrambi il testo estratto in + marcatori espliciti di confine del contenuto esterno invece di passare il testo grezzo del file + - sandboxing e allowlist rigide degli strumenti Dettagli: [Sicurezza](/it/gateway/security). - - Sì, per la maggior parte delle configurazioni. Isolare il bot con account e numeri di telefono separati - riduce il raggio d'azione se qualcosa va storto. Questo rende anche più facile ruotare + + Sì, nella maggior parte delle configurazioni. Isolare il bot con account e numeri di telefono separati + riduce il raggio d'azione se qualcosa va storto. Inoltre rende più facile ruotare le credenziali o revocare l'accesso senza impattare i tuoi account personali. - Inizia in piccolo. Concedi accesso solo agli strumenti e agli account di cui hai realmente bisogno, e amplia - più avanti se necessario. + Inizia in piccolo. Concedi accesso solo agli strumenti e agli account di cui hai davvero bisogno, ed espandi + in seguito se necessario. Documentazione: [Sicurezza](/it/gateway/security), [Pairing](/it/channels/pairing). - **Non** consigliamo piena autonomia sui tuoi messaggi personali. Il modello più sicuro è: + **Non** consigliamo piena autonomia sui tuoi messaggi personali. Il pattern più sicuro è: - - Mantieni i DM in modalità **pairing** o con una allowlist ristretta. + - Mantieni i DM in **modalità pairing** o con un'allowlist rigida. - Usa un **numero o account separato** se vuoi che invii messaggi per tuo conto. - - Lascia che prepari una bozza, poi **approva prima dell'invio**. + - Lascia che prepari la bozza, poi **approva prima dell'invio**. Se vuoi sperimentare, fallo su un account dedicato e mantienilo isolato. Vedi [Sicurezza](/it/gateway/security). @@ -3151,14 +3149,14 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de - Sì, **se** l'agent è solo chat e l'input è attendibile. I livelli più piccoli sono + Sì, **se** l'agent è solo chat e l'input è attendibile. I tier più piccoli sono più suscettibili al dirottamento delle istruzioni, quindi evitali per agent con strumenti abilitati - o quando leggono contenuti non attendibili. Se devi usare un modello più piccolo, limita - gli strumenti ed eseguilo in una sandbox. Vedi [Sicurezza](/it/gateway/security). + o quando leggono contenuti non attendibili. Se devi usare un modello più piccolo, blocca + gli strumenti ed esegui dentro una sandbox. Vedi [Sicurezza](/it/gateway/security). - I codici di pairing vengono inviati **solo** quando un mittente sconosciuto invia un messaggio al bot e + I codici di pairing vengono inviati **solo** quando un mittente sconosciuto scrive al bot e `dmPolicy: "pairing"` è abilitato. `/start` da solo non genera un codice. Controlla le richieste in sospeso: @@ -3167,13 +3165,13 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de openclaw pairing list telegram ``` - Se vuoi accesso immediato, inserisci il tuo ID mittente nell'allowlist oppure imposta `dmPolicy: "open"` + Se vuoi accesso immediato, aggiungi all'allowlist il tuo sender id oppure imposta `dmPolicy: "open"` per quell'account. - - No. La policy DM predefinita di WhatsApp è **pairing**. I mittenti sconosciuti ricevono solo un codice di pairing e il loro messaggio **non viene elaborato**. OpenClaw risponde solo alle chat che riceve o agli invii espliciti che attivi tu. + + No. Il criterio DM predefinito di WhatsApp è **pairing**. I mittenti sconosciuti ricevono solo un codice di pairing e il loro messaggio **non viene elaborato**. OpenClaw risponde solo alle chat che riceve o a invii espliciti che attivi tu. Approva il pairing con: @@ -3187,7 +3185,7 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de openclaw pairing list whatsapp ``` - Prompt del numero di telefono nella procedura guidata: serve a impostare la tua **allowlist/proprietario** in modo che i tuoi DM siano consentiti. Non viene usato per invii automatici. Se lo esegui sul tuo numero WhatsApp personale, usa quel numero e abilita `channels.whatsapp.selfChatMode`. + Prompt del numero di telefono nella procedura guidata: viene usato per impostare la tua **allowlist/owner** in modo che i tuoi DM siano consentiti. Non viene usato per l'invio automatico. Se esegui sul tuo numero WhatsApp personale, usa quel numero e abilita `channels.whatsapp.selfChatMode`. @@ -3195,11 +3193,11 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de ## Comandi chat, interruzione delle attività e "non si ferma" - - La maggior parte dei messaggi interni o degli strumenti appare solo quando **verbose**, **trace** o **reasoning** è abilitato + + La maggior parte dei messaggi interni o degli strumenti compare solo quando **verbose**, **trace** o **reasoning** è abilitato per quella sessione. - Correzione nella chat dove lo vedi: + Correzione nella chat in cui lo vedi: ``` /verbose off @@ -3207,7 +3205,7 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de /reasoning off ``` - Se continua a esserci troppo rumore, controlla le impostazioni della sessione nella Control UI e imposta verbose + Se è ancora rumoroso, controlla le impostazioni della sessione nella Control UI e imposta verbose su **inherit**. Conferma anche di non usare un profilo bot con `verboseDefault` impostato su `on` nella configurazione. @@ -3215,7 +3213,7 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de - + Invia uno di questi **come messaggio autonomo** (senza slash): ``` @@ -3242,7 +3240,7 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de Questi sono trigger di interruzione (non comandi slash). - Per i processi in background (dallo strumento exec), puoi chiedere all'agente di eseguire: + Per i processi in background (dallo strumento exec), puoi chiedere all'agent di eseguire: ``` process action:kill sessionId:XXX @@ -3250,12 +3248,12 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de Panoramica dei comandi slash: vedi [Comandi slash](/it/tools/slash-commands). - La maggior parte dei comandi deve essere inviata come **messaggio autonomo** che inizia con `/`, ma alcune scorciatoie (come `/status`) funzionano anche inline per i mittenti in allowlist. + La maggior parte dei comandi deve essere inviata come messaggio **autonomo** che inizia con `/`, ma alcune scorciatoie (come `/status`) funzionano anche inline per i mittenti in allowlist. - - OpenClaw blocca per impostazione predefinita la messaggistica **cross-provider**. Se una chiamata di strumento è associata + + OpenClaw blocca per impostazione predefinita la messaggistica **cross-provider**. Se una chiamata allo strumento è associata a Telegram, non invierà a Discord a meno che tu non lo consenta esplicitamente. Abilita la messaggistica cross-provider per l'agent: @@ -3277,13 +3275,13 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de - - La modalità queue controlla come i nuovi messaggi interagiscono con un'esecuzione in corso. Usa `/queue` per cambiare modalità: + + La modalità coda controlla come i nuovi messaggi interagiscono con un'esecuzione in corso. Usa `/queue` per cambiare modalità: - `steer` - i nuovi messaggi reindirizzano l'attività corrente - `followup` - esegue i messaggi uno alla volta - `collect` - raggruppa i messaggi e risponde una sola volta (predefinito) - - `steer-backlog` - reindirizza ora, poi elabora l'arretrato + - `steer-backlog` - reindirizza ora, poi elabora il backlog - `interrupt` - interrompe l'esecuzione corrente e ne avvia una nuova Puoi aggiungere opzioni come `debounce:2s cap:25 drop:summarize` per le modalità followup. @@ -3295,10 +3293,10 @@ Correlato: [/concepts/oauth](/it/concepts/oauth) (flussi OAuth, archiviazione de - In OpenClaw, credenziali e selezione del modello sono separate. Impostare `ANTHROPIC_API_KEY` (oppure archiviare una chiave API Anthropic nei profili di autenticazione) abilita l'autenticazione, ma il modello predefinito effettivo è quello che configuri in `agents.defaults.model.primary` (per esempio, `anthropic/claude-sonnet-4-6` oppure `anthropic/claude-opus-4-6`). Se vedi `No credentials found for profile "anthropic:default"`, significa che il Gateway non è riuscito a trovare credenziali Anthropic nell'atteso `auth-profiles.json` per l'agent in esecuzione. + In OpenClaw, credenziali e selezione del modello sono separate. Impostare `ANTHROPIC_API_KEY` (oppure memorizzare una chiave API Anthropic nei profili di autenticazione) abilita l'autenticazione, ma il vero modello predefinito è quello che configuri in `agents.defaults.model.primary` (ad esempio `anthropic/claude-sonnet-4-6` oppure `anthropic/claude-opus-4-6`). Se vedi `No credentials found for profile "anthropic:default"`, significa che il Gateway non è riuscito a trovare credenziali Anthropic nel file `auth-profiles.json` previsto per l'agent in esecuzione. --- -Ancora bloccato? Chiedi su [Discord](https://discord.com/invite/clawd) oppure apri una [discussione GitHub](https://github.com/openclaw/openclaw/discussions). +Ancora bloccato? Chiedi in [Discord](https://discord.com/invite/clawd) oppure apri una [discussione GitHub](https://github.com/openclaw/openclaw/discussions). diff --git a/docs/it/help/testing.md b/docs/it/help/testing.md index 8621679df..e900ed61b 100644 --- a/docs/it/help/testing.md +++ b/docs/it/help/testing.md @@ -1,134 +1,136 @@ --- read_when: - - Eseguire i test in locale o in CI - - Aggiunta di test di regressione per bug di modello/provider - - Debug del comportamento di Gateway + agente + - Esecuzione dei test in locale o in CI + - Aggiunta di test di regressione per bug di modelli/provider + - Debug del comportamento di Gateway + agent summary: 'Kit di test: suite unit/e2e/live, runner Docker e cosa copre ciascun test' -title: Testare +title: Test x-i18n: - generated_at: "2026-04-18T08:05:13Z" + generated_at: "2026-04-20T08:31:22Z" model: gpt-5.4 provider: openai - source_hash: 7cdd2048ba58e606fd68703977c2b33000abdb1826b6589ce25a35c53468726a + source_hash: 88457038e2e2c7940d0348762d0ece187111a8c61fa9bad54b39eade4217ddbc source_path: help/testing.md workflow: 15 --- # Test -OpenClaw ha tre suite Vitest (unit/integration, e2e, live) e un piccolo insieme di runner Docker. +OpenClaw dispone di tre suite Vitest (unit/integration, e2e, live) e di un piccolo insieme di runner Docker. Questo documento è una guida a “come testiamo”: - Cosa copre ciascuna suite (e cosa deliberatamente _non_ copre) -- Quali comandi eseguire per i flussi di lavoro più comuni (locale, pre-push, debug) -- Come i test live individuano le credenziali e selezionano modelli/provider -- Come aggiungere test di regressione per problemi reali di modelli/provider +- Quali comandi eseguire per i flussi di lavoro comuni (locale, pre-push, debug) +- Come i test live rilevano le credenziali e selezionano modelli/provider +- Come aggiungere regressioni per problemi reali di modelli/provider ## Avvio rapido -La maggior parte dei giorni: +Nella maggior parte dei casi: - Gate completo (previsto prima del push): `pnpm build && pnpm check && pnpm test` - Esecuzione locale più rapida dell’intera suite su una macchina capiente: `pnpm test:max` -- Loop di watch diretto di Vitest: `pnpm test:watch` -- Il targeting diretto dei file ora instrada anche i percorsi di extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Preferisci prima le esecuzioni mirate quando stai iterando su un singolo errore. +- Loop di watch Vitest diretto: `pnpm test:watch` +- Il targeting diretto dei file ora instrada anche i percorsi extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Quando stai iterando su un singolo errore, preferisci prima esecuzioni mirate. - Sito QA basato su Docker: `pnpm qa:lab:up` -- Corsia QA basata su VM Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- Lane QA basata su VM Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Quando tocchi i test o vuoi maggiore confidenza: +Quando modifichi i test o vuoi maggiore confidenza: -- Gate di coverage: `pnpm test:coverage` +- Gate di copertura: `pnpm test:coverage` - Suite E2E: `pnpm test:e2e` -Quando fai debug di provider/modelli reali (richiede credenziali reali): +Quando esegui il debug di provider/modelli reali (richiede credenziali reali): -- Suite live (modelli + probe di tool/immagini del gateway): `pnpm test:live` -- Punta in modo silenzioso a un singolo file live: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Suite live (modelli + probe tool/immagini del Gateway): `pnpm test:live` +- Esegui in modo silenzioso un solo file live: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Suggerimento: quando ti serve solo un singolo caso che fallisce, preferisci restringere i test live tramite le variabili d’ambiente di allowlist descritte sotto. +Suggerimento: quando ti serve solo un caso che fallisce, preferisci restringere i test live tramite le variabili d’ambiente di allowlist descritte sotto. ## Runner specifici per QA -Questi comandi si affiancano alle suite di test principali quando ti serve il realismo di QA-lab: +Questi comandi si affiancano alle principali suite di test quando ti serve il realismo di qa-lab: - `pnpm openclaw qa suite` - - Esegue direttamente sull’host scenari QA basati sul repository. - - Esegue per impostazione predefinita più scenari selezionati in parallelo con worker gateway isolati, fino a 64 worker o al numero di scenari selezionati. Usa `--concurrency ` per regolare il numero di worker, oppure `--concurrency 1` per la vecchia corsia seriale. + - Esegue scenari QA supportati dal repository direttamente sull’host. + - Esegue più scenari selezionati in parallelo per impostazione predefinita con worker Gateway isolati. `qa-channel` usa per impostazione predefinita una concorrenza pari a 4 (limitata dal numero di scenari selezionati). Usa `--concurrency ` per regolare il numero di worker, oppure `--concurrency 1` per il vecchio lane seriale. + - Termina con codice diverso da zero quando uno scenario fallisce. Usa `--allow-failures` quando vuoi ottenere gli artifact senza un codice di uscita di errore. - Supporta le modalità provider `live-frontier`, `mock-openai` e `aimock`. - `aimock` avvia un server provider locale basato su AIMock per copertura sperimentale di fixture e protocol-mock senza sostituire la corsia `mock-openai` basata sugli scenari. + `aimock` avvia un server provider locale basato su AIMock per copertura sperimentale di fixture e mock di protocollo senza sostituire il lane `mock-openai` basato sugli scenari. - `pnpm openclaw qa suite --runner multipass` - Esegue la stessa suite QA all’interno di una VM Linux Multipass usa e getta. - Mantiene lo stesso comportamento di selezione degli scenari di `qa suite` sull’host. - Riutilizza gli stessi flag di selezione provider/modello di `qa suite`. - - Le esecuzioni live inoltrano gli input di autenticazione QA supportati che sono pratici per il guest: - chiavi provider basate su env, il percorso della configurazione del provider live QA e `CODEX_HOME` quando presente. - - Le directory di output devono restare sotto la root del repository così il guest può riscriverle tramite il workspace montato. - - Scrive il normale report + riepilogo QA più i log di Multipass sotto + - Le esecuzioni live inoltrano gli input di autenticazione QA supportati e pratici per il guest: + chiavi provider basate su env, il percorso di configurazione del provider live QA e `CODEX_HOME` quando presente. + - Le directory di output devono rimanere sotto la root del repository affinché il guest possa scrivere di nuovo tramite il workspace montato. + - Scrive il report QA normale + il riepilogo più i log Multipass sotto `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Avvia il sito QA basato su Docker per lavoro QA in stile operatore. + - Avvia il sito QA basato su Docker per il lavoro QA in stile operatore. - `pnpm openclaw qa aimock` - Avvia solo il server provider AIMock locale per smoke test diretti del protocollo. - `pnpm openclaw qa matrix` - - Esegue la corsia QA live di Matrix contro un homeserver Tuwunel temporaneo basato su Docker. - - Questo host QA oggi è solo per repository/sviluppo. Le installazioni pacchettizzate di OpenClaw non distribuiscono `qa-lab`, quindi non espongono `openclaw qa`. - - I checkout del repository caricano direttamente il runner incluso; non è necessario alcun passaggio separato di installazione del plugin. - - Effettua il provisioning di tre utenti Matrix temporanei (`driver`, `sut`, `observer`) più una stanza privata, quindi avvia un processo figlio del gateway QA con il vero plugin Matrix come trasporto SUT. - - Usa per impostazione predefinita l’immagine stabile Tuwunel fissata `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Sostituiscila con `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` quando devi testare un’immagine diversa. - - Matrix non espone flag condivisi di origine delle credenziali perché la corsia effettua localmente il provisioning di utenti temporanei. - - Scrive un report QA di Matrix, un riepilogo, un artifact degli eventi osservati e un log combinato stdout/stderr sotto `.artifacts/qa-e2e/...`. + - Esegue il lane QA live di Matrix contro un homeserver Tuwunel usa e getta basato su Docker. + - Questo host QA oggi è solo per repo/dev. Le installazioni OpenClaw pacchettizzate non distribuiscono `qa-lab`, quindi non espongono `openclaw qa`. + - I checkout del repository caricano direttamente il runner incluso; non è necessario un passaggio separato di installazione del plugin. + - Effettua il provisioning di tre utenti Matrix temporanei (`driver`, `sut`, `observer`) più una stanza privata, quindi avvia un processo figlio del gateway QA con il vero plugin Matrix come trasporto del SUT. + - Usa per impostazione predefinita l’immagine Tuwunel stabile fissata `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Sostituiscila con `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` quando devi testare un’immagine diversa. + - Matrix non espone flag condivisi di origine credenziali perché il lane effettua localmente il provisioning di utenti usa e getta. + - Scrive un report QA Matrix, un riepilogo, un artifact degli eventi osservati e un log combinato stdout/stderr sotto `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Esegue la corsia QA live di Telegram contro un vero gruppo privato usando i token del bot driver e del bot SUT dall’env. + - Esegue il lane QA live di Telegram contro un gruppo privato reale usando i token bot del driver e del SUT dall’env. - Richiede `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` e `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. L’id del gruppo deve essere l’id numerico della chat Telegram. - - Supporta `--credential-source convex` per credenziali condivise in pool. Usa la modalità env per impostazione predefinita, oppure imposta `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` per usare lease in pool. + - Supporta `--credential-source convex` per credenziali condivise in pool. Usa la modalità env per impostazione predefinita, oppure imposta `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` per attivare i lease in pool. + - Termina con codice diverso da zero quando uno scenario fallisce. Usa `--allow-failures` quando vuoi ottenere gli artifact senza un codice di uscita di errore. - Richiede due bot distinti nello stesso gruppo privato, con il bot SUT che espone un nome utente Telegram. - - Per un’osservazione stabile bot-to-bot, abilita la Bot-to-Bot Communication Mode in `@BotFather` per entrambi i bot e assicurati che il bot driver possa osservare il traffico dei bot nel gruppo. - - Scrive un report QA di Telegram, un riepilogo e un artifact dei messaggi osservati sotto `.artifacts/qa-e2e/...`. + - Per un’osservazione stabile bot-to-bot, abilita Bot-to-Bot Communication Mode in `@BotFather` per entrambi i bot e assicurati che il bot driver possa osservare il traffico dei bot nel gruppo. + - Scrive un report QA Telegram, un riepilogo e un artifact dei messaggi osservati sotto `.artifacts/qa-e2e/...`. -Le corsie live di trasporto condividono un unico contratto standard così i nuovi trasporti non divergono: +I lane di trasporto live condividono un contratto standard così che i nuovi trasporti non divergano. -`qa-channel` resta la suite QA sintetica ampia e non fa parte della matrice di copertura dei trasporti live. +`qa-channel` rimane la suite QA sintetica ampia e non fa parte della matrice di copertura dei trasporti live. -| Corsia | Canary | Gating delle mention | Blocco allowlist | Risposta di primo livello | Ripresa dopo riavvio | Follow-up nel thread | Isolamento del thread | Osservazione delle reazioni | Comando help | -| -------- | ------ | -------------------- | ---------------- | ------------------------- | -------------------- | ------------------- | -------------------- | --------------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Lane | Canary | Blocco menzioni | Blocco allowlist | Risposta di primo livello | Ripresa dopo riavvio | Follow-up del thread | Isolamento del thread | Osservazione reazioni | Comando help | +| -------- | ------ | --------------- | ---------------- | ------------------------- | -------------------- | ------------------- | --------------------- | --------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### Credenziali Telegram condivise tramite Convex (v1) Quando `--credential-source convex` (o `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) è abilitato per -`openclaw qa telegram`, QA lab acquisisce un lease esclusivo da un pool basato su Convex, invia heartbeat -per quel lease mentre la corsia è in esecuzione e rilascia il lease alla chiusura. +`openclaw qa telegram`, il laboratorio QA acquisisce un lease esclusivo da un pool supportato da Convex, invia heartbeat +a quel lease mentre il lane è in esecuzione e rilascia il lease allo spegnimento. -Scaffold di riferimento del progetto Convex: +Scaffold del progetto Convex di riferimento: - `qa/convex-credential-broker/` -Variabili d’ambiente obbligatorie: +Variabili d’ambiente richieste: -- `OPENCLAW_QA_CONVEX_SITE_URL` (per esempio `https://your-deployment.convex.site`) +- `OPENCLAW_QA_CONVEX_SITE_URL` (ad esempio `https://your-deployment.convex.site`) - Un secret per il ruolo selezionato: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` per `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` per `ci` - Selezione del ruolo delle credenziali: - CLI: `--credential-role maintainer|ci` - - Valore predefinito env: `OPENCLAW_QA_CREDENTIAL_ROLE` (predefinito `maintainer`) + - Valore predefinito env: `OPENCLAW_QA_CREDENTIAL_ROLE` (in CI il valore predefinito è `ci`, altrimenti `maintainer`) -Variabili d’ambiente facoltative: +Variabili d’ambiente opzionali: - `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (predefinito `1200000`) - `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (predefinito `30000`) - `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (predefinito `90000`) - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (predefinito `15000`) - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (predefinito `/qa-credentials/v1`) -- `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (id di tracciamento facoltativo) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` consente URL Convex loopback `http://` solo per sviluppo locale. +- `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (id di tracciamento opzionale) +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` consente URL Convex `http://` loopback per sviluppo solo locale. -`OPENCLAW_QA_CONVEX_SITE_URL` dovrebbe usare `https://` nel normale funzionamento. +`OPENCLAW_QA_CONVEX_SITE_URL` dovrebbe usare `https://` nel funzionamento normale. -I comandi CLI di amministrazione per maintainer (aggiungi/rimuovi/elenca pool) richiedono +I comandi amministrativi del maintainer (aggiunta/rimozione/elenco del pool) richiedono specificamente `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. Helper CLI per i maintainer: @@ -139,14 +141,14 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Usa `--json` per output leggibile da macchine in script e utility CI. +Usa `--json` per output leggibile dalle macchine negli script e nelle utility CI. Contratto endpoint predefinito (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - Richiesta: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` - Successo: `{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` - - Esaurito/ripetibile: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` + - Esaurito/riprovabile: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` - `POST /heartbeat` - Richiesta: `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` - Successo: `{ status: "ok" }` (o `2xx` vuoto) @@ -159,7 +161,7 @@ Contratto endpoint predefinito (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials - `POST /admin/remove` (solo secret maintainer) - Richiesta: `{ credentialId, actorId }` - Successo: `{ status: "ok", changed, credential }` - - Guardia lease attivo: `{ status: "error", code: "LEASE_ACTIVE", ... }` + - Guardia contro lease attivo: `{ status: "error", code: "LEASE_ACTIVE", ... }` - `POST /admin/list` (solo secret maintainer) - Richiesta: `{ kind?, status?, includePayload?, limit? }` - Successo: `{ status: "ok", credentials, count }` @@ -167,8 +169,8 @@ Contratto endpoint predefinito (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials Forma del payload per il tipo Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` deve essere una stringa con l’id numerico della chat Telegram. -- `admin/add` valida questa forma per `kind: "telegram"` e rifiuta payload malformati. +- `groupId` deve essere una stringa id numerica della chat Telegram. +- `admin/add` convalida questa forma per `kind: "telegram"` e rifiuta payload malformati. ### Aggiungere un canale a QA @@ -179,7 +181,7 @@ Aggiungere un canale al sistema QA markdown richiede esattamente due cose: Non aggiungere una nuova root di comando QA di primo livello quando l’host condiviso `qa-lab` può gestire il flusso. -`qa-lab` gestisce la meccanica condivisa dell’host: +`qa-lab` gestisce i meccanismi condivisi dell’host: - la root di comando `openclaw qa` - avvio e teardown della suite @@ -187,39 +189,39 @@ Non aggiungere una nuova root di comando QA di primo livello quando l’host con - scrittura degli artifact - generazione dei report - esecuzione degli scenari -- alias di compatibilità per scenari `qa-channel` più vecchi +- alias di compatibilità per i vecchi scenari `qa-channel` I plugin runner gestiscono il contratto di trasporto: - come `openclaw qa ` viene montato sotto la root condivisa `qa` -- come il gateway viene configurato per quel trasporto +- come viene configurato il gateway per quel trasporto - come viene verificata la readiness - come vengono iniettati gli eventi in ingresso - come vengono osservati i messaggi in uscita -- come vengono esposti transcript e stato di trasporto normalizzato +- come vengono esposti transcript e stato normalizzato del trasporto - come vengono eseguite le azioni supportate dal trasporto -- come viene gestito reset o cleanup specifico del trasporto +- come viene gestito il reset o la pulizia specifici del trasporto La soglia minima di adozione per un nuovo canale è: 1. Mantenere `qa-lab` come proprietario della root condivisa `qa`. -2. Implementare il runner di trasporto sull’interfaccia host condivisa di `qa-lab`. -3. Mantenere la meccanica specifica del trasporto all’interno del plugin runner o dell’harness del plugin channel. +2. Implementare il runner di trasporto sulla seam dell’host condiviso `qa-lab`. +3. Mantenere i meccanismi specifici del trasporto all’interno del plugin runner o dell’harness del canale. 4. Montare il runner come `openclaw qa ` invece di registrare una root di comando concorrente. - I plugin runner dovrebbero dichiarare `qaRunners` in `openclaw.plugin.json` ed esportare un array `qaRunnerCliRegistrations` corrispondente da `runtime-api.ts`. - Mantieni `runtime-api.ts` leggero; la CLI lazy e l’esecuzione del runner dovrebbero restare dietro entrypoint separati. + I plugin runner devono dichiarare `qaRunners` in `openclaw.plugin.json` ed esportare un array corrispondente `qaRunnerCliRegistrations` da `runtime-api.ts`. + Mantieni `runtime-api.ts` leggero; la CLI lazy e l’esecuzione del runner devono restare dietro entrypoint separati. 5. Creare o adattare scenari markdown nelle directory tematiche `qa/scenarios/`. -6. Usare gli helper generici degli scenari per i nuovi scenari. -7. Mantenere funzionanti gli alias di compatibilità esistenti, salvo che il repository stia effettuando una migrazione intenzionale. +6. Usare gli helper di scenario generici per i nuovi scenari. +7. Mantenere funzionanti gli alias di compatibilità esistenti a meno che il repository non stia eseguendo una migrazione intenzionale. La regola decisionale è rigida: - Se un comportamento può essere espresso una sola volta in `qa-lab`, mettilo in `qa-lab`. -- Se un comportamento dipende da un solo trasporto di canale, mantienilo in quel plugin runner o nell’harness del plugin. -- Se uno scenario ha bisogno di una nuova capability che più di un canale può usare, aggiungi un helper generico invece di un branch specifico del canale in `suite.ts`. -- Se un comportamento ha significato solo per un trasporto, mantieni lo scenario specifico del trasporto e rendilo esplicito nel contratto dello scenario. +- Se un comportamento dipende da un trasporto di canale, mantienilo in quel plugin runner o harness del plugin. +- Se uno scenario richiede una nuova capacità che può essere usata da più di un canale, aggiungi un helper generico invece di un ramo specifico del canale in `suite.ts`. +- Se un comportamento ha senso solo per un trasporto, mantieni lo scenario specifico del trasporto e rendilo esplicito nel contratto dello scenario. -I nomi preferiti dei nuovi helper generici per i nuovi scenari sono: +I nomi helper generici preferiti per i nuovi scenari sono: - `waitForTransportReady` - `waitForChannelReady` @@ -234,7 +236,7 @@ I nomi preferiti dei nuovi helper generici per i nuovi scenari sono: - `formatTransportTranscript` - `resetTransport` -Restano disponibili alias di compatibilità per gli scenari esistenti, inclusi: +Gli alias di compatibilità restano disponibili per gli scenari esistenti, inclusi: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -242,160 +244,160 @@ Restano disponibili alias di compatibilità per gli scenari esistenti, inclusi: - `formatConversationTranscript` - `resetBus` -Il nuovo lavoro sui canali dovrebbe usare i nomi generici degli helper. -Gli alias di compatibilità esistono per evitare una migrazione in un solo giorno, non come modello per -la scrittura di nuovi scenari. +Il nuovo lavoro sui canali dovrebbe usare i nomi helper generici. +Gli alias di compatibilità esistono per evitare una migrazione in un unico giorno, non come modello per +la creazione di nuovi scenari. ## Suite di test (cosa viene eseguito dove) -Pensa alle suite come a livelli di “realismo crescente” (e di flakiness/costo crescente): +Pensa alle suite come a un aumento progressivo del “realismo” (e dell’instabilità/costo): ### Unit / integration (predefinita) - Comando: `pnpm test` -- Configurazione: dieci esecuzioni shard sequenziali (`vitest.full-*.config.ts`) sui progetti Vitest scoped esistenti -- File: inventari core/unit sotto `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` e i test node `ui` in allowlist coperti da `vitest.unit.config.ts` +- Configurazione: dieci esecuzioni shard sequenziali (`vitest.full-*.config.ts`) sui progetti Vitest con ambito esistenti +- File: inventari core/unit in `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` e i test node `ui` in allowlist coperti da `vitest.unit.config.ts` - Ambito: - Test unitari puri - - Test di integrazione in-process (autenticazione gateway, routing, tooling, parsing, configurazione) + - Test di integrazione in-process (autenticazione gateway, instradamento, tooling, parsing, configurazione) - Regressioni deterministiche per bug noti - Aspettative: - Viene eseguita in CI - Non richiede chiavi reali - Dovrebbe essere veloce e stabile - Nota sui progetti: - - `pnpm test` senza target ora esegue undici configurazioni shard più piccole (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) invece di un unico enorme processo nativo root-project. Questo riduce il picco di RSS su macchine cariche ed evita che il lavoro di auto-reply/extension sottragga risorse alle suite non correlate. - - `pnpm test --watch` usa ancora il grafo di progetti nativo root `vitest.config.ts`, perché un loop watch multi-shard non è pratico. - - `pnpm test`, `pnpm test:watch` e `pnpm test:perf:imports` instradano prima i target espliciti di file/directory attraverso corsie scoped, quindi `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita di pagare il costo di avvio dell’intero root project. - - `pnpm test:changed` espande i percorsi git modificati nelle stesse corsie scoped quando il diff tocca solo file sorgente/test instradabili; le modifiche a config/setup tornano comunque alla riesecuzione ampia del root-project. - - I test unitari leggeri dal punto di vista degli import da agent, comandi, plugin, helper auto-reply, `plugin-sdk` e aree di utility pure simili vengono instradati attraverso la corsia `unit-fast`, che salta `test/setup-openclaw-runtime.ts`; i file stateful/runtime-heavy restano sulle corsie esistenti. - - Anche alcuni file helper sorgente di `plugin-sdk` e `commands` mappano le esecuzioni in modalità changed a test sibling espliciti in quelle corsie leggere, così le modifiche agli helper evitano di rieseguire l’intera suite pesante per quella directory. - - `auto-reply` ora ha tre bucket dedicati: helper core di primo livello, test di integrazione `reply.*` di primo livello e il sottoalbero `src/auto-reply/reply/**`. Questo mantiene il lavoro più pesante dell’harness reply fuori dai test economici di status/chunk/token. -- Nota sul runner embedded: - - Quando modifichi gli input di discovery dei message-tool o il contesto runtime di Compaction, + - `pnpm test` senza target ora esegue undici configurazioni shard più piccole (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) invece di un unico enorme processo nativo root-project. Questo riduce il picco di RSS su macchine cariche ed evita che il lavoro di auto-reply/extension penalizzi suite non correlate. + - `pnpm test --watch` continua a usare il grafo di progetto nativo root `vitest.config.ts`, perché un loop watch multi-shard non è pratico. + - `pnpm test`, `pnpm test:watch` e `pnpm test:perf:imports` instradano prima i target espliciti di file/directory attraverso lane con ambito, quindi `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita di pagare il costo completo di avvio del progetto root. + - `pnpm test:changed` espande i percorsi git modificati negli stessi lane con ambito quando il diff tocca solo file sorgente/test instradabili; le modifiche a config/setup ricadono comunque sulla riesecuzione ampia del progetto root. + - I test unitari leggeri in termini di import provenienti da agent, comandi, plugin, helper auto-reply, `plugin-sdk` e aree simili di pura utilità vengono instradati attraverso il lane `unit-fast`, che salta `test/setup-openclaw-runtime.ts`; i file con stato/runtime pesante restano sui lane esistenti. + - Alcuni file sorgente helper selezionati di `plugin-sdk` e `commands` mappano anche le esecuzioni in modalità changed verso test sibling espliciti in quei lane leggeri, così le modifiche agli helper evitano di rieseguire l’intera suite pesante per quella directory. + - `auto-reply` ora ha tre bucket dedicati: helper core di primo livello, test di integrazione `reply.*` di primo livello e il sottoalbero `src/auto-reply/reply/**`. Questo mantiene il lavoro più pesante dell’harness reply fuori dai test economici su status/chunk/token. +- Nota sul runner incorporato: + - Quando modifichi gli input di rilevamento dei message-tool o il contesto runtime di Compaction, mantieni entrambi i livelli di copertura. - Aggiungi regressioni helper mirate per boundary puri di routing/normalizzazione. - - Mantieni anche sane le suite di integrazione dell’embedded runner: + - Mantieni sane anche le suite di integrazione del runner incorporato: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` e `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Queste suite verificano che gli id scoped e il comportamento di Compaction continuino a passare + - Queste suite verificano che gli id con ambito e il comportamento di Compaction continuino a fluire attraverso i percorsi reali `run.ts` / `compact.ts`; i test solo helper non sono un - sostituto sufficiente di questi percorsi di integrazione. + sostituto sufficiente per questi percorsi di integrazione. - Nota sul pool: - - La configurazione base di Vitest ora usa per impostazione predefinita `threads`. - - La configurazione Vitest condivisa imposta anche `isolate: false` e usa il runner non isolato tra i root project, le configurazioni e2e e live. - - La corsia UI root mantiene il proprio setup e optimizer `jsdom`, ma ora gira anch’essa sul runner condiviso non isolato. - - Ogni shard di `pnpm test` eredita gli stessi valori predefiniti `threads` + `isolate: false` dalla configurazione Vitest condivisa. - - Il launcher condiviso `scripts/run-vitest.mjs` ora aggiunge anche `--no-maglev` per impostazione predefinita ai processi Node figli di Vitest, per ridurre il churn di compilazione V8 durante grandi esecuzioni locali. Imposta `OPENCLAW_VITEST_ENABLE_MAGLEV=1` se devi confrontare il comportamento con il comportamento V8 standard. + - La configurazione base di Vitest ora usa `threads` come predefinito. + - La configurazione Vitest condivisa fissa inoltre `isolate: false` e usa il runner non isolato nei progetti root, e2e e live. + - Il lane UI root mantiene la propria configurazione `jsdom` e optimizer, ma ora viene eseguito anch’esso sul runner condiviso non isolato. + - Ogni shard `pnpm test` eredita gli stessi valori predefiniti `threads` + `isolate: false` dalla configurazione Vitest condivisa. + - Il launcher condiviso `scripts/run-vitest.mjs` ora aggiunge anche `--no-maglev` per impostazione predefinita ai processi Node figli di Vitest per ridurre il churn di compilazione V8 durante grandi esecuzioni locali. Imposta `OPENCLAW_VITEST_ENABLE_MAGLEV=1` se devi confrontare il comportamento V8 standard. - Nota sull’iterazione locale veloce: - - `pnpm test:changed` instrada attraverso corsie scoped quando i percorsi modificati mappano in modo pulito a una suite più piccola. + - `pnpm test:changed` instrada attraverso lane con ambito quando i percorsi modificati mappano chiaramente a una suite più piccola. - `pnpm test:max` e `pnpm test:changed:max` mantengono lo stesso comportamento di instradamento, solo con un limite di worker più alto. - - L’auto-scaling locale dei worker ora è intenzionalmente più conservativo e riduce ulteriormente quando il load average dell’host è già alto, così più esecuzioni Vitest concorrenti fanno meno danni per impostazione predefinita. - - La configurazione base di Vitest contrassegna i file di progetto/configurazione come `forceRerunTriggers` così i rieseguiti in modalità changed restano corretti quando cambia il wiring dei test. - - La configurazione mantiene `OPENCLAW_VITEST_FS_MODULE_CACHE` abilitato sugli host supportati; imposta `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` se vuoi una posizione di cache esplicita per profiling diretto. + - L’auto-scaling locale dei worker ora è intenzionalmente conservativo e riduce anche l’attività quando il load average dell’host è già alto, così più esecuzioni Vitest concorrenti fanno meno danni per impostazione predefinita. + - La configurazione base Vitest contrassegna i file projects/config come `forceRerunTriggers` così le riesecuzioni in modalità changed restano corrette quando cambia il cablaggio dei test. + - La configurazione mantiene `OPENCLAW_VITEST_FS_MODULE_CACHE` abilitato sugli host supportati; imposta `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` se desideri una posizione cache esplicita per il profiling diretto. - Nota sul debug delle prestazioni: - - `pnpm test:perf:imports` abilita il report della durata di import di Vitest più l’output di breakdown degli import. - - `pnpm test:perf:imports:changed` limita la stessa vista di profiling ai file modificati da `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` confronta `test:changed` instradato con il percorso nativo root-project per quel diff committed e stampa wall time più macOS max RSS. -- `pnpm test:perf:changed:bench -- --worktree` misura il benchmark dell’albero dirty corrente instradando l’elenco dei file modificati attraverso `scripts/test-projects.mjs` e la configurazione root Vitest. - - `pnpm test:perf:profile:main` scrive un profilo CPU del thread principale per l’overhead di avvio e transform di Vitest/Vite. - - `pnpm test:perf:profile:runner` scrive profili CPU+heap del runner per la suite unit con parallelismo dei file disabilitato. + - `pnpm test:perf:imports` abilita la reportistica sulla durata degli import di Vitest più l’output di dettaglio degli import. + - `pnpm test:perf:imports:changed` limita la stessa vista di profiling ai file modificati rispetto a `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` confronta `test:changed` instradato con il percorso nativo root-project per quel diff commitato e stampa wall time più macOS max RSS. +- `pnpm test:perf:changed:bench -- --worktree` esegue il benchmark dell’albero sporco corrente instradando l’elenco dei file modificati attraverso `scripts/test-projects.mjs` e la configurazione root Vitest. + - `pnpm test:perf:profile:main` scrive un profilo CPU del thread principale per l’overhead di avvio e trasformazione di Vitest/Vite. + - `pnpm test:perf:profile:runner` scrive profili CPU+heap del runner per la suite unit con parallelismo file disabilitato. ### E2E (smoke del gateway) - Comando: `pnpm test:e2e` - Configurazione: `vitest.e2e.config.ts` - File: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` -- Valori predefiniti di runtime: +- Valori predefiniti runtime: - Usa `threads` di Vitest con `isolate: false`, in linea con il resto del repository. - Usa worker adattivi (CI: fino a 2, locale: 1 per impostazione predefinita). - - Viene eseguita in modalità silenziosa per impostazione predefinita per ridurre l’overhead di I/O su console. + - Viene eseguito in modalità silenziosa per impostazione predefinita per ridurre l’overhead di I/O sulla console. - Override utili: - - `OPENCLAW_E2E_WORKERS=` per forzare il numero di worker (massimo 16). - - `OPENCLAW_E2E_VERBOSE=1` per riabilitare l’output verboso su console. + - `OPENCLAW_E2E_WORKERS=` per forzare il numero di worker (limitato a 16). + - `OPENCLAW_E2E_VERBOSE=1` per riattivare un output console dettagliato. - Ambito: - Comportamento end-to-end del gateway multiistanza - - Superfici WebSocket/HTTP, pairing dei Node e networking più pesante + - Superfici WebSocket/HTTP, associazione Node e networking più pesante - Aspettative: - - Viene eseguita in CI (quando abilitata nella pipeline) + - Viene eseguito in CI (quando abilitato nella pipeline) - Non richiede chiavi reali - - Ha più parti in movimento dei test unitari (può essere più lenta) + - Ha più parti in movimento rispetto ai test unitari (può essere più lento) ### E2E: smoke del backend OpenShell - Comando: `pnpm test:e2e:openshell` - File: `test/openshell-sandbox.e2e.test.ts` - Ambito: - - Avvia sull’host un gateway OpenShell isolato tramite Docker + - Avvia un gateway OpenShell isolato sull’host tramite Docker - Crea una sandbox da un Dockerfile locale temporaneo - - Esercita il backend OpenShell di OpenClaw tramite `sandbox ssh-config` + esecuzione SSH reali + - Esercita il backend OpenShell di OpenClaw tramite `sandbox ssh-config` reale + esecuzione SSH - Verifica il comportamento del filesystem canonico remoto tramite il bridge fs della sandbox - Aspettative: - Solo opt-in; non fa parte dell’esecuzione predefinita `pnpm test:e2e` - - Richiede una CLI locale `openshell` più un daemon Docker funzionante - - Usa `HOME` / `XDG_CONFIG_HOME` isolati, poi distrugge il gateway di test e la sandbox + - Richiede una CLI `openshell` locale più un demone Docker funzionante + - Usa `HOME` / `XDG_CONFIG_HOME` isolati, quindi distrugge il gateway di test e la sandbox - Override utili: - `OPENCLAW_E2E_OPENSHELL=1` per abilitare il test quando si esegue manualmente la suite e2e più ampia - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` per puntare a un binario CLI o script wrapper non predefinito + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` per puntare a un binario CLI non predefinito o a uno script wrapper ### Live (provider reali + modelli reali) - Comando: `pnpm test:live` - Configurazione: `vitest.live.config.ts` - File: `src/**/*.live.test.ts` -- Predefinita: **abilitata** da `pnpm test:live` (imposta `OPENCLAW_LIVE_TEST=1`) +- Predefinito: **abilitato** da `pnpm test:live` (imposta `OPENCLAW_LIVE_TEST=1`) - Ambito: - “Questo provider/modello funziona davvero _oggi_ con credenziali reali?” - - Cattura cambi di formato del provider, particolarità della chiamata di tool, problemi di autenticazione e comportamento dei rate limit + - Intercetta cambiamenti di formato del provider, stranezze di tool-calling, problemi di auth e comportamento dei rate limit - Aspettative: - Per progettazione non è stabile in CI (reti reali, policy reali dei provider, quote, outage) - Costa denaro / usa rate limit - - Preferisci eseguire sottoinsiemi ristretti invece di “tutto” -- Le esecuzioni live caricano `~/.profile` per recuperare eventuali API key mancanti. -- Per impostazione predefinita, le esecuzioni live isolano comunque `HOME` e copiano materiale di config/auth in una home di test temporanea così le fixture unit non possono modificare il tuo `~/.openclaw` reale. -- Imposta `OPENCLAW_LIVE_USE_REAL_HOME=1` solo quando vuoi intenzionalmente che i test live usino la tua home directory reale. -- `pnpm test:live` ora usa per impostazione predefinita una modalità più silenziosa: mantiene l’output di avanzamento `[live] ...`, ma sopprime l’avviso extra su `~/.profile` e silenzia i log di bootstrap del gateway/il chatter Bonjour. Imposta `OPENCLAW_LIVE_TEST_QUIET=0` se vuoi di nuovo i log completi di avvio. -- Rotazione delle API key (specifica per provider): imposta `*_API_KEYS` con formato separato da virgole/punto e virgola o `*_API_KEY_1`, `*_API_KEY_2` (per esempio `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) oppure override per-live tramite `OPENCLAW_LIVE_*_KEY`; i test ritentano sulle risposte di rate limit. + - È preferibile eseguire sottoinsiemi ristretti invece di “tutto” +- Le esecuzioni live leggono `~/.profile` per recuperare eventuali chiavi API mancanti. +- Per impostazione predefinita, le esecuzioni live continuano a isolare `HOME` e a copiare materiale config/auth in una home di test temporanea così i fixture unit non possono modificare il tuo `~/.openclaw` reale. +- Imposta `OPENCLAW_LIVE_USE_REAL_HOME=1` solo quando hai intenzionalmente bisogno che i test live usino la tua directory home reale. +- `pnpm test:live` ora usa per impostazione predefinita una modalità più silenziosa: mantiene l’output di avanzamento `[live] ...`, ma sopprime l’avviso extra su `~/.profile` e silenzia i log di bootstrap del gateway / il chatter Bonjour. Imposta `OPENCLAW_LIVE_TEST_QUIET=0` se vuoi ripristinare i log completi di avvio. +- Rotazione delle chiavi API (specifica per provider): imposta `*_API_KEYS` con formato separato da virgole/punto e virgola oppure `*_API_KEY_1`, `*_API_KEY_2` (ad esempio `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) o override per-live tramite `OPENCLAW_LIVE_*_KEY`; i test ritentano in caso di risposte rate limit. - Output di avanzamento/heartbeat: - - Le suite live ora emettono righe di avanzamento su stderr così le chiamate lunghe ai provider risultano visibilmente attive anche quando la cattura della console di Vitest è silenziosa. - - `vitest.live.config.ts` disabilita l’intercettazione della console da parte di Vitest così le righe di avanzamento del provider/gateway vengono trasmesse immediatamente durante le esecuzioni live. - - Regola gli heartbeat del modello diretto con `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Regola gli heartbeat del gateway/probe con `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Le suite live ora emettono righe di avanzamento su stderr così le chiamate lunghe ai provider risultano visibilmente attive anche quando la cattura console di Vitest è silenziosa. + - `vitest.live.config.ts` disabilita l’intercettazione console di Vitest così le righe di avanzamento provider/gateway vengono trasmesse immediatamente durante le esecuzioni live. + - Regola gli heartbeat direct-model con `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Regola gli heartbeat gateway/probe con `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Quale suite dovrei eseguire? Usa questa tabella decisionale: -- Modifica di logica/test: esegui `pnpm test` (e `pnpm test:coverage` se hai cambiato molto) -- Se tocchi networking del gateway / protocollo WS / pairing: aggiungi `pnpm test:e2e` -- Se fai debug di “il mio bot non funziona” / errori specifici del provider / chiamata di tool: esegui un `pnpm test:live` ristretto +- Se modifichi logica/test: esegui `pnpm test` (e `pnpm test:coverage` se hai modificato molto) +- Se tocchi networking del gateway / protocollo WS / associazione: aggiungi `pnpm test:e2e` +- Se stai facendo debug di “il mio bot non funziona” / errori specifici del provider / tool calling: esegui un `pnpm test:live` ristretto -## Live: sweep delle capability del Node Android +## Live: sweep delle capacità del Node Android - Test: `src/gateway/android-node.capabilities.live.test.ts` - Script: `pnpm android:test:integration` -- Obiettivo: invocare **ogni comando attualmente pubblicizzato** da un Node Android connesso e verificare il comportamento del contratto dei comandi. +- Obiettivo: invocare **ogni comando attualmente pubblicizzato** da un Node Android connesso e verificare il comportamento del contratto del comando. - Ambito: - - Setup manuale/con precondizioni (la suite non installa/esegue/abbina l’app). - - Validazione gateway `node.invoke` comando per comando per il Node Android selezionato. -- Pre-setup richiesto: - - App Android già connessa e abbinata al gateway. + - Setup manuale/precondizionato (la suite non installa/esegue/associa l’app). + - Validazione `node.invoke` del gateway comando per comando per il Node Android selezionato. +- Preconfigurazione richiesta: + - App Android già connessa e associata al gateway. - App mantenuta in foreground. - - Permessi/consenso alla cattura concessi per le capability che prevedi debbano riuscire. -- Override facoltativi del target: - - `OPENCLAW_ANDROID_NODE_ID` o `OPENCLAW_ANDROID_NODE_NAME`. + - Permessi/consenso alla cattura concessi per le capacità che prevedi debbano passare. +- Override target opzionali: + - `OPENCLAW_ANDROID_NODE_ID` oppure `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Dettagli completi del setup Android: [App Android](/it/platforms/android) +- Dettagli completi della configurazione Android: [Android App](/it/platforms/android) ## Live: smoke del modello (chiavi di profilo) -I test live sono divisi in due livelli così possiamo isolare i guasti: +I test live sono suddivisi in due livelli così possiamo isolare i guasti: -- “Modello diretto” ci dice se il provider/modello può rispondere del tutto con la chiave fornita. -- “Smoke del gateway” ci dice se l’intera pipeline gateway+agente funziona per quel modello (sessioni, cronologia, tool, policy sandbox, ecc.). +- “Direct model” ci dice se il provider/modello può rispondere in assoluto con la chiave data. +- “Gateway smoke” ci dice se l’intera pipeline gateway+agent funziona per quel modello (sessioni, cronologia, tool, policy sandbox, ecc.). -### Livello 1: completamento diretto del modello (senza gateway) +### Livello 1: completamento direct model (senza gateway) - Test: `src/agents/models.profiles.live.test.ts` - Obiettivo: @@ -412,27 +414,27 @@ I test live sono divisi in due livelli così possiamo isolare i guasti: - Gli sweep modern/all usano per impostazione predefinita un limite curato ad alto segnale; imposta `OPENCLAW_LIVE_MAX_MODELS=0` per uno sweep modern esaustivo oppure un numero positivo per un limite più piccolo. - Come selezionare i provider: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist separata da virgole) -- Da dove arrivano le chiavi: +- Da dove provengono le chiavi: - Per impostazione predefinita: archivio profili e fallback env - - Imposta `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre **solo** l’archivio profili + - Imposta `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre **solo l’archivio profili** - Perché esiste: - - Separa “l’API del provider è rotta / la chiave non è valida” da “la pipeline gateway agente è rotta” - - Contiene regressioni piccole e isolate (esempio: replay del reasoning OpenAI Responses/Codex Responses + flussi di tool-call) + - Separa “l’API del provider è rotta / la chiave non è valida” da “la pipeline gateway agent è rotta” + - Contiene regressioni piccole e isolate (esempio: replay del reasoning di OpenAI Responses/Codex Responses + flussi di tool-call) -### Livello 2: smoke del Gateway + agente dev (quello che fa davvero "@openclaw") +### Livello 2: smoke di Gateway + agent di sviluppo (cosa fa davvero "@openclaw") - Test: `src/gateway/gateway-models.profiles.live.test.ts` - Obiettivo: - Avviare un gateway in-process - Creare/modificare una sessione `agent:dev:*` (override del modello per esecuzione) - - Iterare sui modelli-con-chiavi e verificare: + - Iterare sui modelli con chiavi e verificare: - risposta “significativa” (senza tool) - - una vera invocazione di tool funziona (probe di read) - - probe facoltative di tool aggiuntivi (probe exec+read) - - i percorsi di regressione OpenAI (solo tool-call → follow-up) continuano a funzionare -- Dettagli delle probe (così puoi spiegare rapidamente i guasti): - - probe `read`: il test scrive un file nonce nel workspace e chiede all’agente di `read` leggerlo e riecheggiare il nonce. - - probe `exec+read`: il test chiede all’agente di scrivere tramite `exec` un nonce in un file temporaneo, quindi di `read` leggerlo di nuovo. + - che una vera invocazione di tool funzioni (probe di lettura) + - probe tool extra opzionali (probe exec+read) + - che i percorsi di regressione OpenAI (solo tool-call → follow-up) continuino a funzionare +- Dettagli delle probe (così puoi spiegare rapidamente i fallimenti): + - probe `read`: il test scrive un file nonce nel workspace e chiede all’agent di `read` leggerlo e restituire il nonce. + - probe `exec+read`: il test chiede all’agent di scrivere tramite `exec` un nonce in un file temporaneo, quindi di `read` leggerlo di nuovo. - probe immagine: il test allega un PNG generato (gatto + codice casuale) e si aspetta che il modello restituisca `cat `. - Riferimento implementativo: `src/gateway/gateway-models.profiles.live.test.ts` e `src/gateway/live-image-probe.ts`. - Come abilitarlo: @@ -440,19 +442,19 @@ I test live sono divisi in due livelli così possiamo isolare i guasti: - Come selezionare i modelli: - Predefinito: allowlist modern (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_GATEWAY_MODELS=all` è un alias per l’allowlist modern - - Oppure imposta `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (o una lista separata da virgole) per restringere + - Oppure imposta `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (o elenco separato da virgole) per restringere - Gli sweep gateway modern/all usano per impostazione predefinita un limite curato ad alto segnale; imposta `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` per uno sweep modern esaustivo oppure un numero positivo per un limite più piccolo. - Come selezionare i provider (evita “tutto OpenRouter”): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist separata da virgole) -- Le probe di tool + immagine sono sempre attive in questo test live: +- Le probe tool + immagine sono sempre attive in questo test live: - probe `read` + probe `exec+read` (stress dei tool) - la probe immagine viene eseguita quando il modello dichiara supporto per input immagine - Flusso (alto livello): - Il test genera un piccolo PNG con “CAT” + codice casuale (`src/gateway/live-image-probe.ts`) - Lo invia tramite `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - - Il gateway analizza gli allegati in `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - L’agente embedded inoltra al modello un messaggio utente multimodale - - Verifica: la risposta contiene `cat` + il codice (tolleranza OCR: sono ammessi piccoli errori) + - Gateway analizza gli allegati in `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - L’agent incorporato inoltra al modello un messaggio utente multimodale + - Verifica: la risposta contiene `cat` + il codice (tolleranza OCR: piccoli errori consentiti) Suggerimento: per vedere cosa puoi testare sulla tua macchina (e gli id esatti `provider/model`), esegui: @@ -464,22 +466,22 @@ openclaw models list --json ## Live: smoke del backend CLI (Claude, Codex, Gemini o altre CLI locali) - Test: `src/gateway/gateway-cli-backend.live.test.ts` -- Obiettivo: validare la pipeline Gateway + agente usando un backend CLI locale, senza toccare la tua configurazione predefinita. +- Obiettivo: convalidare la pipeline Gateway + agent usando un backend CLI locale, senza toccare la configurazione predefinita. - I valori predefiniti smoke specifici del backend si trovano nella definizione `cli-backend.ts` dell’extension proprietaria. -- Abilita: +- Abilitazione: - `pnpm test:live` (oppure `OPENCLAW_LIVE_TEST=1` se invochi Vitest direttamente) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Valori predefiniti: - Provider/modello predefinito: `claude-cli/claude-sonnet-4-6` - - Il comportamento di comando/argomenti/immagine proviene dai metadati del plugin del backend CLI proprietario. -- Override (facoltativi): + - Il comportamento di command/args/image proviene dai metadati del plugin backend CLI proprietario. +- Override (opzionali): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` per inviare un allegato immagine reale (i percorsi vengono iniettati nel prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` per passare i percorsi dei file immagine come argomenti CLI invece di iniettarli nel prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (oppure `"list"`) per controllare come vengono passati gli argomenti immagine quando è impostato `IMAGE_ARG`. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` per inviare un secondo turno e validare il flusso di ripresa. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` per inviare un vero allegato immagine (i percorsi vengono iniettati nel prompt). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` per passare i percorsi dei file immagine come argomenti CLI invece che tramite iniezione nel prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (oppure `"list"`) per controllare come vengono passati gli argomenti immagine quando `IMAGE_ARG` è impostato. + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` per inviare un secondo turno e convalidare il flusso di ripresa. - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` per disabilitare la probe predefinita di continuità nella stessa sessione Claude Sonnet -> Opus (imposta `1` per forzarla quando il modello selezionato supporta un target di switch). Esempio: @@ -508,27 +510,27 @@ pnpm test:docker:live-cli-backend:gemini Note: - Il runner Docker si trova in `scripts/test-live-cli-backend-docker.sh`. -- Esegue lo smoke live del backend CLI dentro l’immagine Docker del repository come utente non root `node`. -- Risolve i metadati dello smoke CLI dall’extension proprietaria, quindi installa il pacchetto CLI Linux corrispondente (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) in un prefisso scrivibile in cache in `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (predefinito: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` richiede OAuth portabile dell’abbonamento Claude Code tramite `~/.claude/.credentials.json` con `claudeAiOauth.subscriptionType` oppure `CLAUDE_CODE_OAUTH_TOKEN` da `claude setup-token`. Prima dimostra `claude -p` diretto in Docker, poi esegue due turni del backend CLI del Gateway senza preservare le variabili env della API key Anthropic. Questa corsia subscription disabilita per impostazione predefinita le probe Claude MCP/tool e immagine perché Claude al momento instrada l’uso di app di terze parti tramite fatturazione extra-usage invece che tramite i normali limiti del piano di abbonamento. -- Lo smoke live del backend CLI ora esercita lo stesso flusso end-to-end per Claude, Codex e Gemini: turno di testo, turno di classificazione immagine, poi chiamata al tool MCP `cron` verificata tramite la CLI del gateway. +- Esegue lo smoke live del backend CLI dentro l’immagine Docker del repository come utente `node` non root. +- Risolve i metadati smoke CLI dall’extension proprietaria, quindi installa il pacchetto CLI Linux corrispondente (`@anthropic-ai/claude-code`, `@openai/codex` oppure `@google/gemini-cli`) in un prefisso scrivibile in cache in `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (predefinito: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` richiede OAuth portabile della sottoscrizione Claude Code tramite `~/.claude/.credentials.json` con `claudeAiOauth.subscriptionType` oppure `CLAUDE_CODE_OAUTH_TOKEN` da `claude setup-token`. Prima dimostra `claude -p` diretto in Docker, poi esegue due turni Gateway CLI-backend senza preservare le variabili env della chiave API Anthropic. Questo lane di sottoscrizione disabilita per impostazione predefinita le probe Claude MCP/tool e immagine perché Claude al momento instrada l’uso di app di terze parti tramite fatturazione di utilizzo extra invece che tramite i normali limiti del piano di sottoscrizione. +- Lo smoke live del backend CLI ora esercita lo stesso flusso end-to-end per Claude, Codex e Gemini: turno testuale, turno di classificazione immagine, quindi chiamata al tool MCP `cron` verificata tramite la CLI del gateway. - Lo smoke predefinito di Claude modifica inoltre la sessione da Sonnet a Opus e verifica che la sessione ripresa ricordi ancora una nota precedente. -## Live: smoke ACP bind (`/acp spawn ... --bind here`) +## Live: smoke del bind ACP (`/acp spawn ... --bind here`) - Test: `src/gateway/gateway-acp-bind.live.test.ts` -- Obiettivo: validare il vero flusso ACP di bind della conversazione con un agente ACP live: +- Obiettivo: convalidare il vero flusso di conversation-bind ACP con un agent ACP live: - inviare `/acp spawn --bind here` - - associare sul posto una conversazione sintetica di message-channel - - inviare un normale follow-up su quella stessa conversazione + - associare in-place una conversazione sintetica del canale messaggi + - inviare un normale follow-up sulla stessa conversazione - verificare che il follow-up finisca nel transcript della sessione ACP associata -- Abilita: +- Abilitazione: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - Valori predefiniti: - - Agenti ACP in Docker: `claude,codex,gemini` - - Agente ACP per `pnpm test:live ...` diretto: `claude` - - Canale sintetico: contesto di conversazione in stile DM Slack + - Agent ACP in Docker: `claude,codex,gemini` + - Agent ACP per `pnpm test:live ...` diretto: `claude` + - Canale sintetico: contesto conversazione in stile DM Slack - Backend ACP: `acpx` - Override: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` @@ -537,8 +539,8 @@ Note: - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Note: - - Questa corsia usa la superficie gateway `chat.send` con campi synthetic originating-route riservati agli admin, così i test possono allegare contesto di message-channel senza fingere una consegna esterna. - - Quando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` non è impostato, il test usa il registro agent integrato del plugin `acpx` embedded per l’agente harness ACP selezionato. + - Questo lane usa la superficie gateway `chat.send` con campi synthetic originating-route riservati agli admin così i test possono allegare il contesto del canale messaggi senza fingere una consegna esterna. + - Quando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` non è impostato, il test usa il registro agent integrato del plugin `acpx` incorporato per l’agent harness ACP selezionato. Esempio: @@ -554,7 +556,7 @@ Ricetta Docker: pnpm test:docker:live-acp-bind ``` -Ricette Docker per singolo agente: +Ricette Docker per singolo agent: ```bash pnpm test:docker:live-acp-bind:claude @@ -566,30 +568,30 @@ Note Docker: - Il runner Docker si trova in `scripts/test-live-acp-bind-docker.sh`. - Per impostazione predefinita, esegue in sequenza lo smoke ACP bind contro tutti gli agent CLI live supportati: `claude`, `codex`, poi `gemini`. -- Usa `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` o `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` per restringere la matrice. -- Carica `~/.profile`, prepara nel container il materiale di autenticazione CLI corrispondente, installa `acpx` in un prefisso npm scrivibile, poi installa la CLI live richiesta (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) se manca. -- Dentro Docker, il runner imposta `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` così acpx mantiene disponibili alla CLI harness figlia le variabili env del provider dal profilo caricato. +- Usa `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` oppure `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` per restringere la matrice. +- Legge `~/.profile`, prepara nel container il materiale di autenticazione CLI corrispondente, installa `acpx` in un prefisso npm scrivibile, quindi installa la CLI live richiesta (`@anthropic-ai/claude-code`, `@openai/codex` oppure `@google/gemini-cli`) se mancante. +- Dentro Docker, il runner imposta `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` così acpx mantiene disponibili alla CLI harness figlia le variabili env del provider provenienti dal profilo caricato. ## Live: smoke dell’harness app-server Codex -- Obiettivo: validare l’harness Codex di proprietà del plugin tramite il normale metodo gateway - `agent`: +- Obiettivo: convalidare l’harness Codex del plugin proprietario tramite il normale + metodo gateway `agent`: - caricare il plugin `codex` incluso - selezionare `OPENCLAW_AGENT_RUNTIME=codex` - - inviare un primo turno agente del gateway a `codex/gpt-5.4` + - inviare un primo turno gateway agent a `codex/gpt-5.4` - inviare un secondo turno alla stessa sessione OpenClaw e verificare che il thread - dell’app-server possa riprendere - - eseguire `/codex status` e `/codex models` tramite lo stesso percorso - del comando gateway + app-server possa riprendere + - eseguire `/codex status` e `/codex models` tramite lo stesso percorso di comando + del gateway - Test: `src/gateway/gateway-codex-harness.live.test.ts` -- Abilita: `OPENCLAW_LIVE_CODEX_HARNESS=1` +- Abilitazione: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Modello predefinito: `codex/gpt-5.4` -- Probe immagine facoltativa: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- Probe MCP/tool facoltativa: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- Lo smoke imposta `OPENCLAW_AGENT_HARNESS_FALLBACK=none` così un harness Codex - rotto non può passare ripiegando silenziosamente su Pi. -- Auth: `OPENAI_API_KEY` dalla shell/profilo, più eventuali copie facoltative di - `~/.codex/auth.json` e `~/.codex/config.toml` +- Probe immagine opzionale: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- Probe MCP/tool opzionale: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- Lo smoke imposta `OPENCLAW_AGENT_HARNESS_FALLBACK=none` così un harness Codex rotto + non può passare ricadendo silenziosamente su PI. +- Auth: `OPENAI_API_KEY` dalla shell/profilo, più eventuali + `~/.codex/auth.json` e `~/.codex/config.toml` copiati Ricetta locale: @@ -612,19 +614,19 @@ pnpm test:docker:live-codex-harness Note Docker: - Il runner Docker si trova in `scripts/test-live-codex-harness-docker.sh`. -- Carica il `~/.profile` montato, passa `OPENAI_API_KEY`, copia i file di auth della CLI Codex - quando presenti, installa `@openai/codex` in un prefisso npm montato e scrivibile, - prepara l’albero sorgente, quindi esegue solo il test live dell’harness Codex. +- Legge il `~/.profile` montato, passa `OPENAI_API_KEY`, copia i file di auth + della CLI Codex quando presenti, installa `@openai/codex` in un prefisso npm + montato e scrivibile, prepara l’albero dei sorgenti, quindi esegue solo il test live dell’harness Codex. - Docker abilita per impostazione predefinita le probe immagine e MCP/tool. Imposta `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` oppure - `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` quando hai bisogno di un’esecuzione di debug più ristretta. -- Docker esporta anche `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, in linea con la configurazione del test - live così il fallback `openai-codex/*` o Pi non può nascondere una regressione + `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` quando ti serve un’esecuzione di debug più ristretta. +- Docker esporta anche `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, in linea con la configurazione del + test live così il fallback `openai-codex/*` o PI non può nascondere una regressione dell’harness Codex. ### Ricette live consigliate -Allowlist ristrette ed esplicite sono le più rapide e le meno soggette a flakiness: +Allowlist ristrette ed esplicite sono le più veloci e meno instabili: - Modello singolo, diretto (senza gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` @@ -632,31 +634,31 @@ Allowlist ristrette ed esplicite sono le più rapide e le meno soggette a flakin - Modello singolo, smoke del gateway: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Tool calling su più provider: +- Tool calling su diversi provider: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Focus Google (API key Gemini + Antigravity): - - Gemini (API key): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` +- Focus Google (chiave API Gemini + Antigravity): + - Gemini (chiave API): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` Note: -- `google/...` usa l’API Gemini (API key). -- `google-antigravity/...` usa il bridge OAuth Antigravity (endpoint agente in stile Cloud Code Assist). -- `google-gemini-cli/...` usa la CLI Gemini locale sulla tua macchina (autenticazione separata + particolarità dei tool). +- `google/...` usa l’API Gemini (chiave API). +- `google-antigravity/...` usa il bridge OAuth Antigravity (endpoint agent in stile Cloud Code Assist). +- `google-gemini-cli/...` usa la CLI Gemini locale sulla tua macchina (auth separata + particolarità degli strumenti). - API Gemini vs CLI Gemini: - - API: OpenClaw chiama via HTTP l’API Gemini ospitata da Google (API key / auth di profilo); è ciò che la maggior parte degli utenti intende con “Gemini”. - - CLI: OpenClaw invoca una binaria `gemini` locale; ha una propria autenticazione e può comportarsi diversamente (streaming/supporto tool/version skew). + - API: OpenClaw chiama l’API Gemini ospitata da Google via HTTP (auth con chiave API / profilo); è ciò che la maggior parte degli utenti intende con “Gemini”. + - CLI: OpenClaw esegue una shell verso un binario `gemini` locale; ha una propria auth e può comportarsi in modo diverso (streaming/supporto tool/disallineamento di versione). ## Live: matrice dei modelli (cosa copriamo) -Non esiste un “elenco modelli CI” fisso (live è opt-in), ma questi sono i modelli **consigliati** da coprire regolarmente su una macchina di sviluppo con chiavi. +Non esiste un “elenco fisso di modelli CI” (live è opt-in), ma questi sono i modelli **consigliati** da coprire regolarmente su una macchina di sviluppo con chiavi. -### Set smoke modern (tool calling + immagine) +### Insieme smoke modern (tool calling + immagine) Questa è l’esecuzione dei “modelli comuni” che ci aspettiamo continui a funzionare: -- OpenAI (non-Codex): `openai/gpt-5.4` (facoltativo: `openai/gpt-5.4-mini`) +- OpenAI (non-Codex): `openai/gpt-5.4` (opzionale: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` - Anthropic: `anthropic/claude-opus-4-6` (oppure `anthropic/claude-sonnet-4-6`) - Google (API Gemini): `google/gemini-3.1-pro-preview` e `google/gemini-3-flash-preview` (evita i vecchi modelli Gemini 2.x) @@ -667,9 +669,9 @@ Questa è l’esecuzione dei “modelli comuni” che ci aspettiamo continui a f Esegui lo smoke del gateway con tool + immagine: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Baseline: tool calling (Read + Exec facoltativo) +### Baseline: tool calling (Read + Exec opzionale) -Scegli almeno uno per ogni famiglia di provider: +Scegline almeno uno per famiglia di provider: - OpenAI: `openai/gpt-5.4` (oppure `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (oppure `anthropic/claude-sonnet-4-6`) @@ -677,7 +679,7 @@ Scegli almeno uno per ogni famiglia di provider: - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Copertura aggiuntiva facoltativa (utile da avere): +Copertura aggiuntiva opzionale (utile da avere): - xAI: `xai/grok-4` (oppure l’ultima disponibile) - Mistral: `mistral/`… (scegli un modello con capacità “tools” che hai abilitato) @@ -686,55 +688,55 @@ Copertura aggiuntiva facoltativa (utile da avere): ### Vision: invio immagine (allegato → messaggio multimodale) -Includi almeno un modello con capacità immagine in `OPENCLAW_LIVE_GATEWAY_MODELS` (varianti Claude/Gemini/OpenAI con supporto vision, ecc.) per esercitare la probe immagine. +Includi almeno un modello con capacità immagine in `OPENCLAW_LIVE_GATEWAY_MODELS` (varianti Claude/Gemini/OpenAI con capacità vision, ecc.) per esercitare la probe immagine. ### Aggregatori / gateway alternativi -Se hai chiavi abilitate, supportiamo anche i test tramite: +Se hai chiavi abilitate, supportiamo anche test tramite: -- OpenRouter: `openrouter/...` (centinaia di modelli; usa `openclaw models scan` per trovare candidati con capacità tool+immagine) +- OpenRouter: `openrouter/...` (centinaia di modelli; usa `openclaw models scan` per trovare candidati con capacità tool+image) - OpenCode: `opencode/...` per Zen e `opencode-go/...` per Go (auth tramite `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Altri provider che puoi includere nella matrice live (se hai credenziali/config): +Altri provider che puoi includere nella matrice live (se hai credenziali/configurazione): - Integrati: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Tramite `models.providers` (endpoint personalizzati): `minimax` (cloud/API), più qualsiasi proxy compatibile con OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, ecc.) +- Tramite `models.providers` (endpoint personalizzati): `minimax` (cloud/API), più qualsiasi proxy compatibile OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, ecc.) -Suggerimento: non cercare di hardcodare “tutti i modelli” nella documentazione. L’elenco autorevole è qualunque cosa `discoverModels(...)` restituisca sulla tua macchina + qualunque chiave sia disponibile. +Suggerimento: non cercare di codificare in modo rigido “tutti i modelli” nella documentazione. L’elenco autorevole è tutto ciò che `discoverModels(...)` restituisce sulla tua macchina + tutte le chiavi disponibili. ## Credenziali (non fare mai commit) -I test live individuano le credenziali nello stesso modo in cui lo fa la CLI. Implicazioni pratiche: +I test live rilevano le credenziali nello stesso modo della CLI. Implicazioni pratiche: - Se la CLI funziona, i test live dovrebbero trovare le stesse chiavi. -- Se un test live dice “nessuna credenziale”, fai debug nello stesso modo in cui faresti debug di `openclaw models list` / della selezione del modello. +- Se un test live dice “nessuna credenziale”, esegui il debug come faresti con `openclaw models list` / selezione del modello. -- Profili auth per agente: `~/.openclaw/agents//agent/auth-profiles.json` (questo è il significato di “chiavi di profilo” nei test live) +- Profili auth per agent: `~/.openclaw/agents//agent/auth-profiles.json` (questo è il significato di “profile keys” nei test live) - Configurazione: `~/.openclaw/openclaw.json` (oppure `OPENCLAW_CONFIG_PATH`) -- Directory di stato legacy: `~/.openclaw/credentials/` (copiata nella home live preparata quando presente, ma non è l’archivio principale delle chiavi di profilo) -- Le esecuzioni live locali copiano per impostazione predefinita la configurazione attiva, i file `auth-profiles.json` per agente, `credentials/` legacy e le directory auth CLI esterne supportate in una home di test temporanea; le home live preparate saltano `workspace/` e `sandboxes/`, e gli override di percorso `agents.*.workspace` / `agentDir` vengono rimossi così le probe restano fuori dal tuo workspace host reale. +- Directory di stato legacy: `~/.openclaw/credentials/` (copiata nella home live preparata quando presente, ma non è l’archivio principale delle chiavi profilo) +- Le esecuzioni live locali copiano per impostazione predefinita la configurazione attiva, i file `auth-profiles.json` per agent, la directory legacy `credentials/` e le directory di auth CLI esterne supportate in una home di test temporanea; le home live preparate saltano `workspace/` e `sandboxes/`, e gli override di percorso `agents.*.workspace` / `agentDir` vengono rimossi così le probe restano fuori dal tuo workspace host reale. -Se vuoi fare affidamento su chiavi env (per esempio esportate nel tuo `~/.profile`), esegui i test locali dopo `source ~/.profile`, oppure usa i runner Docker sotto (possono montare `~/.profile` nel container). +Se vuoi fare affidamento sulle chiavi env (ad esempio esportate nel tuo `~/.profile`), esegui i test locali dopo `source ~/.profile`, oppure usa i runner Docker indicati sotto (possono montare `~/.profile` nel container). ## Live Deepgram (trascrizione audio) - Test: `src/media-understanding/providers/deepgram/audio.live.test.ts` -- Abilita: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` +- Abilitazione: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` ## Live BytePlus coding plan - Test: `src/agents/byteplus.live.test.ts` -- Abilita: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` -- Override facoltativo del modello: `BYTEPLUS_CODING_MODEL=ark-code-latest` +- Abilitazione: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` +- Override modello opzionale: `BYTEPLUS_CODING_MODEL=ark-code-latest` ## Live media workflow ComfyUI - Test: `extensions/comfy/comfy.live.test.ts` -- Abilita: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` +- Abilitazione: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Ambito: - - Esercita i percorsi bundled Comfy per immagini, video e `music_generate` - - Salta ogni capability a meno che `models.providers.comfy.` non sia configurato - - Utile dopo modifiche a invio workflow Comfy, polling, download o registrazione del plugin + - Esercita i percorsi inclusi di immagine, video e `music_generate` di comfy + - Salta ogni capacità a meno che `models.providers.comfy.` non sia configurato + - Utile dopo modifiche all’invio dei workflow comfy, al polling, ai download o alla registrazione del plugin ## Live generazione immagini @@ -744,237 +746,237 @@ Se vuoi fare affidamento su chiavi env (per esempio esportate nel tuo `~/.profil - Ambito: - Enumera ogni plugin provider di generazione immagini registrato - Carica le variabili env dei provider mancanti dalla tua shell di login (`~/.profile`) prima dell’esecuzione delle probe - - Usa per impostazione predefinita le API key live/env prima dei profili auth salvati, così chiavi di test obsolete in `auth-profiles.json` non mascherano le vere credenziali della shell - - Salta i provider senza auth/profilo/modello utilizzabili - - Esegue le varianti standard di generazione immagini tramite la capability runtime condivisa: + - Usa per impostazione predefinita le chiavi API live/env prima dei profili auth memorizzati, così chiavi di test obsolete in `auth-profiles.json` non mascherano le vere credenziali della shell + - Salta i provider senza auth/profilo/modello utilizzabile + - Esegue le varianti standard di generazione immagini tramite la capacità runtime condivisa: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Provider bundled attualmente coperti: +- Provider inclusi attualmente coperti: - `openai` - `google` -- Restrizione facoltativa: +- Restrizione opzionale: - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` -- Comportamento auth facoltativo: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per forzare l’auth tramite archivio profili e ignorare gli override solo env +- Comportamento auth opzionale: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre l’auth del profile store e ignorare gli override solo env ## Live generazione musicale - Test: `extensions/music-generation-providers.live.test.ts` -- Abilita: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` +- Abilitazione: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Ambito: - - Esercita il percorso bundled condiviso del provider di generazione musicale + - Esercita il percorso condiviso incluso del provider di generazione musicale - Attualmente copre Google e MiniMax - Carica le variabili env dei provider dalla tua shell di login (`~/.profile`) prima dell’esecuzione delle probe - - Usa per impostazione predefinita le API key live/env prima dei profili auth salvati, così chiavi di test obsolete in `auth-profiles.json` non mascherano le vere credenziali della shell - - Salta i provider senza auth/profilo/modello utilizzabili + - Usa per impostazione predefinita le chiavi API live/env prima dei profili auth memorizzati, così chiavi di test obsolete in `auth-profiles.json` non mascherano le vere credenziali della shell + - Salta i provider senza auth/profilo/modello utilizzabile - Esegue entrambe le modalità runtime dichiarate quando disponibili: - `generate` con input solo prompt - `edit` quando il provider dichiara `capabilities.edit.enabled` - - Copertura attuale della corsia condivisa: + - Copertura attuale del lane condiviso: - `google`: `generate`, `edit` - `minimax`: `generate` - `comfy`: file live Comfy separato, non questo sweep condiviso -- Restrizione facoltativa: +- Restrizione opzionale: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` -- Comportamento auth facoltativo: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per forzare l’auth tramite archivio profili e ignorare gli override solo env +- Comportamento auth opzionale: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre l’auth del profile store e ignorare gli override solo env ## Live generazione video - Test: `extensions/video-generation-providers.live.test.ts` -- Abilita: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` +- Abilitazione: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Ambito: - - Esercita il percorso bundled condiviso del provider di generazione video - - Per impostazione predefinita usa il percorso smoke sicuro per release: provider non-FAL, una richiesta text-to-video per provider, prompt lobster di un secondo e un limite di operazione per provider da `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` per impostazione predefinita) - - Salta FAL per impostazione predefinita perché la latenza della coda lato provider può dominare il tempo di release; passa `--video-providers fal` oppure `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` per eseguirlo esplicitamente + - Esercita il percorso condiviso incluso del provider di generazione video + - Usa per impostazione predefinita il percorso smoke sicuro per il rilascio: provider non-FAL, una richiesta text-to-video per provider, prompt lobster di un secondo e un limite per operazione per provider da `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` per impostazione predefinita) + - Salta FAL per impostazione predefinita perché la latenza della coda lato provider può dominare il tempo di rilascio; passa `--video-providers fal` oppure `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` per eseguirlo esplicitamente - Carica le variabili env dei provider dalla tua shell di login (`~/.profile`) prima dell’esecuzione delle probe - - Usa per impostazione predefinita le API key live/env prima dei profili auth salvati, così chiavi di test obsolete in `auth-profiles.json` non mascherano le vere credenziali della shell - - Salta i provider senza auth/profilo/modello utilizzabili + - Usa per impostazione predefinita le chiavi API live/env prima dei profili auth memorizzati, così chiavi di test obsolete in `auth-profiles.json` non mascherano le vere credenziali della shell + - Salta i provider senza auth/profilo/modello utilizzabile - Esegue solo `generate` per impostazione predefinita - - Imposta `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` per eseguire anche le modalità di trasformazione dichiarate quando disponibili: - - `imageToVideo` quando il provider dichiara `capabilities.imageToVideo.enabled` e il provider/modello selezionato accetta input immagine locale basato su buffer nello sweep condiviso - - `videoToVideo` quando il provider dichiara `capabilities.videoToVideo.enabled` e il provider/modello selezionato accetta input video locale basato su buffer nello sweep condiviso + - Imposta `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` per eseguire anche le modalità transform dichiarate quando disponibili: + - `imageToVideo` quando il provider dichiara `capabilities.imageToVideo.enabled` e il provider/modello selezionato accetta input immagine locale con buffer-backed nello sweep condiviso + - `videoToVideo` quando il provider dichiara `capabilities.videoToVideo.enabled` e il provider/modello selezionato accetta input video locale con buffer-backed nello sweep condiviso - Provider `imageToVideo` attualmente dichiarati ma saltati nello sweep condiviso: - - `vydra` perché il `veo3` bundled è solo testo e il `kling` bundled richiede un URL immagine remoto - - Copertura specifica per provider Vydra: + - `vydra` perché il `veo3` incluso è solo testo e il `kling` incluso richiede un URL immagine remoto + - Copertura Vydra specifica del provider: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - quel file esegue `veo3` text-to-video più una corsia `kling` che usa per impostazione predefinita una fixture con URL immagine remoto + - quel file esegue `veo3` text-to-video più un lane `kling` che usa per impostazione predefinita un fixture con URL immagine remoto - Copertura live `videoToVideo` attuale: - solo `runway` quando il modello selezionato è `runway/gen4_aleph` - Provider `videoToVideo` attualmente dichiarati ma saltati nello sweep condiviso: - `alibaba`, `qwen`, `xai` perché quei percorsi richiedono attualmente URL di riferimento remoti `http(s)` / MP4 - - `google` perché l’attuale corsia condivisa Gemini/Veo usa input locale basato su buffer e quel percorso non è accettato nello sweep condiviso - - `openai` perché l’attuale corsia condivisa non garantisce accesso specifico dell’organizzazione a inpaint/remix video -- Restrizione facoltativa: + - `google` perché l’attuale lane Gemini/Veo condiviso usa input locale con buffer-backed e quel percorso non è accettato nello sweep condiviso + - `openai` perché l’attuale lane condiviso non garantisce accesso specifico dell’organizzazione a video inpaint/remix +- Restrizione opzionale: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` per includere ogni provider nello sweep predefinito, incluso FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` per ridurre il limite di operazione di ogni provider in uno smoke aggressivo -- Comportamento auth facoltativo: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per forzare l’auth tramite archivio profili e ignorare gli override solo env + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` per ridurre il limite di operazione di ciascun provider per un’esecuzione smoke aggressiva +- Comportamento auth opzionale: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre l’auth del profile store e ignorare gli override solo env ## Harness live media - Comando: `pnpm test:live:media` - Scopo: - - Esegue le suite live condivise di immagini, musica e video tramite un unico entrypoint nativo del repository + - Esegue le suite live condivise di immagine, musica e video tramite un unico entrypoint nativo del repository - Carica automaticamente le variabili env dei provider mancanti da `~/.profile` - - Per impostazione predefinita restringe automaticamente ogni suite ai provider che al momento hanno auth utilizzabile - - Riutilizza `scripts/test-live.mjs`, così il comportamento di heartbeat e quiet mode resta coerente + - Restringe automaticamente per impostazione predefinita ogni suite ai provider che attualmente hanno auth utilizzabile + - Riutilizza `scripts/test-live.mjs`, così il comportamento heartbeat e quiet-mode resta coerente - Esempi: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Runner Docker (controlli facoltativi “funziona su Linux”) +## Runner Docker (controlli opzionali “funziona su Linux”) Questi runner Docker si dividono in due gruppi: -- Runner live-model: `test:docker:live-models` e `test:docker:live-gateway` eseguono solo il file live a chiavi di profilo corrispondente dentro l’immagine Docker del repository (`src/agents/models.profiles.live.test.ts` e `src/gateway/gateway-models.profiles.live.test.ts`), montando la tua directory di configurazione locale e il workspace (e caricando `~/.profile` se montato). Gli entrypoint locali corrispondenti sono `test:live:models-profiles` e `test:live:gateway-profiles`. -- I runner Docker live usano per impostazione predefinita un limite smoke più piccolo così uno sweep Docker completo resta pratico: +- Runner live-model: `test:docker:live-models` e `test:docker:live-gateway` eseguono solo il rispettivo file live con chiavi profilo all’interno dell’immagine Docker del repository (`src/agents/models.profiles.live.test.ts` e `src/gateway/gateway-models.profiles.live.test.ts`), montando la tua directory di configurazione locale e il workspace (e leggendo `~/.profile` se montato). Gli entrypoint locali corrispondenti sono `test:live:models-profiles` e `test:live:gateway-profiles`. +- I runner live Docker usano per impostazione predefinita un limite smoke più piccolo così uno sweep Docker completo resta pratico: `test:docker:live-models` usa per impostazione predefinita `OPENCLAW_LIVE_MAX_MODELS=12`, e `test:docker:live-gateway` usa per impostazione predefinita `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` e `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Sostituisci quelle variabili env quando - vuoi esplicitamente la scansione esaustiva più ampia. -- `test:docker:all` costruisce una volta l’immagine Docker live tramite `test:docker:live-build`, poi la riutilizza per le due corsie Docker live. -- Runner smoke container: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` e `test:docker:plugins` avviano uno o più container reali e verificano percorsi di integrazione di livello più alto. + desideri esplicitamente la scansione esaustiva più ampia. +- `test:docker:all` costruisce una volta l’immagine Docker live tramite `test:docker:live-build`, poi la riutilizza per i due lane live Docker. +- Runner smoke del container: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` e `test:docker:plugins` avviano uno o più container reali e verificano percorsi di integrazione di livello superiore. -I runner Docker live-model montano inoltre solo le home di auth CLI necessarie (o tutte quelle supportate quando l’esecuzione non è ristretta), poi le copiano nella home del container prima dell’esecuzione così l’OAuth di CLI esterne può aggiornare i token senza modificare l’archivio auth dell’host: +I runner Docker live-model montano inoltre solo le home di auth CLI necessarie (oppure tutte quelle supportate quando l’esecuzione non è ristretta), quindi le copiano nella home del container prima dell’esecuzione così l’OAuth della CLI esterna può aggiornare i token senza modificare l’archivio auth dell’host: - Modelli diretti: `pnpm test:docker:live-models` (script: `scripts/test-live-models-docker.sh`) - Smoke ACP bind: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`) - Smoke backend CLI: `pnpm test:docker:live-cli-backend` (script: `scripts/test-live-cli-backend-docker.sh`) - Smoke harness app-server Codex: `pnpm test:docker:live-codex-harness` (script: `scripts/test-live-codex-harness-docker.sh`) -- Gateway + agente dev: `pnpm test:docker:live-gateway` (script: `scripts/test-live-gateway-models-docker.sh`) +- Gateway + agent di sviluppo: `pnpm test:docker:live-gateway` (script: `scripts/test-live-gateway-models-docker.sh`) - Smoke live Open WebUI: `pnpm test:docker:openwebui` (script: `scripts/e2e/openwebui-docker.sh`) - Wizard di onboarding (TTY, scaffolding completo): `pnpm test:docker:onboard` (script: `scripts/e2e/onboard-docker.sh`) - Networking del gateway (due container, auth WS + health): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) -- Bridge canale MCP (Gateway seeded + bridge stdio + smoke raw Claude notification-frame): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) -- Plugin (smoke di installazione + alias `/plugin` + semantica di riavvio Claude-bundle): `pnpm test:docker:plugins` (script: `scripts/e2e/plugins-docker.sh`) +- Bridge canale MCP (Gateway inizializzato + bridge stdio + smoke raw Claude notification-frame): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) +- Plugin (smoke di installazione + alias `/plugin` + semantica di riavvio del bundle Claude): `pnpm test:docker:plugins` (script: `scripts/e2e/plugins-docker.sh`) -I runner Docker live-model montano inoltre il checkout corrente in sola lettura e +I runner Docker live-model montano anche il checkout corrente in sola lettura e lo preparano in una workdir temporanea dentro il container. Questo mantiene -snella l’immagine runtime pur eseguendo comunque Vitest rispetto al tuo esatto sorgente/config locale. -Il passaggio di staging salta grandi cache solo locali e output di build delle app come -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` e directory di output `.build` o -Gradle locali all’app, così le esecuzioni live Docker non passano minuti a copiare +snella l’immagine runtime pur eseguendo Vitest contro il tuo sorgente/configurazione locali esatti. +Il passaggio di staging salta grandi cache solo locali e output di build dell’app come +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` e directory di output `.build` locali dell’app o +Gradle, così le esecuzioni live Docker non passano minuti a copiare artifact specifici della macchina. -Impostano anche `OPENCLAW_SKIP_CHANNELS=1` così le probe live del gateway non avviano -worker reali di canali Telegram/Discord/ecc. dentro il container. -`test:docker:live-models` esegue comunque `pnpm test:live`, quindi fai passare anche -`OPENCLAW_LIVE_GATEWAY_*` quando devi restringere o escludere la copertura live del gateway -da quella corsia Docker. +Impostano inoltre `OPENCLAW_SKIP_CHANNELS=1` così le probe live del gateway non avviano +worker di canale reali Telegram/Discord/ecc. dentro il container. +`test:docker:live-models` esegue comunque `pnpm test:live`, quindi inoltra anche +`OPENCLAW_LIVE_GATEWAY_*` quando devi restringere o escludere la copertura +live del gateway da quel lane Docker. `test:docker:openwebui` è uno smoke di compatibilità di livello superiore: avvia un container gateway OpenClaw con gli endpoint HTTP compatibili con OpenAI abilitati, -avvia un container Open WebUI fissato contro quel gateway, effettua l’accesso tramite +avvia un container Open WebUI fissato contro quel gateway, effettua il sign-in tramite Open WebUI, verifica che `/api/models` esponga `openclaw/default`, quindi invia una -vera richiesta di chat tramite il proxy `/api/chat/completions` di Open WebUI. +vera richiesta chat tramite il proxy `/api/chat/completions` di Open WebUI. La prima esecuzione può essere sensibilmente più lenta perché Docker potrebbe dover scaricare -l’immagine Open WebUI e Open WebUI potrebbe dover completare il proprio setup a freddo. -Questa corsia si aspetta una chiave modello live utilizzabile, e `OPENCLAW_PROFILE_FILE` -(`~/.profile` per impostazione predefinita) è il modo principale per fornirla nelle esecuzioni Docker. +l’immagine Open WebUI e Open WebUI potrebbe dover completare il proprio avvio a freddo. +Questo lane si aspetta una chiave di modello live utilizzabile, e `OPENCLAW_PROFILE_FILE` +(`~/.profile` per impostazione predefinita) è il modo principale per fornirla nelle esecuzioni Dockerizzate. Le esecuzioni riuscite stampano un piccolo payload JSON come `{ "ok": true, "model": "openclaw/default", ... }`. -`test:docker:mcp-channels` è intenzionalmente deterministico e non necessita di un -account reale Telegram, Discord o iMessage. Avvia un container Gateway seeded, +`test:docker:mcp-channels` è intenzionalmente deterministico e non ha bisogno di un +account reale Telegram, Discord o iMessage. Avvia un container Gateway inizializzato, avvia un secondo container che esegue `openclaw mcp serve`, quindi -verifica discovery della conversazione instradata, letture del transcript, metadati degli allegati, -comportamento della coda di eventi live, instradamento dell’invio in uscita e notifiche in stile Claude di canale + -permesso sul vero bridge stdio MCP. Il controllo delle notifiche -ispeziona direttamente i frame MCP stdio raw così lo smoke valida ciò che il -bridge emette davvero, non solo ciò che un particolare SDK client capita di esporre. +verifica il rilevamento delle conversazioni instradate, la lettura dei transcript, i metadati +degli allegati, il comportamento della coda di eventi live, l’instradamento dell’invio in uscita +e le notifiche in stile Claude su canale + permessi tramite il vero bridge stdio MCP. Il controllo delle notifiche +ispeziona direttamente i frame raw stdio MCP così lo smoke convalida ciò che il +bridge emette davvero, non solo ciò che una specifica SDK client capita a esporre. -Smoke manuale ACP plain-language thread (non CI): +Smoke manuale plain-language del thread ACP (non CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Mantieni questo script per i flussi di lavoro di regressione/debug. Potrebbe servire di nuovo per la validazione dell’instradamento thread ACP, quindi non eliminarlo. +- Mantieni questo script per flussi di lavoro di regressione/debug. Potrebbe servire di nuovo per la validazione dell’instradamento dei thread ACP, quindi non eliminarlo. Variabili env utili: -- `OPENCLAW_CONFIG_DIR=...` (predefinito: `~/.openclaw`) montata su `/home/node/.openclaw` -- `OPENCLAW_WORKSPACE_DIR=...` (predefinito: `~/.openclaw/workspace`) montata su `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (predefinito: `~/.profile`) montata su `/home/node/.profile` e caricata prima dell’esecuzione dei test -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` per verificare solo le variabili env caricate da `OPENCLAW_PROFILE_FILE`, usando directory config/workspace temporanee e senza mount auth CLI esterni -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (predefinito: `~/.cache/openclaw/docker-cli-tools`) montata su `/home/node/.npm-global` per installazioni CLI in cache dentro Docker -- Le directory/file auth di CLI esterne sotto `$HOME` vengono montati in sola lettura sotto `/host-auth...`, poi copiati in `/home/node/...` prima dell’avvio dei test +- `OPENCLAW_CONFIG_DIR=...` (predefinito: `~/.openclaw`) montata in `/home/node/.openclaw` +- `OPENCLAW_WORKSPACE_DIR=...` (predefinito: `~/.openclaw/workspace`) montata in `/home/node/.openclaw/workspace` +- `OPENCLAW_PROFILE_FILE=...` (predefinito: `~/.profile`) montata in `/home/node/.profile` e caricata prima di eseguire i test +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` per verificare solo le variabili env caricate da `OPENCLAW_PROFILE_FILE`, usando directory config/workspace temporanee e nessun mount auth CLI esterno +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (predefinito: `~/.cache/openclaw/docker-cli-tools`) montata in `/home/node/.npm-global` per installazioni CLI in cache dentro Docker +- Directory/file di auth CLI esterni sotto `$HOME` vengono montati in sola lettura sotto `/host-auth...`, poi copiati in `/home/node/...` prima dell’avvio dei test - Directory predefinite: `.minimax` - File predefiniti: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Le esecuzioni ristrette per provider montano solo le directory/file necessari dedotti da `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Override manuale con `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` oppure una lista separata da virgole come `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - Le esecuzioni con provider ristretti montano solo directory/file necessari dedotti da `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Sostituisci manualmente con `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` o un elenco separato da virgole come `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` per restringere l’esecuzione -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` per filtrare i provider dentro il container -- `OPENCLAW_SKIP_DOCKER_BUILD=1` per riutilizzare un’immagine `openclaw:local-live` esistente per riesecuzioni che non richiedono una nuova build -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per assicurarsi che le credenziali provengano dall’archivio profili (non dall’env) +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` per filtrare i provider nel container +- `OPENCLAW_SKIP_DOCKER_BUILD=1` per riutilizzare un’immagine `openclaw:local-live` esistente per riesecuzioni che non richiedono una ricostruzione +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per assicurare che le credenziali provengano dal profile store (non da env) - `OPENCLAW_OPENWEBUI_MODEL=...` per scegliere il modello esposto dal gateway per lo smoke Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...` per sostituire il prompt di verifica nonce usato dallo smoke Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...` per sostituire il prompt di controllo nonce usato dallo smoke Open WebUI - `OPENWEBUI_IMAGE=...` per sostituire il tag immagine Open WebUI fissato -## Verifica della documentazione +## Integrità della documentazione Esegui i controlli docs dopo modifiche alla documentazione: `pnpm check:docs`. -Esegui la validazione completa degli anchor Mintlify quando ti servono anche controlli degli heading nella pagina: `pnpm docs:check-links:anchors`. +Esegui la validazione completa degli anchor Mintlify quando ti servono anche controlli sulle intestazioni nella pagina: `pnpm docs:check-links:anchors`. ## Regressione offline (sicura per CI) -Queste sono regressioni di “pipeline reale” senza provider reali: +Si tratta di regressioni della “pipeline reale” senza provider reali: -- Tool calling del gateway (mock OpenAI, gateway reale + loop agente): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Wizard del gateway (WS `wizard.start`/`wizard.next`, scrive config + auth applicata): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") +- Tool calling del gateway (mock OpenAI, vero gateway + loop agent): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Wizard del gateway (WS `wizard.start`/`wizard.next`, scrittura di config + auth imposta): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") -## Valutazioni di affidabilità dell’agente (Skills) +## Valutazioni di affidabilità degli agent (Skills) -Abbiamo già alcuni test sicuri per CI che si comportano come “valutazioni di affidabilità dell’agente”: +Abbiamo già alcuni test sicuri per CI che si comportano come “valutazioni di affidabilità degli agent”: -- Mock tool-calling attraverso il vero gateway + loop agente (`src/gateway/gateway.test.ts`). -- Flussi wizard end-to-end che validano il wiring della sessione e gli effetti di configurazione (`src/gateway/gateway.test.ts`). +- Mock tool-calling tramite il vero gateway + loop agent (`src/gateway/gateway.test.ts`). +- Flussi wizard end-to-end che convalidano il cablaggio della sessione e gli effetti della configurazione (`src/gateway/gateway.test.ts`). Cosa manca ancora per Skills (vedi [Skills](/it/tools/skills)): -- **Decisioning:** quando gli Skills sono elencati nel prompt, l’agente sceglie lo Skill giusto (o evita quelli irrilevanti)? -- **Compliance:** l’agente legge `SKILL.md` prima dell’uso e segue i passaggi/argomenti richiesti? -- **Workflow contracts:** scenari multi-turno che verificano ordine dei tool, persistenza della cronologia di sessione e boundary della sandbox. +- **Decisioning:** quando Skills sono elencate nel prompt, l’agent sceglie la Skill giusta (o evita quelle irrilevanti)? +- **Compliance:** l’agent legge `SKILL.md` prima dell’uso e segue i passaggi/gli argomenti richiesti? +- **Workflow contracts:** scenari multi-turno che verificano l’ordine degli strumenti, il riporto della cronologia della sessione e i confini della sandbox. Le valutazioni future dovrebbero restare prima di tutto deterministiche: -- Un runner di scenari che usa provider mock per verificare chiamate ai tool + ordine, letture dei file skill e wiring della sessione. -- Una piccola suite di scenari focalizzati sugli skill (usa vs evita, gating, prompt injection). -- Valutazioni live facoltative (opt-in, controllate da env) solo dopo che la suite sicura per CI è stata messa in piedi. +- Un runner di scenari che usa provider mock per verificare chiamate agli strumenti + ordine, letture dei file Skill e cablaggio della sessione. +- Una piccola suite di scenari focalizzati sulle Skill (usare vs evitare, gating, prompt injection). +- Valutazioni live opzionali (opt-in, controllate da env) solo dopo che la suite sicura per CI è pronta. -## Test di contratto (forma di plugin e channel) +## Test di contratto (forma di plugin e canale) -I test di contratto verificano che ogni plugin e channel registrato sia conforme al -proprio contratto di interfaccia. Iterano su tutti i plugin rilevati ed eseguono una suite di -verifiche di forma e comportamento. La corsia unit predefinita `pnpm test` -salta intenzionalmente questi file smoke e di interfaccia condivisa; esegui esplicitamente i comandi dei contratti -quando tocchi superfici condivise di channel o provider. +I test di contratto verificano che ogni plugin e canale registrato sia conforme al proprio +contratto di interfaccia. Iterano su tutti i plugin rilevati ed eseguono una suite di +verifiche di forma e comportamento. Il lane unit predefinito `pnpm test` +salta intenzionalmente questi file smoke e seam condivisi; esegui i comandi di contratto esplicitamente +quando tocchi superfici condivise di canali o provider. ### Comandi - Tutti i contratti: `pnpm test:contracts` -- Solo contratti dei channel: `pnpm test:contracts:channels` +- Solo contratti dei canali: `pnpm test:contracts:channels` - Solo contratti dei provider: `pnpm test:contracts:plugins` -### Contratti dei channel +### Contratti dei canali Si trovano in `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Forma base del plugin (id, nome, capability) -- **setup** - Contratto della procedura guidata di setup -- **session-binding** - Comportamento del binding di sessione +- **plugin** - Forma base del plugin (id, nome, capacità) +- **setup** - Contratto del wizard di configurazione +- **session-binding** - Comportamento del binding della sessione - **outbound-payload** - Struttura del payload del messaggio - **inbound** - Gestione dei messaggi in ingresso -- **actions** - Handler delle azioni del channel -- **threading** - Gestione dell’id del thread +- **actions** - Handler delle azioni del canale +- **threading** - Gestione dell’ID del thread - **directory** - API directory/roster - **group-policy** - Applicazione delle policy di gruppo @@ -982,7 +984,7 @@ Si trovano in `src/channels/plugins/contracts/*.contract.test.ts`: Si trovano in `src/plugins/contracts/*.contract.test.ts`. -- **status** - Probe di stato del channel +- **status** - Probe di stato del canale - **registry** - Forma del registro dei plugin ### Contratti dei provider @@ -991,30 +993,30 @@ Si trovano in `src/plugins/contracts/*.contract.test.ts`: - **auth** - Contratto del flusso di auth - **auth-choice** - Scelta/selezione dell’auth -- **catalog** - API del catalogo modelli -- **discovery** - Discovery del plugin -- **loader** - Caricamento del plugin +- **catalog** - API del catalogo dei modelli +- **discovery** - Rilevamento dei plugin +- **loader** - Caricamento dei plugin - **runtime** - Runtime del provider - **shape** - Forma/interfaccia del plugin -- **wizard** - Procedura guidata di setup +- **wizard** - Wizard di configurazione ### Quando eseguirli -- Dopo aver modificato export o subpath di plugin-sdk -- Dopo aver aggiunto o modificato un plugin channel o provider -- Dopo aver rifattorizzato la registrazione o la discovery dei plugin +- Dopo aver modificato export o sottopercorsi del plugin-sdk +- Dopo aver aggiunto o modificato un plugin canale o provider +- Dopo aver rifattorizzato la registrazione o il rilevamento dei plugin -I test di contratto vengono eseguiti in CI e non richiedono API key reali. +I test di contratto vengono eseguiti in CI e non richiedono chiavi API reali. -## Aggiunta di regressioni (linee guida) +## Aggiungere regressioni (linee guida) -Quando correggi un problema di provider/modello scoperto in live: +Quando correggi un problema provider/modello scoperto in live: - Aggiungi una regressione sicura per CI se possibile (provider mock/stub, oppure cattura l’esatta trasformazione della forma della richiesta) - Se è intrinsecamente solo live (rate limit, policy di auth), mantieni il test live ristretto e opt-in tramite variabili env -- Preferisci puntare al layer più piccolo che intercetta il bug: - - bug di conversione/replay della richiesta del provider → test diretto dei modelli - - bug della pipeline gateway sessione/cronologia/tool → smoke live del gateway o test mock del gateway sicuro per CI -- Guardrail di attraversamento SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` ricava un target di esempio per classe SecretRef dai metadati del registro (`listSecretTargetRegistryEntries()`), quindi verifica che gli id exec dei segmenti di attraversamento vengano rifiutati. +- Preferisci prendere di mira il livello più piccolo che intercetta il bug: + - bug di conversione/replay della richiesta del provider → test direct models + - bug della pipeline gateway session/history/tool → smoke live del gateway o test mock del gateway sicuro per CI +- Guardrail sull’attraversamento SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva un target campione per classe SecretRef dai metadati del registro (`listSecretTargetRegistryEntries()`), quindi verifica che gli id exec dei segmenti di attraversamento vengano rifiutati. - Se aggiungi una nuova famiglia di target SecretRef `includeInPlan` in `src/secrets/target-registry-data.ts`, aggiorna `classifyTargetClass` in quel test. Il test fallisce intenzionalmente sugli id target non classificati così le nuove classi non possono essere saltate in silenzio. diff --git a/docs/it/help/troubleshooting.md b/docs/it/help/troubleshooting.md index ba0f5d066..0ce1ad8f7 100644 --- a/docs/it/help/troubleshooting.md +++ b/docs/it/help/troubleshooting.md @@ -1,14 +1,14 @@ --- read_when: - OpenClaw non funziona e hai bisogno del percorso più rapido per una soluzione - - Vuoi un flusso di triage prima di approfondire con runbook dettagliati -summary: Hub di risoluzione dei problemi di OpenClaw orientato ai sintomi + - Vuoi un flusso di triage prima di entrare nei runbook di approfondimento +summary: Hub di risoluzione dei problemi orientato ai sintomi per OpenClaw title: Risoluzione generale dei problemi x-i18n: - generated_at: "2026-04-11T02:45:17Z" + generated_at: "2026-04-20T08:31:32Z" model: gpt-5.4 provider: openai - source_hash: 16b38920dbfdc8d4a79bbb5d6fab2c67c9f218a97c36bb4695310d7db9c4614a + source_hash: cc5d8c9f804084985c672c5a003ce866e8142ab99fe81abb7a0d38e22aea4b88 source_path: help/troubleshooting.md workflow: 15 --- @@ -19,7 +19,7 @@ Se hai solo 2 minuti, usa questa pagina come punto di ingresso per il triage. ## Primi 60 secondi -Esegui esattamente questa sequenza nell'ordine indicato: +Esegui questa sequenza esatta nell'ordine indicato: ```bash openclaw status @@ -35,10 +35,12 @@ Output corretto in una riga: - `openclaw status` → mostra i canali configurati e nessun errore auth evidente. - `openclaw status --all` → il report completo è presente e condivisibile. -- `openclaw gateway probe` → la destinazione gateway prevista è raggiungibile (`Reachable: yes`). `RPC: limited - missing scope: operator.read` indica diagnostica degradata, non un errore di connessione. -- `openclaw gateway status` → `Runtime: running` e `RPC probe: ok`. +- `openclaw gateway probe` → il target Gateway previsto è raggiungibile (`Reachable: yes`). `Capability: ...` indica quale livello di auth il probe ha potuto dimostrare, e `Read probe: limited - missing scope: operator.read` indica una diagnostica degradata, non un errore di connessione. +- `openclaw gateway status` → `Runtime: running`, `Connectivity probe: ok` e una riga `Capability: ...` plausibile. Usa `--require-rpc` se ti serve anche la prova RPC con ambito di lettura. - `openclaw doctor` → nessun errore bloccante di configurazione/servizio. -- `openclaw channels status --probe` → se il gateway è raggiungibile, restituisce lo stato di trasporto live per account più i risultati di probe/audit come `works` o `audit ok`; se il gateway non è raggiungibile, il comando torna a riepiloghi basati solo sulla configurazione. +- `openclaw channels status --probe` → con un gateway raggiungibile restituisce + stato live del trasporto per account più risultati di probe/audit come `works` o `audit ok`; se il + gateway non è raggiungibile, il comando ripiega su riepiloghi basati solo sulla configurazione. - `openclaw logs --follow` → attività costante, nessun errore fatale ripetuto. ## Anthropic long context 429 @@ -49,29 +51,29 @@ vai a [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-cont ## Il backend locale compatibile con OpenAI funziona direttamente ma fallisce in OpenClaw -Se il tuo backend locale o self-hosted `/v1` risponde a piccole probe dirette +Se il tuo backend locale o self-hosted `/v1` risponde a piccoli probe diretti `/v1/chat/completions` ma fallisce su `openclaw infer model run` o nei normali -turni dell'agente: +turni agente: 1. Se l'errore menziona `messages[].content` che si aspetta una stringa, imposta `models.providers..models[].compat.requiresStringContent: true`. 2. Se il backend continua a fallire solo nei turni agente di OpenClaw, imposta `models.providers..models[].compat.supportsTools: false` e riprova. 3. Se le chiamate dirette minime continuano a funzionare ma i prompt OpenClaw più grandi mandano in crash il - backend, tratta il problema residuo come una limitazione upstream del modello/server e - continua nel runbook approfondito: + backend, tratta il problema rimanente come una limitazione del modello/server upstream e + continua nel runbook di approfondimento: [/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail](/it/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail) -## L'installazione del plugin fallisce con openclaw extensions mancanti +## L'installazione del Plugin fallisce con estensioni openclaw mancanti -Se l'installazione fallisce con `package.json missing openclaw.extensions`, il pacchetto plugin +Se l'installazione fallisce con `package.json missing openclaw.extensions`, il pacchetto Plugin usa una struttura vecchia che OpenClaw non accetta più. -Correzione nel pacchetto plugin: +Correzione nel pacchetto Plugin: 1. Aggiungi `openclaw.extensions` a `package.json`. -2. Punta le entry ai file runtime compilati (di solito `./dist/index.js`). -3. Ripubblica il plugin ed esegui di nuovo `openclaw plugins install `. +2. Punta gli entry ai file runtime compilati (di solito `./dist/index.js`). +3. Ripubblica il Plugin ed esegui di nuovo `openclaw plugins install `. Esempio: @@ -85,7 +87,7 @@ Esempio: } ``` -Riferimento: [Architettura dei plugin](/it/plugins/architecture) +Riferimento: [Architettura dei Plugin](/it/plugins/architecture) ## Albero decisionale @@ -93,19 +95,19 @@ Riferimento: [Architettura dei plugin](/it/plugins/architecture) flowchart TD A[OpenClaw non funziona] --> B{Cosa si rompe per primo} B --> C[Nessuna risposta] - B --> D[Dashboard o Control UI non si connette] + B --> D[Dashboard o Control UI non si connettono] B --> E[Il Gateway non si avvia o il servizio non è in esecuzione] - B --> F[Il canale si connette ma i messaggi non passano] - B --> G[Cron o heartbeat non si è attivato o non ha consegnato] - B --> H[Il nodo è associato ma il comando exec per camera canvas screen fallisce] + B --> F[Il canale si connette ma i messaggi non scorrono] + B --> G[Cron o Heartbeat non è stato eseguito o non ha consegnato] + B --> H[Il Node è associato ma lo strumento camera canvas screen exec fallisce] B --> I[Lo strumento browser fallisce] C --> C1[/Sezione Nessuna risposta/] D --> D1[/Sezione Control UI/] E --> E1[/Sezione Gateway/] - F --> F1[/Sezione Flusso del canale/] + F --> F1[/Sezione Flusso canale/] G --> G1[/Sezione Automazione/] - H --> H1[/Sezione Strumenti nodo/] + H --> H1[/Sezione Strumenti Node/] I --> I1[/Sezione Browser/] ``` @@ -119,20 +121,21 @@ flowchart TD openclaw logs --follow ``` - Un output corretto appare così: + Un output corretto si presenta così: - `Runtime: running` - - `RPC probe: ok` + - `Connectivity probe: ok` + - `Capability: read-only`, `write-capable` o `admin-capable` - Il tuo canale mostra il trasporto connesso e, dove supportato, `works` o `audit ok` in `channels status --probe` - - Il mittente risulta approvato (oppure la policy DM è aperta/in allowlist) + - Il mittente risulta approvato (oppure la policy DM è open/allowlist) - Firme di log comuni: + Firme comuni nei log: - - `drop guild message (mention required` → il gating per mention ha bloccato il messaggio in Discord. - - `pairing request` → il mittente non è approvato ed è in attesa di approvazione dell'associazione DM. + - `drop guild message (mention required` → il gating per menzione ha bloccato il messaggio in Discord. + - `pairing request` → il mittente non è approvato ed è in attesa di approvazione per l'associazione DM. - `blocked` / `allowlist` nei log del canale → mittente, stanza o gruppo è filtrato. - Pagine approfondite: + Pagine di approfondimento: - [/gateway/troubleshooting#no-replies](/it/gateway/troubleshooting#no-replies) - [/channels/troubleshooting](/it/channels/troubleshooting) @@ -140,7 +143,7 @@ flowchart TD - + ```bash openclaw status openclaw gateway status @@ -149,28 +152,29 @@ flowchart TD openclaw channels status --probe ``` - Un output corretto appare così: + Un output corretto si presenta così: - `Dashboard: http://...` è mostrato in `openclaw gateway status` - - `RPC probe: ok` + - `Connectivity probe: ok` + - `Capability: read-only`, `write-capable` o `admin-capable` - Nessun loop auth nei log - Firme di log comuni: + Firme comuni nei log: - - `device identity required` → il contesto HTTP/non sicuro non può completare l'auth del dispositivo. - - `origin not allowed` → l'`Origin` del browser non è consentito per la destinazione gateway della Control UI. - - `AUTH_TOKEN_MISMATCH` con suggerimenti di tentativo (`canRetryWithDeviceToken=true`) → può verificarsi automaticamente un tentativo con device token fidato. - - Quel tentativo con token in cache riutilizza l'insieme di scope in cache memorizzato con il paired - device token. I chiamanti con `deviceToken` esplicito / `scopes` espliciti mantengono - invece l'insieme di scope richiesto. + - `device identity required` → HTTP/contesto non sicuro non può completare l'auth del dispositivo. + - `origin not allowed` → l'`Origin` del browser non è consentito per il target Gateway della Control UI + - `AUTH_TOKEN_MISMATCH` con suggerimenti di retry (`canRetryWithDeviceToken=true`) → un retry automatico con device token fidato può avvenire una volta. + - Quel retry con token in cache riusa l'insieme di scope in cache memorizzato con il + device token associato. I chiamanti con `deviceToken` esplicito / `scopes` espliciti mantengono invece il loro insieme di scope richiesto. - Nel percorso asincrono Tailscale Serve Control UI, i tentativi falliti per lo stesso `{scope, ip}` vengono serializzati prima che il limiter registri l'errore, quindi un - secondo tentativo errato concorrente può già mostrare `retry later`. - - `too many failed authentication attempts (retry later)` da un'origine browser localhost → i fallimenti ripetuti dalla stessa `Origin` vengono temporaneamente bloccati; un'altra origine localhost usa un bucket separato. - - `repeated unauthorized` dopo quel tentativo → token/password errati, mancata corrispondenza della modalità auth o paired device token obsoleto. - - `gateway connect failed:` → la UI sta puntando all'URL/porta sbagliata o a un gateway non raggiungibile. + secondo retry errato concorrente può già mostrare `retry later`. + - `too many failed authentication attempts (retry later)` da un'origine browser localhost → gli errori ripetuti dalla stessa `Origin` vengono temporaneamente + bloccati; un'altra origine localhost usa un bucket separato. + - `repeated unauthorized` dopo quel retry → token/password errati, modalità auth non corrispondente o device token associato non aggiornato. + - `gateway connect failed:` → la UI punta a URL/porta sbagliati o a un gateway irraggiungibile. - Pagine approfondite: + Pagine di approfondimento: - [/gateway/troubleshooting#dashboard-control-ui-connectivity](/it/gateway/troubleshooting#dashboard-control-ui-connectivity) - [/web/control-ui](/web/control-ui) @@ -187,19 +191,20 @@ flowchart TD openclaw channels status --probe ``` - Un output corretto appare così: + Un output corretto si presenta così: - `Service: ... (loaded)` - `Runtime: running` - - `RPC probe: ok` + - `Connectivity probe: ok` + - `Capability: read-only`, `write-capable` o `admin-capable` - Firme di log comuni: + Firme comuni nei log: - - `Gateway start blocked: set gateway.mode=local` o `existing config is missing gateway.mode` → la modalità gateway è remote, oppure nel file di configurazione manca il contrassegno local-mode e deve essere riparato. + - `Gateway start blocked: set gateway.mode=local` o `existing config is missing gateway.mode` → la modalità gateway è remote, oppure nel file di configurazione manca il marker local-mode e deve essere riparato. - `refusing to bind gateway ... without auth` → bind non-loopback senza un percorso auth gateway valido (token/password, oppure trusted-proxy dove configurato). - `another gateway instance is already listening` o `EADDRINUSE` → porta già occupata. - Pagine approfondite: + Pagine di approfondimento: - [/gateway/troubleshooting#gateway-service-not-running](/it/gateway/troubleshooting#gateway-service-not-running) - [/gateway/background-process](/it/gateway/background-process) @@ -207,7 +212,7 @@ flowchart TD - + ```bash openclaw status openclaw gateway status @@ -216,26 +221,26 @@ flowchart TD openclaw channels status --probe ``` - Un output corretto appare così: + Un output corretto si presenta così: - Il trasporto del canale è connesso. - I controlli pairing/allowlist passano. - - Le mention vengono rilevate dove richiesto. + - Le menzioni vengono rilevate dove richiesto. - Firme di log comuni: + Firme comuni nei log: - - `mention required` → il gating per mention nel gruppo ha bloccato l'elaborazione. + - `mention required` → il gating della menzione nel gruppo ha bloccato l'elaborazione. - `pairing` / `pending` → il mittente DM non è ancora approvato. - `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → problema di token o permessi del canale. - Pagine approfondite: + Pagine di approfondimento: - [/gateway/troubleshooting#channel-connected-messages-not-flowing](/it/gateway/troubleshooting#channel-connected-messages-not-flowing) - [/channels/troubleshooting](/it/channels/troubleshooting) - + ```bash openclaw status openclaw gateway status @@ -245,23 +250,23 @@ flowchart TD openclaw logs --follow ``` - Un output corretto appare così: + Un output corretto si presenta così: - - `cron.status` mostra che è abilitato con una prossima riattivazione. - - `cron runs` mostra voci `ok` recenti. + - `cron.status` mostra abilitato con un prossimo risveglio. + - `cron runs` mostra recenti voci `ok`. - Heartbeat è abilitato e non è fuori dalle ore attive. - Firme di log comuni: + Firme comuni nei log: - - `cron: scheduler disabled; jobs will not run automatically` → cron è disabilitato. + - `cron: scheduler disabled; jobs will not run automatically` → Cron è disabilitato. - `heartbeat skipped` con `reason=quiet-hours` → fuori dalle ore attive configurate. - `heartbeat skipped` con `reason=empty-heartbeat-file` → `HEARTBEAT.md` esiste ma contiene solo struttura vuota o solo intestazioni. - - `heartbeat skipped` con `reason=no-tasks-due` → la modalità attività di `HEARTBEAT.md` è attiva ma nessuno degli intervalli delle attività è ancora scaduto. - - `heartbeat skipped` con `reason=alerts-disabled` → tutta la visibilità heartbeat è disabilitata (`showOk`, `showAlerts` e `useIndicator` sono tutti disattivati). - - `requests-in-flight` → corsia principale occupata; la riattivazione heartbeat è stata rinviata. - - `unknown accountId` → l'account di destinazione della consegna heartbeat non esiste. + - `heartbeat skipped` con `reason=no-tasks-due` → la modalità attività di `HEARTBEAT.md` è attiva ma nessun intervallo delle attività è ancora scaduto. + - `heartbeat skipped` con `reason=alerts-disabled` → tutta la visibilità Heartbeat è disabilitata (`showOk`, `showAlerts` e `useIndicator` sono tutti disattivati). + - `requests-in-flight` → corsia principale occupata; il risveglio Heartbeat è stato rinviato. + - `unknown accountId` → il target di consegna Heartbeat non esiste. - Pagine approfondite: + Pagine di approfondimento: - [/gateway/troubleshooting#cron-and-heartbeat-delivery](/it/gateway/troubleshooting#cron-and-heartbeat-delivery) - [/automation/cron-jobs#troubleshooting](/it/automation/cron-jobs#troubleshooting) @@ -269,7 +274,7 @@ flowchart TD - + ```bash openclaw status openclaw gateway status @@ -278,20 +283,20 @@ flowchart TD openclaw logs --follow ``` - Un output corretto appare così: + Un output corretto si presenta così: - - Il nodo è elencato come connesso e associato per il ruolo `node`. + - Il Node è elencato come connesso e associato per il ruolo `node`. - La capability esiste per il comando che stai invocando. - - Lo stato del permesso è concesso per lo strumento. + - Lo stato dei permessi è concesso per lo strumento. - Firme di log comuni: + Firme comuni nei log: - - `NODE_BACKGROUND_UNAVAILABLE` → porta l'app del nodo in primo piano. + - `NODE_BACKGROUND_UNAVAILABLE` → porta l'app Node in primo piano. - `*_PERMISSION_REQUIRED` → il permesso del sistema operativo è stato negato o manca. - - `SYSTEM_RUN_DENIED: approval required` → l'approvazione exec è in sospeso. + - `SYSTEM_RUN_DENIED: approval required` → l'approvazione exec è in attesa. - `SYSTEM_RUN_DENIED: allowlist miss` → il comando non è nella allowlist exec. - Pagine approfondite: + Pagine di approfondimento: - [/gateway/troubleshooting#node-paired-tool-fails](/it/gateway/troubleshooting#node-paired-tool-fails) - [/nodes/troubleshooting](/it/nodes/troubleshooting) @@ -299,7 +304,7 @@ flowchart TD - + ```bash openclaw config get tools.exec.host openclaw config get tools.exec.security @@ -312,9 +317,9 @@ flowchart TD - Se `tools.exec.host` non è impostato, il valore predefinito è `auto`. - `host=auto` viene risolto in `sandbox` quando è attivo un runtime sandbox, altrimenti in `gateway`. - `host=auto` riguarda solo il routing; il comportamento "YOLO" senza prompt deriva da `security=full` più `ask=off` su gateway/node. - - Su `gateway` e `node`, `tools.exec.security` non impostato usa come predefinito `full`. - - `tools.exec.ask` non impostato usa come predefinito `off`. - - Risultato: se stai vedendo richieste di approvazione, qualche policy locale dell'host o per sessione ha reso exec più restrittivo rispetto ai valori predefiniti attuali. + - Su `gateway` e `node`, `tools.exec.security` non impostato ha come predefinito `full`. + - `tools.exec.ask` non impostato ha come predefinito `off`. + - Risultato: se stai vedendo richieste di approvazione, qualche policy locale dell'host o per sessione ha irrigidito exec rispetto ai valori predefiniti attuali. Ripristina l'attuale comportamento predefinito senza approvazione: @@ -327,17 +332,17 @@ flowchart TD Alternative più sicure: - - Imposta solo `tools.exec.host=gateway` se vuoi semplicemente un instradamento host stabile. - - Usa `security=allowlist` con `ask=on-miss` se vuoi exec sull'host ma desideri comunque una revisione in caso di mancata corrispondenza con la allowlist. - - Abilita la modalità sandbox se vuoi che `host=auto` torni a risolversi in `sandbox`. + - Imposta solo `tools.exec.host=gateway` se vuoi soltanto un routing host stabile. + - Usa `security=allowlist` con `ask=on-miss` se vuoi exec sull'host ma desideri comunque una revisione per le mancate corrispondenze nella allowlist. + - Abilita la modalità sandbox se vuoi che `host=auto` venga risolto di nuovo in `sandbox`. - Firme di log comuni: + Firme comuni nei log: - - `Approval required.` → il comando è in attesa su `/approve ...`. - - `SYSTEM_RUN_DENIED: approval required` → l'approvazione exec dell'host del nodo è in sospeso. - - `exec host=sandbox requires a sandbox runtime for this session` → selezione sandbox implicita/esplicita ma la modalità sandbox è disattivata. + - `Approval required.` → il comando è in attesa di `/approve ...`. + - `SYSTEM_RUN_DENIED: approval required` → l'approvazione exec su host-node è in attesa. + - `exec host=sandbox requires a sandbox runtime for this session` → selezione sandbox implicita/esplicita ma modalità sandbox disattivata. - Pagine approfondite: + Pagine di approfondimento: - [/tools/exec](/it/tools/exec) - [/tools/exec-approvals](/it/tools/exec-approvals) @@ -354,24 +359,24 @@ flowchart TD openclaw doctor ``` - Un output corretto appare così: + Un output corretto si presenta così: - Lo stato del browser mostra `running: true` e un browser/profilo selezionato. - `openclaw` si avvia, oppure `user` può vedere le schede Chrome locali. - Firme di log comuni: + Firme comuni nei log: - `unknown command "browser"` o `unknown command 'browser'` → `plugins.allow` è impostato e non include `browser`. - `Failed to start Chrome CDP on port` → l'avvio del browser locale non è riuscito. - `browser.executablePath not found` → il percorso del binario configurato è errato. - `browser.cdpUrl must be http(s) or ws(s)` → l'URL CDP configurato usa uno schema non supportato. - `browser.cdpUrl has invalid port` → l'URL CDP configurato ha una porta non valida o fuori intervallo. - - `No Chrome tabs found for profile="user"` → il profilo di collegamento Chrome MCP non ha schede Chrome locali aperte. + - `No Chrome tabs found for profile="user"` → il profilo attach di Chrome MCP non ha schede Chrome locali aperte. - `Remote CDP for profile "" is not reachable` → l'endpoint CDP remoto configurato non è raggiungibile da questo host. - - `Browser attachOnly is enabled ... not reachable` o `Browser attachOnly is enabled and CDP websocket ... is not reachable` → il profilo solo collegamento non ha una destinazione CDP live. - - override obsoleti di viewport / dark mode / locale / offline su profili solo collegamento o CDP remoti → esegui `openclaw browser stop --browser-profile ` per chiudere la sessione di controllo attiva e rilasciare lo stato di emulazione senza riavviare il gateway. + - `Browser attachOnly is enabled ... not reachable` o `Browser attachOnly is enabled and CDP websocket ... is not reachable` → il profilo solo-attach non ha alcun target CDP live. + - override obsoleti di viewport / dark-mode / locale / offline su profili solo-attach o CDP remoto → esegui `openclaw browser stop --browser-profile ` per chiudere la sessione di controllo attiva e rilasciare lo stato di emulazione senza riavviare il gateway. - Pagine approfondite: + Pagine di approfondimento: - [/gateway/troubleshooting#browser-tool-fails](/it/gateway/troubleshooting#browser-tool-fails) - [/tools/browser#missing-browser-command-or-tool](/it/tools/browser#missing-browser-command-or-tool) @@ -385,7 +390,7 @@ flowchart TD ## Correlati - [FAQ](/it/help/faq) — domande frequenti -- [Risoluzione dei problemi del Gateway](/it/gateway/troubleshooting) — problemi specifici del gateway -- [Doctor](/it/gateway/doctor) — controlli di integrità automatizzati e riparazioni +- [Risoluzione dei problemi del Gateway](/it/gateway/troubleshooting) — problemi specifici del Gateway +- [Doctor](/it/gateway/doctor) — controlli di salute automatizzati e riparazioni - [Risoluzione dei problemi dei canali](/it/channels/troubleshooting) — problemi di connettività dei canali -- [Risoluzione dei problemi di automazione](/it/automation/cron-jobs#troubleshooting) — problemi di cron e heartbeat +- [Risoluzione dei problemi dell'automazione](/it/automation/cron-jobs#troubleshooting) — problemi di Cron e Heartbeat diff --git a/docs/it/tools/browser.md b/docs/it/tools/browser.md index ee645a3ce..86b73ff47 100644 --- a/docs/it/tools/browser.md +++ b/docs/it/tools/browser.md @@ -1,40 +1,40 @@ --- read_when: - - Aggiunta dell'automazione del browser controllata dall'agente - - Debug di come openclaw stia interferendo con il tuo Chrome - - Implementazione delle impostazioni del browser + del ciclo di vita nell'app macOS -summary: Servizio di controllo del browser integrato + comandi di azione + - Aggiunta di automazione del browser controllata dall'agente + - Debug di perché openclaw sta interferendo con il tuo Chrome + - Implementazione delle impostazioni del browser e del ciclo di vita nell'app macOS +summary: Servizio di controllo browser integrato + comandi di azione title: Browser (gestito da OpenClaw) x-i18n: - generated_at: "2026-04-14T13:04:29Z" + generated_at: "2026-04-20T08:31:51Z" model: gpt-5.4 provider: openai - source_hash: ae9ef725f544d4236d229f498c7187871c69bd18d31069b30a7e67fac53166a2 + source_hash: 3f7d37b34ba48dc7c38f8c2e77f8bb97af987eac6a874ebfc921f950fb59de4b source_path: tools/browser.md workflow: 15 --- # Browser (gestito da openclaw) -OpenClaw può eseguire un **profilo Chrome/Brave/Edge/Chromium dedicato** controllato dall'agente. -È isolato dal tuo browser personale ed è gestito tramite un piccolo -servizio di controllo locale all'interno del Gateway (solo loopback). +OpenClaw può eseguire un **profilo dedicato Chrome/Brave/Edge/Chromium** controllato dall'agente. +È isolato dal tuo browser personale ed è gestito tramite un piccolo servizio di +controllo locale all'interno del Gateway (solo loopback). Vista per principianti: - Consideralo come un **browser separato, solo per l'agente**. - Il profilo `openclaw` **non** tocca il profilo del tuo browser personale. -- L'agente può **aprire schede, leggere pagine, fare clic e digitare** in un percorso sicuro. -- Il profilo `user` integrato si collega alla tua sessione Chrome reale con accesso effettuato tramite Chrome MCP. +- L'agente può **aprire schede, leggere pagine, fare clic e digitare** in una corsia sicura. +- Il profilo integrato `user` si collega alla tua sessione Chrome reale autenticata tramite Chrome MCP. ## Cosa ottieni - Un profilo browser separato chiamato **openclaw** (accento arancione per impostazione predefinita). - Controllo deterministico delle schede (elenca/apri/metti a fuoco/chiudi). -- Azioni dell'agente (clic/digita/trascina/seleziona), snapshot, screenshot, PDF. -- Supporto opzionale per più profili (`openclaw`, `work`, `remote`, ...). +- Azioni dell'agente (clic/digitazione/trascinamento/selezione), snapshot, screenshot, PDF. +- Supporto facoltativo per più profili (`openclaw`, `work`, `remote`, ...). -Questo browser **non** è il tuo browser principale per tutti i giorni. È una superficie sicura e isolata per +Questo browser **non** è il tuo browser quotidiano. È una superficie sicura e isolata per l'automazione e la verifica da parte dell'agente. ## Avvio rapido @@ -46,16 +46,16 @@ openclaw browser --browser-profile openclaw open https://example.com openclaw browser --browser-profile openclaw snapshot ``` -Se ricevi “Browser disabled”, abilitalo nella configurazione (vedi sotto) e riavvia il +Se ottieni “Browser disabled”, abilitalo nella configurazione (vedi sotto) e riavvia il Gateway. -Se `openclaw browser` manca del tutto, oppure l'agente dice che lo strumento browser +Se `openclaw browser` manca completamente, oppure l'agente dice che lo strumento browser non è disponibile, vai a [Comando o strumento browser mancante](/it/tools/browser#missing-browser-command-or-tool). ## Controllo del Plugin -Lo strumento `browser` predefinito ora è un Plugin incluso che viene distribuito abilitato per -impostazione predefinita. Questo significa che puoi disabilitarlo o sostituirlo senza rimuovere il resto del +Lo strumento `browser` predefinito è ora un Plugin integrato che viene distribuito abilitato per +impostazione predefinita. Ciò significa che puoi disabilitarlo o sostituirlo senza rimuovere il resto del sistema di Plugin di OpenClaw: ```json5 @@ -70,33 +70,33 @@ sistema di Plugin di OpenClaw: } ``` -Disabilita il Plugin incluso prima di installare un altro plugin che fornisce lo -stesso nome strumento `browser`. L'esperienza browser predefinita richiede entrambi: +Disabilita il Plugin integrato prima di installare un altro plugin che fornisce lo +stesso nome di strumento `browser`. L'esperienza browser predefinita richiede entrambi: - `plugins.entries.browser.enabled` non disabilitato - `browser.enabled=true` -Se disattivi solo il Plugin, la CLI browser inclusa (`openclaw browser`), -il metodo Gateway (`browser.request`), lo strumento agente e il servizio di controllo browser -predefinito scompaiono tutti insieme. La tua configurazione `browser.*` rimane intatta per essere riutilizzata da -un Plugin sostitutivo. +Se disattivi solo il Plugin, la CLI browser integrata (`openclaw browser`), +il metodo gateway (`browser.request`), lo strumento agente e il servizio di controllo browser +predefinito scompaiono tutti insieme. La tua configurazione `browser.*` resta intatta affinché un +plugin sostitutivo possa riutilizzarla. -Il Plugin browser incluso ora possiede anche l'implementazione runtime del browser. -Il core mantiene solo gli helper condivisi del Plugin SDK più le riesportazioni di compatibilità per -i vecchi percorsi di importazione interni. In pratica, rimuovere o sostituire il pacchetto del Plugin browser -rimuove l'insieme di funzionalità del browser invece di lasciare dietro un secondo runtime -di proprietà del core. +Il Plugin browser integrato possiede ora anche l'implementazione runtime del browser. +Il core mantiene solo helper condivisi del Plugin SDK più re-export di compatibilità per +vecchi percorsi di import interni. In pratica, rimuovere o sostituire il pacchetto plugin browser +rimuove il set di funzionalità del browser invece di lasciare dietro un secondo runtime +posseduto dal core. -Le modifiche alla configurazione del browser richiedono comunque un riavvio del Gateway affinché il Plugin incluso -possa registrare nuovamente il suo servizio browser con le nuove impostazioni. +Le modifiche alla configurazione del browser richiedono comunque un riavvio del Gateway affinché il Plugin integrato +possa registrare di nuovo il proprio servizio browser con le nuove impostazioni. ## Comando o strumento browser mancante Se `openclaw browser` diventa improvvisamente un comando sconosciuto dopo un aggiornamento, oppure -l'agente segnala che manca lo strumento browser, la causa più comune è una lista `plugins.allow` -restrittiva che non include `browser`. +l'agente segnala che lo strumento browser è mancante, la causa più comune è una +lista `plugins.allow` restrittiva che non include `browser`. -Esempio di configurazione non funzionante: +Esempio di configurazione errata: ```json5 { @@ -118,26 +118,26 @@ Correggila aggiungendo `browser` alla allowlist dei plugin: Note importanti: -- `browser.enabled=true` da solo non è sufficiente quando `plugins.allow` è impostato. -- Anche `plugins.entries.browser.enabled=true` da solo non è sufficiente quando `plugins.allow` è impostato. -- `tools.alsoAllow: ["browser"]` **non** carica il Plugin browser incluso. Regola solo la policy degli strumenti dopo che il Plugin è già stato caricato. -- Se non hai bisogno di una allowlist dei plugin restrittiva, rimuovere `plugins.allow` ripristina anche il comportamento browser incluso predefinito. +- `browser.enabled=true` da solo non basta quando è impostato `plugins.allow`. +- Anche `plugins.entries.browser.enabled=true` da solo non basta quando è impostato `plugins.allow`. +- `tools.alsoAllow: ["browser"]` **non** carica il Plugin browser integrato. Regola solo la policy degli strumenti dopo che il plugin è già stato caricato. +- Se non hai bisogno di una allowlist dei plugin restrittiva, rimuovere `plugins.allow` ripristina anche il comportamento predefinito del browser integrato. Sintomi tipici: - `openclaw browser` è un comando sconosciuto. -- `browser.request` è mancante. -- L'agente segnala che lo strumento browser non è disponibile o manca. +- `browser.request` manca. +- L'agente segnala che lo strumento browser non è disponibile o è mancante. ## Profili: `openclaw` vs `user` -- `openclaw`: browser gestito e isolato (non richiede estensioni). -- `user`: profilo integrato di collegamento Chrome MCP alla tua **vera sessione Chrome con accesso effettuato**. +- `openclaw`: browser gestito e isolato (nessuna estensione richiesta). +- `user`: profilo integrato di collegamento Chrome MCP alla tua **vera sessione Chrome autenticata**. -Per le chiamate allo strumento browser dell'agente: +Per le chiamate dello strumento browser da parte dell'agente: - Predefinito: usa il browser isolato `openclaw`. -- Preferisci `profile="user"` quando contano le sessioni già con accesso effettuato e l'utente +- Preferisci `profile="user"` quando contano le sessioni già autenticate e l'utente è al computer per fare clic/approvare eventuali prompt di collegamento. - `profile` è l'override esplicito quando vuoi una modalità browser specifica. @@ -188,30 +188,30 @@ Le impostazioni del browser si trovano in `~/.openclaw/openclaw.json`. Note: -- Il servizio di controllo browser si associa al loopback su una porta derivata da `gateway.port` - (predefinito: `18791`, cioè gateway + 2). +- Il servizio di controllo browser si collega al loopback su una porta derivata da `gateway.port` + (predefinita: `18791`, cioè gateway + 2). - Se sovrascrivi la porta del Gateway (`gateway.port` o `OPENCLAW_GATEWAY_PORT`), - le porte browser derivate cambiano per restare nella stessa “famiglia”. + le porte browser derivate si spostano per rimanere nella stessa “famiglia”. - `cdpUrl` usa per impostazione predefinita la porta CDP locale gestita quando non è impostato. - `remoteCdpTimeoutMs` si applica ai controlli di raggiungibilità CDP remoti (non loopback). - `remoteCdpHandshakeTimeoutMs` si applica ai controlli di raggiungibilità WebSocket CDP remoti. -- La navigazione/apertura scheda del browser è protetta da SSRF prima della navigazione e ricontrollata al meglio sull'URL finale `http(s)` dopo la navigazione. -- In modalità SSRF rigorosa, vengono controllati anche individuazione/sonde degli endpoint CDP remoti (`cdpUrl`, incluse le ricerche `/json/version`). +- La navigazione/apertura scheda del browser è protetta da SSRF prima della navigazione e ricontrollata, nei limiti del possibile, sull'URL finale `http(s)` dopo la navigazione. +- In modalità SSRF rigorosa, vengono controllati anche discovery/sonde degli endpoint CDP remoti (`cdpUrl`, incluse le ricerche `/json/version`). - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` è disabilitato per impostazione predefinita. Impostalo su `true` solo quando ti fidi intenzionalmente dell'accesso browser alla rete privata. - `browser.ssrfPolicy.allowPrivateNetwork` resta supportato come alias legacy per compatibilità. -- `attachOnly: true` significa “non avviare mai un browser locale; collegarsi solo se è già in esecuzione.” +- `attachOnly: true` significa “non avviare mai un browser locale; collegati solo se è già in esecuzione.” - `color` + `color` per profilo colorano l'interfaccia del browser così puoi vedere quale profilo è attivo. -- Il profilo predefinito è `openclaw` (browser standalone gestito da OpenClaw). Usa `defaultProfile: "user"` per scegliere il browser utente con accesso effettuato. -- Ordine di rilevamento automatico: browser di sistema predefinito se basato su Chromium; altrimenti Chrome → Brave → Edge → Chromium → Chrome Canary. +- Il profilo predefinito è `openclaw` (browser standalone gestito da OpenClaw). Usa `defaultProfile: "user"` per optare per il browser utente autenticato. +- Ordine di rilevamento automatico: browser predefinito del sistema se basato su Chromium; altrimenti Chrome → Brave → Edge → Chromium → Chrome Canary. - I profili `openclaw` locali assegnano automaticamente `cdpPort`/`cdpUrl` — impostali solo per CDP remoto. -- `driver: "existing-session"` usa Chrome DevTools MCP invece di CDP grezzo. Non +- `driver: "existing-session"` usa Chrome DevTools MCP invece del CDP grezzo. Non impostare `cdpUrl` per quel driver. - Imposta `browser.profiles..userDataDir` quando un profilo existing-session deve collegarsi a un profilo utente Chromium non predefinito come Brave o Edge. -## Usa Brave (o un altro browser basato su Chromium) +## Usare Brave (o un altro browser basato su Chromium) -Se il tuo browser **di sistema predefinito** è basato su Chromium (Chrome/Brave/Edge/ecc.), +Se il tuo browser **predefinito di sistema** è basato su Chromium (Chrome/Brave/Edge/ecc), OpenClaw lo usa automaticamente. Imposta `browser.executablePath` per sovrascrivere il rilevamento automatico: @@ -246,41 +246,41 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome" ## Controllo locale vs remoto -- **Controllo locale (predefinito):** il Gateway avvia il servizio di controllo loopback e può avviare un browser locale. +- **Controllo locale (predefinito):** il Gateway avvia il servizio di controllo loopback e può lanciare un browser locale. - **Controllo remoto (host node):** esegui un host node sulla macchina che ha il browser; il Gateway inoltra a esso le azioni del browser. -- **CDP remoto:** imposta `browser.profiles..cdpUrl` (o `browser.cdpUrl`) per +- **CDP remoto:** imposta `browser.profiles..cdpUrl` (oppure `browser.cdpUrl`) per collegarti a un browser remoto basato su Chromium. In questo caso, OpenClaw non avvierà un browser locale. Il comportamento di arresto varia in base alla modalità del profilo: - profili locali gestiti: `openclaw browser stop` arresta il processo browser che OpenClaw ha avviato -- profili attach-only e CDP remoti: `openclaw browser stop` chiude la sessione di +- profili attach-only e CDP remoto: `openclaw browser stop` chiude la sessione di controllo attiva e rilascia gli override di emulazione Playwright/CDP (viewport, - schema colori, impostazioni locali, fuso orario, modalità offline e stato simile), anche + schema colori, locale, fuso orario, modalità offline e stato simile), anche se nessun processo browser è stato avviato da OpenClaw Gli URL CDP remoti possono includere autenticazione: -- Token di query (ad esempio, `https://provider.example?token=`) -- Autenticazione HTTP Basic (ad esempio, `https://user:pass@provider.example`) +- Token di query (ad es. `https://provider.example?token=`) +- Autenticazione HTTP Basic (ad es. `https://user:pass@provider.example`) -OpenClaw preserva l'autenticazione quando chiama gli endpoint `/json/*` e quando si connette -al WebSocket CDP. Preferisci variabili d'ambiente o secret manager per i -token invece di salvarli nei file di configurazione. +OpenClaw preserva l'autenticazione quando chiama gli endpoint `/json/*` e quando si collega +al WebSocket CDP. Preferisci variabili d'ambiente o gestori di segreti per i +token invece di inserirli nei file di configurazione. -## Proxy browser node (predefinito a configurazione zero) +## Proxy browser del Node (predefinito zero-config) Se esegui un **host node** sulla macchina che ha il tuo browser, OpenClaw può -instradare automaticamente le chiamate allo strumento browser verso quel node senza alcuna configurazione browser aggiuntiva. -Questo è il percorso predefinito per i Gateway remoti. +instradare automaticamente a quel node le chiamate dello strumento browser senza configurazione browser aggiuntiva. +Questo è il percorso predefinito per i gateway remoti. Note: -- L'host node espone il proprio server di controllo browser locale tramite un **comando proxy**. -- I profili provengono dalla configurazione `browser.profiles` del node stesso (uguale a quella locale). -- `nodeHost.browserProxy.allowProfiles` è opzionale. Lascialo vuoto per il comportamento legacy/predefinito: tutti i profili configurati restano raggiungibili tramite il proxy, incluse le route di creazione/eliminazione profilo. -- Se imposti `nodeHost.browserProxy.allowProfiles`, OpenClaw lo tratta come un confine di privilegio minimo: solo i profili nella allowlist possono essere destinati e le route di creazione/eliminazione dei profili persistenti vengono bloccate sulla superficie del proxy. +- L'host node espone il proprio server locale di controllo browser tramite un **comando proxy**. +- I profili provengono dalla configurazione `browser.profiles` del node stesso (uguale al locale). +- `nodeHost.browserProxy.allowProfiles` è facoltativo. Lascialo vuoto per il comportamento legacy/predefinito: tutti i profili configurati restano raggiungibili tramite il proxy, incluse le route di creazione/eliminazione dei profili. +- Se imposti `nodeHost.browserProxy.allowProfiles`, OpenClaw lo tratta come un confine a privilegi minimi: solo i profili in allowlist possono essere usati come target e le route di creazione/eliminazione dei profili persistenti vengono bloccate sulla superficie proxy. - Disabilitalo se non lo vuoi: - Sul node: `nodeHost.browserProxy.enabled=false` - Sul gateway: `gateway.nodes.browser.mode="off"` @@ -313,24 +313,38 @@ Esempio: Note: -- Sostituisci `` con il tuo token Browserless reale. +- Sostituisci `` con il tuo vero token Browserless. - Scegli l'endpoint regionale che corrisponde al tuo account Browserless (vedi la loro documentazione). - Se Browserless ti fornisce un URL base HTTPS, puoi convertirlo in `wss://` per una connessione CDP diretta oppure mantenere l'URL HTTPS e lasciare che OpenClaw - individui `/json/version`. + scopra `/json/version`. ## Provider CDP WebSocket diretti Alcuni servizi browser ospitati espongono un endpoint **WebSocket diretto** invece -del rilevamento CDP standard basato su HTTP (`/json/version`). OpenClaw supporta entrambi: +dello standard di discovery CDP basato su HTTP (`/json/version`). OpenClaw accetta tre +forme di URL CDP e sceglie automaticamente la strategia di connessione corretta: -- **Endpoint HTTP(S)** — OpenClaw chiama `/json/version` per individuare l'URL del debugger - WebSocket, quindi si connette. -- **Endpoint WebSocket** (`ws://` / `wss://`) — OpenClaw si connette direttamente, - saltando `/json/version`. Usa questa modalità per servizi come - [Browserless](https://browserless.io), - [Browserbase](https://www.browserbase.com), o qualsiasi provider che ti fornisca un - URL WebSocket. +- **Discovery HTTP(S)** — `http://host[:port]` oppure `https://host[:port]`. + OpenClaw chiama `/json/version` per scoprire l'URL del debugger WebSocket, quindi + si collega. Nessun fallback WebSocket. +- **Endpoint WebSocket diretti** — `ws://host[:port]/devtools//` oppure + `wss://...` con un percorso `/devtools/browser|page|worker|shared_worker|service_worker/`. + OpenClaw si collega direttamente tramite un handshake WebSocket e salta + completamente `/json/version`. +- **Radici WebSocket bare** — `ws://host[:port]` oppure `wss://host[:port]` senza + un percorso `/devtools/...` (ad es. [Browserless](https://browserless.io), + [Browserbase](https://www.browserbase.com)). OpenClaw prova prima la discovery HTTP + `/json/version` (normalizzando lo schema in `http`/`https`); + se la discovery restituisce un `webSocketDebuggerUrl`, viene usato, altrimenti OpenClaw + ripiega su un handshake WebSocket diretto alla radice bare. Questo copre + sia le porte di debug remoto in stile Chrome sia i provider solo WebSocket. + +`ws://host:port` / `wss://host:port` semplice senza un percorso `/devtools/...` +puntato a un'istanza Chrome locale è supportato tramite il fallback +discovery-first — Chrome accetta upgrade WebSocket solo sul percorso specifico per browser +o target restituito da `/json/version`, quindi un handshake alla sola radice bare +fallirebbe. ### Browserbase @@ -359,10 +373,10 @@ Note: - [Registrati](https://www.browserbase.com/sign-up) e copia la tua **API Key** dalla [dashboard Overview](https://www.browserbase.com/overview). -- Sostituisci `` con la tua vera API key Browserbase. +- Sostituisci `` con la tua vera chiave API Browserbase. - Browserbase crea automaticamente una sessione browser alla connessione WebSocket, quindi non è necessario alcun passaggio manuale di creazione della sessione. -- Il piano gratuito consente una sessione concorrente e un'ora di browser al mese. +- Il piano gratuito consente una sessione concorrente e un'ora browser al mese. Vedi i [prezzi](https://www.browserbase.com/pricing) per i limiti dei piani a pagamento. - Consulta la [documentazione Browserbase](https://docs.browserbase.com) per il riferimento API completo, le guide SDK e gli esempi di integrazione. @@ -372,36 +386,36 @@ Note: Concetti chiave: - Il controllo del browser è solo loopback; l'accesso passa tramite l'autenticazione del Gateway o l'associazione del node. -- L'API HTTP browser standalone su loopback usa **solo autenticazione con segreto condiviso**: - autenticazione bearer con token del gateway, `x-openclaw-password`, oppure autenticazione HTTP Basic con la - password del gateway configurata. +- L'API HTTP browser standalone in loopback usa **solo autenticazione con segreto condiviso**: + auth bearer con token gateway, `x-openclaw-password` oppure autenticazione HTTP Basic con la + password gateway configurata. - Gli header di identità Tailscale Serve e `gateway.auth.mode: "trusted-proxy"` **non** - autenticano questa API browser standalone su loopback. -- Se il controllo del browser è abilitato e non è configurata alcuna autenticazione con segreto condiviso, OpenClaw - genera automaticamente `gateway.auth.token` all'avvio e lo salva nella configurazione. -- OpenClaw **non** genera automaticamente quel token quando `gateway.auth.mode` è - già `password`, `none`, o `trusted-proxy`. + autenticano questa API browser standalone in loopback. +- Se il controllo browser è abilitato e non è configurata alcuna autenticazione con segreto condiviso, OpenClaw + genera automaticamente `gateway.auth.token` all'avvio e lo rende persistente nella configurazione. +- OpenClaw **non** genera automaticamente quel token quando `gateway.auth.mode` è già + `password`, `none` oppure `trusted-proxy`. - Mantieni il Gateway e qualsiasi host node su una rete privata (Tailscale); evita l'esposizione pubblica. -- Tratta gli URL/token CDP remoti come segreti; preferisci variabili d'ambiente o un secret manager. +- Tratta gli URL/token CDP remoti come segreti; preferisci variabili d'ambiente o un gestore di segreti. Suggerimenti per CDP remoto: -- Preferisci endpoint cifrati (HTTPS o WSS) e token a breve durata quando possibile. -- Evita di incorporare token a lunga durata direttamente nei file di configurazione. +- Preferisci endpoint cifrati (HTTPS o WSS) e token di breve durata quando possibile. +- Evita di incorporare direttamente token di lunga durata nei file di configurazione. -## Profili (multi-browser) +## Profili (browser multipli) -OpenClaw supporta più profili con nome (configurazioni di instradamento). I profili possono essere: +OpenClaw supporta più profili con nome (configurazioni di routing). I profili possono essere: -- **gestiti da openclaw**: un'istanza dedicata di browser basato su Chromium con la propria directory dati utente + porta CDP +- **gestiti da openclaw**: un'istanza browser dedicata basata su Chromium con la propria directory dati utente + porta CDP - **remoto**: un URL CDP esplicito (browser basato su Chromium in esecuzione altrove) -- **sessione esistente**: il tuo profilo Chrome esistente tramite auto-connessione Chrome DevTools MCP +- **sessione esistente**: il tuo profilo Chrome esistente tramite collegamento automatico Chrome DevTools MCP -Predefiniti: +Valori predefiniti: - Il profilo `openclaw` viene creato automaticamente se manca. - Il profilo `user` è integrato per il collegamento existing-session di Chrome MCP. -- I profili existing-session sono opzionali oltre a `user`; creali con `--driver existing-session`. +- I profili existing-session sono opt-in oltre a `user`; creali con `--driver existing-session`. - Le porte CDP locali vengono allocate da **18800–18899** per impostazione predefinita. - L'eliminazione di un profilo sposta la sua directory dati locale nel Cestino. @@ -409,11 +423,11 @@ Tutti gli endpoint di controllo accettano `?profile=`; la CLI usa `--brows ## Existing-session tramite Chrome DevTools MCP -OpenClaw può anche collegarsi a un profilo browser basato su Chromium in esecuzione tramite il -server ufficiale Chrome DevTools MCP. Questo riutilizza le schede e lo stato di accesso +OpenClaw può anche collegarsi a un profilo browser già in esecuzione basato su Chromium tramite +il server ufficiale Chrome DevTools MCP. Questo riutilizza le schede e lo stato di accesso già aperti in quel profilo browser. -Riferimenti ufficiali di contesto e configurazione: +Riferimenti ufficiali per contesto e configurazione: - [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session) - [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp) @@ -422,12 +436,12 @@ Profilo integrato: - `user` -Opzionale: crea il tuo profilo existing-session personalizzato se vuoi un +Facoltativo: crea un tuo profilo existing-session personalizzato se vuoi un nome, colore o directory dati browser diversi. Comportamento predefinito: -- Il profilo `user` integrato usa l'auto-connessione Chrome MCP, che punta al +- Il profilo integrato `user` usa il collegamento automatico Chrome MCP, che punta al profilo locale predefinito di Google Chrome. Usa `userDataDir` per Brave, Edge, Chromium o un profilo Chrome non predefinito: @@ -451,7 +465,7 @@ Quindi, nel browser corrispondente: 1. Apri la pagina inspect di quel browser per il debug remoto. 2. Abilita il debug remoto. -3. Lascia il browser in esecuzione e approva il prompt di connessione quando OpenClaw si collega. +3. Mantieni il browser in esecuzione e approva il prompt di connessione quando OpenClaw si collega. Pagine inspect comuni: @@ -468,70 +482,71 @@ openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot --format ai ``` -Come appare il successo: +Aspetto di un esito positivo: - `status` mostra `driver: existing-session` - `status` mostra `transport: chrome-mcp` - `status` mostra `running: true` -- `tabs` elenca le schede del browser già aperte +- `tabs` elenca le schede browser già aperte - `snapshot` restituisce ref dalla scheda live selezionata Cosa controllare se il collegamento non funziona: - il browser di destinazione basato su Chromium è alla versione `144+` - il debug remoto è abilitato nella pagina inspect di quel browser -- il browser ha mostrato il prompt di consenso al collegamento e tu lo hai accettato -- `openclaw doctor` migra la vecchia configurazione browser basata su estensione e verifica che - Chrome sia installato localmente per i profili predefiniti con auto-connessione, ma non può - abilitare per te il debug remoto dal lato browser +- il browser ha mostrato il prompt di consenso al collegamento e lo hai accettato +- `openclaw doctor` migra la vecchia configurazione browser basata su estensione e controlla che + Chrome sia installato localmente per i profili predefiniti con collegamento automatico, ma non può + abilitare per te il debug remoto lato browser Uso da parte dell'agente: -- Usa `profile="user"` quando hai bisogno dello stato del browser con accesso effettuato dell'utente. +- Usa `profile="user"` quando ti serve lo stato del browser autenticato dell'utente. - Se usi un profilo existing-session personalizzato, passa quel nome profilo esplicito. - Scegli questa modalità solo quando l'utente è al computer per approvare il prompt di collegamento. -- il Gateway o l'host node può eseguire `npx chrome-devtools-mcp@latest --autoConnect` +- il Gateway o l'host node possono avviare `npx chrome-devtools-mcp@latest --autoConnect` Note: -- Questo percorso è più rischioso del profilo `openclaw` isolato perché può - agire all'interno della tua sessione browser con accesso effettuato. +- Questo percorso è più rischioso del profilo isolato `openclaw` perché può + agire all'interno della tua sessione browser autenticata. - OpenClaw non avvia il browser per questo driver; si collega solo a una sessione esistente. - OpenClaw usa qui il flusso ufficiale Chrome DevTools MCP `--autoConnect`. Se - `userDataDir` è impostato, OpenClaw lo passa per puntare a quella specifica + `userDataDir` è impostato, OpenClaw lo inoltra per puntare a quella esplicita directory dati utente Chromium. -- Gli screenshot existing-session supportano acquisizioni della pagina e acquisizioni di elementi `--ref` - dagli snapshot, ma non i selettori CSS `--element`. +- Gli screenshot existing-session supportano acquisizioni di pagina e acquisizioni di elementi `--ref` + da snapshot, ma non i selettori CSS `--element`. - Gli screenshot di pagina existing-session funzionano senza Playwright tramite Chrome MCP. - Gli screenshot di elementi basati su ref (`--ref`) funzionano anche lì, ma `--full-page` + Anche gli screenshot di elementi basati su ref (`--ref`) funzionano lì, ma `--full-page` non può essere combinato con `--ref` o `--element`. - Le azioni existing-session sono ancora più limitate rispetto al percorso del browser gestito: - - `click`, `type`, `hover`, `scrollIntoView`, `drag`, e `select` richiedono - ref snapshot invece dei selettori CSS - - `click` è solo con il pulsante sinistro (nessuna sovrascrittura del pulsante o modificatore) + - `click`, `type`, `hover`, `scrollIntoView`, `drag` e `select` richiedono + ref di snapshot invece di selettori CSS + - `click` è solo con pulsante sinistro (nessuna sovrascrittura del pulsante o modificatori) - `type` non supporta `slowly=true`; usa `fill` o `press` - `press` non supporta `delayMs` - - `hover`, `scrollIntoView`, `drag`, `select`, `fill`, e `evaluate` non - supportano override di timeout per chiamata - - `select` al momento supporta un solo valore -- Existing-session `wait --url` supporta pattern esatti, sottostringa e glob + - `hover`, `scrollIntoView`, `drag`, `select`, `fill` ed `evaluate` non + supportano override di timeout per singola chiamata + - `select` attualmente supporta solo un singolo valore +- Existing-session `wait --url` supporta pattern esatti, per sottostringa e glob come gli altri driver browser. `wait --load networkidle` non è ancora supportato. - Gli hook di upload existing-session richiedono `ref` o `inputRef`, supportano un file alla volta e non supportano il targeting CSS `element`. -- Gli hook dialog existing-session non supportano override di timeout. -- Alcune funzionalità richiedono ancora il percorso browser gestito, inclusi +- Gli hook di dialog existing-session non supportano override di timeout. +- Alcune funzionalità richiedono ancora il percorso del browser gestito, inclusi azioni batch, esportazione PDF, intercettazione dei download e `responsebody`. -- Existing-session è locale all'host. Se Chrome si trova su una macchina diversa o in un - namespace di rete diverso, usa invece CDP remoto o un host node. +- Existing-session può collegarsi sull'host selezionato o tramite un browser node + connesso. Se Chrome si trova altrove e non è connesso alcun browser node, usa + CDP remoto o un host node. ## Garanzie di isolamento - **Directory dati utente dedicata**: non tocca mai il profilo del tuo browser personale. -- **Porte dedicate**: evita `9222` per prevenire collisioni con i flussi di lavoro di sviluppo. -- **Controllo deterministico delle schede**: le schede di destinazione vengono identificate tramite `targetId`, non tramite “ultima scheda”. +- **Porte dedicate**: evita `9222` per prevenire collisioni con i workflow di sviluppo. +- **Controllo deterministico delle schede**: usa come target le schede tramite `targetId`, non “ultima scheda”. ## Selezione del browser @@ -551,7 +566,7 @@ Piattaforme: - Linux: cerca `google-chrome`, `brave`, `microsoft-edge`, `chromium`, ecc. - Windows: controlla le posizioni di installazione comuni. -## API di controllo (opzionale) +## API di controllo (facoltativa) Solo per integrazioni locali, il Gateway espone una piccola API HTTP loopback: @@ -570,71 +585,71 @@ Solo per integrazioni locali, il Gateway espone una piccola API HTTP loopback: Tutti gli endpoint accettano `?profile=`. -Se è configurata l'autenticazione gateway con segreto condiviso, anche le route HTTP browser richiedono autenticazione: +Se è configurata l'autenticazione gateway con segreto condiviso, anche le route HTTP del browser richiedono autenticazione: - `Authorization: Bearer ` - `x-openclaw-password: ` oppure autenticazione HTTP Basic con quella password Note: -- Questa API browser standalone su loopback **non** usa trusted-proxy o +- Questa API browser standalone in loopback **non** usa trusted-proxy né gli header di identità Tailscale Serve. -- Se `gateway.auth.mode` è `none` o `trusted-proxy`, queste route browser su loopback - non ereditano quelle modalità basate su identità; mantienile solo loopback. +- Se `gateway.auth.mode` è `none` oppure `trusted-proxy`, queste route browser loopback + non ereditano quelle modalità basate sull'identità; mantienile solo loopback. ### Contratto di errore `/act` -`POST /act` usa una risposta di errore strutturata per la validazione a livello di route e -i fallimenti di policy: +`POST /act` usa una risposta di errore strutturata per validazione a livello di route e +fallimenti di policy: ```json { "error": "", "code": "ACT_*" } ``` -Valori `code` correnti: +Valori `code` attuali: -- `ACT_KIND_REQUIRED` (HTTP 400): `kind` manca o non è riconosciuto. -- `ACT_INVALID_REQUEST` (HTTP 400): il payload dell'azione ha fallito normalizzazione o validazione. -- `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): è stato usato `selector` con un tipo di azione non supportato. -- `ACT_EVALUATE_DISABLED` (HTTP 403): `evaluate` (o `wait --fn`) è disabilitato dalla configurazione. +- `ACT_KIND_REQUIRED` (HTTP 400): `kind` è mancante o non riconosciuto. +- `ACT_INVALID_REQUEST` (HTTP 400): il payload dell'azione non ha superato normalizzazione o validazione. +- `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): `selector` è stato usato con un tipo di azione non supportato. +- `ACT_EVALUATE_DISABLED` (HTTP 403): `evaluate` (oppure `wait --fn`) è disabilitato dalla configurazione. - `ACT_TARGET_ID_MISMATCH` (HTTP 403): `targetId` di primo livello o batch è in conflitto con il target della richiesta. - `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): l'azione non è supportata per i profili existing-session. -Altri errori di runtime possono ancora restituire `{ "error": "" }` senza un +Altri errori di runtime possono comunque restituire `{ "error": "" }` senza un campo `code`. ### Requisito Playwright -Alcune funzionalità (navigate/act/AI snapshot/role snapshot, screenshot di elementi, +Alcune funzionalità (`navigate`/`act`/snapshot AI/role snapshot, screenshot di elementi, PDF) richiedono Playwright. Se Playwright non è installato, quegli endpoint restituiscono un chiaro errore 501. -Cosa continua a funzionare senza Playwright: +Cosa funziona ancora senza Playwright: -- Snapshot ARIA -- Screenshot di pagina per il browser `openclaw` gestito quando è disponibile un WebSocket - CDP per scheda -- Screenshot di pagina per profili `existing-session` / Chrome MCP -- Screenshot existing-session basati su `--ref` dall'output dello snapshot +- snapshot ARIA +- screenshot di pagina per il browser `openclaw` gestito quando è disponibile un + WebSocket CDP per scheda +- screenshot di pagina per i profili `existing-session` / Chrome MCP +- screenshot `existing-session` basati su ref (`--ref`) dall'output di snapshot Cosa richiede ancora Playwright: - `navigate` - `act` -- AI snapshot / role snapshot -- Screenshot di elementi con selettore CSS (`--element`) -- Esportazione PDF completa del browser +- snapshot AI / role snapshot +- screenshot di elementi con selettori CSS (`--element`) +- esportazione PDF completa del browser -Anche gli screenshot di elementi rifiutano `--full-page`; la route restituisce `fullPage is +Gli screenshot di elementi rifiutano anche `--full-page`; la route restituisce `fullPage is not supported for element screenshots`. -Se vedi `Playwright is not available in this gateway build`, installa il pacchetto -Playwright completo (non `playwright-core`) e riavvia il gateway, oppure reinstalla -OpenClaw con il supporto browser. +Se vedi `Playwright is not available in this gateway build`, installa il pacchetto completo +Playwright (non `playwright-core`) e riavvia il gateway, oppure reinstalla +OpenClaw con supporto browser. -#### Installazione di Playwright in Docker +#### Installazione Docker di Playwright -Se il tuo Gateway è in esecuzione in Docker, evita `npx playwright` (conflitti con gli override npm). +Se il tuo Gateway è eseguito in Docker, evita `npx playwright` (conflitti con gli override npm). Usa invece la CLI inclusa: ```bash @@ -643,7 +658,7 @@ docker compose run --rm openclaw-cli \ ``` Per rendere persistenti i download del browser, imposta `PLAYWRIGHT_BROWSERS_PATH` (ad esempio, -`/home/node/.cache/ms-playwright`) e assicurati che `/home/node` sia persistito tramite +`/home/node/.cache/ms-playwright`) e assicurati che `/home/node` sia persistente tramite `OPENCLAW_HOME_VOLUME` o un bind mount. Vedi [Docker](/it/install/docker). ## Come funziona (interno) @@ -651,20 +666,20 @@ Per rendere persistenti i download del browser, imposta `PLAYWRIGHT_BROWSERS_PAT Flusso di alto livello: - Un piccolo **server di controllo** accetta richieste HTTP. -- Si collega ai browser basati su Chromium (Chrome/Brave/Edge/Chromium) tramite **CDP**. -- Per le azioni avanzate (clic/digitazione/snapshot/PDF), usa **Playwright** sopra +- Si collega a browser basati su Chromium (Chrome/Brave/Edge/Chromium) tramite **CDP**. +- Per azioni avanzate (clic/digitazione/snapshot/PDF), usa **Playwright** sopra CDP. -- Quando Playwright non è presente, sono disponibili solo le operazioni che non usano Playwright. +- Quando Playwright manca, sono disponibili solo operazioni che non usano Playwright. -Questo design mantiene l'agente su un'interfaccia stabile e deterministica, permettendoti al contempo -di cambiare browser e profili locali/remoti. +Questo design mantiene l'agente su un'interfaccia stabile e deterministica, lasciandoti al contempo +la possibilità di sostituire browser e profili locali/remoti. ## Riferimento rapido CLI -Tutti i comandi accettano `--browser-profile ` per indirizzare un profilo specifico. +Tutti i comandi accettano `--browser-profile ` per puntare a un profilo specifico. Tutti i comandi accettano anche `--json` per output leggibile da macchina (payload stabili). -Nozioni di base: +Base: - `openclaw browser status` - `openclaw browser start` @@ -695,7 +710,7 @@ Ispezione: Nota sul ciclo di vita: -- Per i profili attach-only e CDP remoti, `openclaw browser stop` è comunque il +- Per i profili attach-only e CDP remoto, `openclaw browser stop` resta comunque il comando di pulizia corretto dopo i test. Chiude la sessione di controllo attiva e cancella gli override temporanei di emulazione invece di terminare il browser sottostante. @@ -749,36 +764,36 @@ Stato: Note: -- `upload` e `dialog` sono chiamate di **preparazione**; eseguirle prima del clic/della pressione - che attiva il selettore/la finestra di dialogo. -- I percorsi di output di download e trace sono vincolati alle root temporanee di OpenClaw: +- `upload` e `dialog` sono chiamate di **arming**; eseguirle prima del clic/tasto + che attiva il chooser/dialog. +- I percorsi di output di download e trace sono vincolati alle radici temp di OpenClaw: - trace: `/tmp/openclaw` (fallback: `${os.tmpdir()}/openclaw`) - download: `/tmp/openclaw/downloads` (fallback: `${os.tmpdir()}/openclaw/downloads`) -- I percorsi di upload sono vincolati a una root temporanea uploads di OpenClaw: - - uploads: `/tmp/openclaw/uploads` (fallback: `${os.tmpdir()}/openclaw/uploads`) -- `upload` può anche impostare direttamente input file tramite `--input-ref` o `--element`. +- I percorsi di upload sono vincolati a una radice temp upload di OpenClaw: + - upload: `/tmp/openclaw/uploads` (fallback: `${os.tmpdir()}/openclaw/uploads`) +- `upload` può anche impostare direttamente input file tramite `--input-ref` oppure `--element`. - `snapshot`: - `--format ai` (predefinito quando Playwright è installato): restituisce uno snapshot AI con ref numerici (`aria-ref=""`). - `--format aria`: restituisce l'albero di accessibilità (senza ref; solo ispezione). - - `--efficient` (o `--mode efficient`): preset compatto per role snapshot (interactive + compact + depth + maxChars più basso). - - Configurazione predefinita (solo tool/CLI): imposta `browser.snapshotDefaults.mode: "efficient"` per usare snapshot efficienti quando il chiamante non passa una modalità (vedi [Configurazione Gateway](/it/gateway/configuration-reference#browser)). - - Le opzioni del role snapshot (`--interactive`, `--compact`, `--depth`, `--selector`) forzano uno snapshot basato su ruoli con ref come `ref=e12`. - - `--frame "