diff --git a/docs/it/channels/zalouser.md b/docs/it/channels/zalouser.md index 6780b97bc..5855ac9f0 100644 --- a/docs/it/channels/zalouser.md +++ b/docs/it/channels/zalouser.md @@ -1,14 +1,14 @@ --- read_when: - Configurare Zalo Personal per OpenClaw - - Debug del login o del flusso dei messaggi di Zalo Personal + - Debug del login Zalo Personal o del flusso dei messaggi summary: Supporto per account personale Zalo tramite zca-js nativo (accesso con QR), funzionalità e configurazione title: Zalo personale x-i18n: - generated_at: "2026-05-02T22:17:11Z" + generated_at: "2026-05-04T18:23:42Z" model: gpt-5.5 provider: openai - source_hash: 0096775e0017e504130f2e19e05ab8114eadb873a9e11f79ea8f0dd91297567f + source_hash: 0f6d27f0ca502e6426abe21d609efd0a168a0b6b0fafe8d52d59f1a717da1ed5 source_path: channels/zalouser.md workflow: 16 --- @@ -19,17 +19,17 @@ Stato: sperimentale. Questa integrazione automatizza un **account Zalo personale Questa è un'integrazione non ufficiale e può comportare la sospensione o il ban dell'account. Usala a tuo rischio. -## Plugin incluso +## Plugin in bundle -Zalo Personal viene distribuito come Plugin incluso nelle versioni attuali di OpenClaw, quindi le normali build -pacchettizzate non richiedono un'installazione separata. +Zalo Personal viene fornito come Plugin in bundle nelle versioni attuali di OpenClaw, quindi le normali +build pacchettizzate non richiedono un'installazione separata. -Se usi una build precedente o un'installazione personalizzata che esclude Zalo Personal, +Se usi una build meno recente o un'installazione personalizzata che esclude Zalo Personal, installa direttamente il pacchetto npm: - Installa tramite CLI: `openclaw plugins install @openclaw/zalouser` - Versione bloccata: `openclaw plugins install @openclaw/zalouser@2026.5.2` -- Oppure da un checkout del sorgente: `openclaw plugins install ./path/to/local/zalouser-plugin` +- Oppure da un checkout dei sorgenti: `openclaw plugins install ./path/to/local/zalouser-plugin` - Dettagli: [Plugin](/it/tools/plugin) Non è richiesto alcun binario CLI esterno `zca`/`openzca`. @@ -37,9 +37,9 @@ Non è richiesto alcun binario CLI esterno `zca`/`openzca`. ## Configurazione rapida (principianti) 1. Assicurati che il Plugin Zalo Personal sia disponibile. - - Le versioni pacchettizzate attuali di OpenClaw lo includono già. - - Le installazioni precedenti/personalizzate possono aggiungerlo manualmente con i comandi sopra. -2. Accedi (QR, sulla macchina del Gateway): + - Le versioni pacchettizzate attuali di OpenClaw lo includono già in bundle. + - Le installazioni meno recenti/personalizzate possono aggiungerlo manualmente con i comandi sopra. +2. Accedi (QR, sulla macchina Gateway): - `openclaw channels login --channel zalouser` - Scansiona il codice QR con l'app mobile Zalo. 3. Abilita il canale: @@ -56,22 +56,22 @@ Non è richiesto alcun binario CLI esterno `zca`/`openzca`. ``` 4. Riavvia il Gateway (o completa la configurazione). -5. L'accesso ai DM usa l'associazione per impostazione predefinita; approva il codice di associazione al primo contatto. +5. L'accesso DM usa per impostazione predefinita l'abbinamento; approva il codice di abbinamento al primo contatto. -## Che cos'è +## Cos'è -- Funziona interamente nel processo tramite `zca-js`. -- Usa listener di eventi nativi per ricevere i messaggi in ingresso. +- Viene eseguito interamente in-process tramite `zca-js`. +- Usa listener di eventi nativi per ricevere messaggi in ingresso. - Invia risposte direttamente tramite l'API JS (testo/media/link). - Progettato per casi d'uso con “account personale” in cui l'API Zalo Bot non è disponibile. -## Denominazione +## Nomenclatura L'id del canale è `zalouser` per rendere esplicito che automatizza un **account utente Zalo personale** (non ufficiale). Manteniamo `zalo` riservato per una potenziale futura integrazione ufficiale con l'API Zalo. ## Trovare gli ID (directory) -Usa la CLI della directory per individuare peer/gruppi e i loro ID: +Usa la CLI della directory per scoprire peer/gruppi e i relativi ID: ```bash openclaw directory self --channel zalouser @@ -88,7 +88,9 @@ openclaw directory groups list --channel zalouser --query "work" `channels.zalouser.dmPolicy` supporta: `pairing | allowlist | open | disabled` (predefinito: `pairing`). -`channels.zalouser.allowFrom` accetta ID utente o nomi. Durante la configurazione, i nomi vengono risolti in ID usando la ricerca contatti nel processo del Plugin. +`channels.zalouser.allowFrom` deve usare ID utente Zalo stabili. Durante la configurazione interattiva, i nomi inseriti possono essere risolti in ID usando la ricerca contatti in-process del Plugin. + +Se un nome grezzo rimane nella configurazione, all'avvio viene risolto solo quando `channels.zalouser.dangerouslyAllowNameMatching: true` è abilitato. Senza quell'opt-in, i controlli runtime del mittente sono solo per ID e i nomi grezzi vengono ignorati per l'autorizzazione. Approva tramite: @@ -97,17 +99,17 @@ Approva tramite: ## Accesso ai gruppi (opzionale) -- Predefinito: `channels.zalouser.groupPolicy = "open"` (gruppi consentiti). Usa `channels.defaults.groupPolicy` per sovrascrivere il valore predefinito quando non è impostato. +- Predefinito: `channels.zalouser.groupPolicy = "open"` (gruppi consentiti). Usa `channels.defaults.groupPolicy` per sovrascrivere il valore predefinito quando non impostato. - Limita a una allowlist con: - `channels.zalouser.groupPolicy = "allowlist"` - - `channels.zalouser.groups` (le chiavi dovrebbero essere ID gruppo stabili; i nomi vengono risolti in ID all'avvio quando possibile) + - `channels.zalouser.groups` (le chiavi devono essere ID gruppo stabili; i nomi vengono risolti in ID all'avvio solo quando `channels.zalouser.dangerouslyAllowNameMatching: true` è abilitato) - `channels.zalouser.groupAllowFrom` (controlla quali mittenti nei gruppi consentiti possono attivare il bot) - Blocca tutti i gruppi: `channels.zalouser.groupPolicy = "disabled"`. -- La procedura guidata di configurazione può richiedere allowlist di gruppi. -- All'avvio, OpenClaw risolve i nomi di gruppi/utenti nelle allowlist in ID e registra la mappatura nei log. -- La corrispondenza della allowlist dei gruppi è solo per ID per impostazione predefinita. I nomi non risolti vengono ignorati per l'autorizzazione a meno che `channels.zalouser.dangerouslyAllowNameMatching: true` sia abilitato. -- `channels.zalouser.dangerouslyAllowNameMatching: true` è una modalità di compatibilità di emergenza che riabilita la corrispondenza mutabile dei nomi dei gruppi. -- Se `groupAllowFrom` non è impostato, il runtime usa `allowFrom` come fallback per i controlli dei mittenti nei gruppi. +- La procedura guidata di configurazione può richiedere le allowlist dei gruppi. +- All'avvio, OpenClaw risolve i nomi di gruppi/utenti nelle allowlist in ID e registra la mappatura solo quando `channels.zalouser.dangerouslyAllowNameMatching: true` è abilitato. +- La corrispondenza della allowlist dei gruppi è solo per ID per impostazione predefinita. I nomi non risolti vengono ignorati per l'autenticazione a meno che `channels.zalouser.dangerouslyAllowNameMatching: true` sia abilitato. +- `channels.zalouser.dangerouslyAllowNameMatching: true` è una modalità di compatibilità break-glass che riabilita la risoluzione mutabile dei nomi all'avvio e la corrispondenza runtime dei nomi dei gruppi. +- Se `groupAllowFrom` non è impostato, il runtime ripiega su `allowFrom` per i controlli dei mittenti dei gruppi. - I controlli dei mittenti si applicano sia ai normali messaggi di gruppo sia ai comandi di controllo (per esempio `/new`, `/reset`). Esempio: @@ -127,15 +129,15 @@ Esempio: } ``` -### Controllo delle menzioni nei gruppi +### Gating delle menzioni nei gruppi -- `channels.zalouser.groups..requireMention` controlla se le risposte di gruppo richiedono una menzione. +- `channels.zalouser.groups..requireMention` controlla se le risposte nei gruppi richiedono una menzione. - Ordine di risoluzione: id/nome gruppo esatto -> slug gruppo normalizzato -> `*` -> predefinito (`true`). -- Questo si applica sia ai gruppi in allowlist sia alla modalità gruppi aperta. +- Questo si applica sia ai gruppi in allowlist sia alla modalità gruppo aperto. - Citare un messaggio del bot conta come menzione implicita per l'attivazione nel gruppo. -- I comandi di controllo autorizzati (per esempio `/new`) possono bypassare il controllo delle menzioni. -- Quando un messaggio di gruppo viene saltato perché è richiesta una menzione, OpenClaw lo archivia come cronologia di gruppo in sospeso e lo include nel successivo messaggio di gruppo elaborato. -- Il limite della cronologia dei gruppi usa come valore predefinito `messages.groupChat.historyLimit` (fallback `50`). Puoi sovrascriverlo per account con `channels.zalouser.historyLimit`. +- I comandi di controllo autorizzati (per esempio `/new`) possono bypassare il gating delle menzioni. +- Quando un messaggio di gruppo viene ignorato perché è richiesta una menzione, OpenClaw lo memorizza come cronologia di gruppo in sospeso e lo include nel successivo messaggio di gruppo elaborato. +- Il limite della cronologia dei gruppi usa per impostazione predefinita `messages.groupChat.historyLimit` (fallback `50`). Puoi sovrascriverlo per account con `channels.zalouser.historyLimit`. Esempio: @@ -153,7 +155,7 @@ Esempio: } ``` -## Account multipli +## Multi-account Gli account vengono mappati ai profili `zalouser` nello stato di OpenClaw. Esempio: @@ -174,31 +176,31 @@ Gli account vengono mappati ai profili `zalouser` nello stato di OpenClaw. Esemp ## Digitazione, reazioni e conferme di consegna - OpenClaw invia un evento di digitazione prima di inviare una risposta (best-effort). -- L'azione di reazione ai messaggi `react` è supportata per `zalouser` nelle azioni del canale. +- L'azione di reazione al messaggio `react` è supportata per `zalouser` nelle azioni del canale. - Usa `remove: true` per rimuovere una specifica emoji di reazione da un messaggio. - Semantica delle reazioni: [Reazioni](/it/tools/reactions) -- Per i messaggi in ingresso che includono metadati evento, OpenClaw invia conferme di consegna + lettura (best-effort). +- Per i messaggi in ingresso che includono metadati evento, OpenClaw invia conferme delivered + seen (best-effort). ## Risoluzione dei problemi -**L'accesso non resta valido:** +**L'accesso non persiste:** - `openclaw channels status --probe` - Accedi di nuovo: `openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser` **Il nome nella allowlist/del gruppo non è stato risolto:** -- Usa ID numerici in `allowFrom`/`groupAllowFrom`/`groups`, oppure nomi esatti di amici/gruppi. +- Usa ID numerici in `allowFrom`/`groupAllowFrom` e ID gruppo stabili in `groups`. Se ti servono intenzionalmente nomi esatti di amici/gruppi, abilita `channels.zalouser.dangerouslyAllowNameMatching: true`. -**Aggiornamento da una vecchia configurazione basata su CLI:** +**Aggiornato da una vecchia configurazione basata su CLI:** -- Rimuovi qualsiasi vecchia assunzione su processi esterni `zca`. -- Il canale ora funziona completamente in OpenClaw senza binari CLI esterni. +- Rimuovi qualsiasi vecchia assunzione su processi `zca` esterni. +- Il canale ora viene eseguito completamente in OpenClaw senza binari CLI esterni. ## Correlati - [Panoramica dei canali](/it/channels) — tutti i canali supportati -- [Associazione](/it/channels/pairing) — autenticazione DM e flusso di associazione -- [Gruppi](/it/channels/groups) — comportamento delle chat di gruppo e controllo delle menzioni +- [Abbinamento](/it/channels/pairing) — autenticazione DM e flusso di abbinamento +- [Gruppi](/it/channels/groups) — comportamento delle chat di gruppo e gating delle menzioni - [Instradamento dei canali](/it/channels/channel-routing) — instradamento delle sessioni per i messaggi -- [Sicurezza](/it/gateway/security) — modello di accesso e rafforzamento +- [Sicurezza](/it/gateway/security) — modello di accesso e hardening diff --git a/docs/it/cli/daemon.md b/docs/it/cli/daemon.md index 960be837c..d249e214f 100644 --- a/docs/it/cli/daemon.md +++ b/docs/it/cli/daemon.md @@ -1,14 +1,14 @@ --- read_when: - Usi ancora `openclaw daemon ...` negli script - - Sono necessari i comandi del ciclo di vita del servizio (install/start/stop/restart/status) -summary: Riferimento CLI per `openclaw daemon` (alias storico per la gestione del servizio Gateway) + - Sono necessari comandi del ciclo di vita del servizio (install/start/stop/restart/status) +summary: Riferimento CLI per `openclaw daemon` (alias legacy per la gestione del servizio Gateway) title: Demone x-i18n: - generated_at: "2026-05-02T22:17:33Z" + generated_at: "2026-05-04T18:23:46Z" model: gpt-5.5 provider: openai - source_hash: 3f11b75bf2781e69f6f59b23364f06cf359f9f24407f25f19b9d2186f7158512 + source_hash: f84e11fc50bdf38da518a8fcf415ae461a2688c2299f996eee384357c0d04a05 source_path: cli/daemon.md workflow: 16 --- @@ -17,7 +17,7 @@ x-i18n: Alias legacy per i comandi di gestione del servizio Gateway. -`openclaw daemon ...` mappa alla stessa superficie di controllo del servizio dei comandi di servizio `openclaw gateway ...`. +`openclaw daemon ...` corrisponde alla stessa superficie di controllo del servizio dei comandi di servizio `openclaw gateway ...`. ## Utilizzo @@ -32,7 +32,7 @@ openclaw daemon uninstall ## Sottocomandi -- `status`: mostra lo stato di installazione del servizio e verifica la salute del Gateway +- `status`: mostra lo stato di installazione del servizio e verifica lo stato del Gateway - `install`: installa il servizio (`launchd`/`systemd`/`schtasks`) - `uninstall`: rimuove il servizio - `start`: avvia il servizio @@ -43,25 +43,26 @@ openclaw daemon uninstall - `status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json` - `install`: `--port`, `--runtime `, `--token`, `--force`, `--json` -- `restart`: `--force`, `--wait `, `--json` +- `restart`: `--safe`, `--force`, `--wait `, `--json` - ciclo di vita (`uninstall|start|stop`): `--json` Note: -- `status` risolve i SecretRef di autenticazione configurati per l'autenticazione del probe quando possibile. -- Se un SecretRef di autenticazione richiesto non viene risolto in questo percorso di comando, `daemon status --json` segnala `rpc.authWarning` quando la connettività/autenticazione del probe non riesce; passa `--token`/`--password` esplicitamente oppure risolvi prima la fonte del segreto. -- Se il probe riesce, gli avvisi auth-ref non risolti vengono soppressi per evitare falsi positivi. -- `status --deep` aggiunge una scansione best-effort del servizio a livello di sistema. Quando trova altri servizi simili al gateway, l'output leggibile stampa suggerimenti di pulizia e avvisa che un gateway per macchina resta comunque la raccomandazione normale. -- Nelle installazioni systemd su Linux, i controlli di deriva del token di `status` includono sia le sorgenti unità `Environment=` sia `EnvironmentFile=`. -- I controlli di deriva risolvono i SecretRef `gateway.auth.token` usando l'env di runtime unito (prima l'env del comando di servizio, poi il fallback all'env di processo). -- Se l'autenticazione con token non è effettivamente attiva (`gateway.auth.mode` esplicito di `password`/`none`/`trusted-proxy`, oppure mode non impostata dove la password può prevalere e nessun candidato token può prevalere), i controlli di deriva del token saltano la risoluzione del token di configurazione. -- Quando l'autenticazione con token richiede un token e `gateway.auth.token` è gestito da SecretRef, `install` verifica che il SecretRef sia risolvibile ma non persiste il token risolto nei metadati dell'ambiente di servizio. -- Se l'autenticazione con token richiede un token e il SecretRef del token configurato non è risolto, l'installazione fallisce in modo chiuso. -- Se sono configurati sia `gateway.auth.token` sia `gateway.auth.password` e `gateway.auth.mode` non è impostato, l'installazione viene bloccata finché la mode non viene impostata esplicitamente. +- `status` risolve, quando possibile, le SecretRefs di autenticazione configurate per l'autenticazione del probe. +- Se una SecretRef di autenticazione richiesta non viene risolta in questo percorso del comando, `daemon status --json` segnala `rpc.authWarning` quando la connettività/autenticazione del probe non riesce; passa esplicitamente `--token`/`--password` oppure risolvi prima la sorgente del segreto. +- Se il probe riesce, gli avvisi per auth-ref non risolti vengono soppressi per evitare falsi positivi. +- `status --deep` aggiunge una scansione del servizio a livello di sistema, eseguita al meglio. Quando trova altri servizi simili al gateway, l'output leggibile stampa suggerimenti di pulizia e avvisa che la raccomandazione normale resta un gateway per macchina. +- Nelle installazioni systemd su Linux, i controlli di divergenza del token di `status` includono sia le sorgenti unit `Environment=` sia `EnvironmentFile=`. +- I controlli di divergenza risolvono le SecretRefs `gateway.auth.token` usando l'ambiente runtime unito (prima l'ambiente del comando di servizio, poi il fallback all'ambiente del processo). +- Se l'autenticazione tramite token non è effettivamente attiva (`gateway.auth.mode` esplicito di `password`/`none`/`trusted-proxy`, oppure modalità non impostata in cui la password può prevalere e nessun candidato token può prevalere), i controlli di divergenza del token saltano la risoluzione del token di configurazione. +- Quando l'autenticazione tramite token richiede un token e `gateway.auth.token` è gestito da SecretRef, `install` verifica che la SecretRef sia risolvibile ma non persiste il token risolto nei metadati dell'ambiente del servizio. +- Se l'autenticazione tramite token richiede un token e la SecretRef del token configurata non è risolta, l'installazione fallisce in modo chiuso. +- Se sono configurati sia `gateway.auth.token` sia `gateway.auth.password` e `gateway.auth.mode` non è impostato, l'installazione viene bloccata finché la modalità non viene impostata esplicitamente. - Su macOS, `install` mantiene i plist LaunchAgent accessibili solo al proprietario e carica i valori dell'ambiente del servizio gestito tramite un file e un wrapper accessibili solo al proprietario, invece di serializzare chiavi API o riferimenti env del profilo di autenticazione in `EnvironmentVariables`. -- Se esegui intenzionalmente più gateway su un host, isola porte, config/stato e workspace; vedi [/gateway#multiple-gateways-same-host](/it/gateway#multiple-gateways-same-host). +- Se esegui intenzionalmente più gateway su un host, isola porte, configurazione/stato e workspace; vedi [/gateway#multiple-gateways-same-host](/it/gateway#multiple-gateways-same-host). +- `restart --safe` chiede al Gateway in esecuzione di eseguire il preflight del lavoro attivo e pianificare un unico riavvio aggregato dopo che il lavoro attivo si è esaurito. `restart` semplice mantiene il comportamento esistente del gestore del servizio; `--force` resta il percorso di override immediato. -## Da preferire +## Preferisci Usa [`openclaw gateway`](/it/cli/gateway) per la documentazione e gli esempi correnti. diff --git a/docs/it/cli/gateway.md b/docs/it/cli/gateway.md index 5e7ac3dbd..68a43aabb 100644 --- a/docs/it/cli/gateway.md +++ b/docs/it/cli/gateway.md @@ -2,30 +2,30 @@ read_when: - Eseguire il Gateway dalla CLI (sviluppo o server) - Debug dell'autenticazione del Gateway, delle modalità di bind e della connettività - - Individuazione dei Gateway tramite Bonjour (DNS-SD locale e ad area estesa) + - Scoperta dei Gateway tramite Bonjour (DNS-SD locale e ad area estesa) sidebarTitle: Gateway -summary: OpenClaw Gateway CLI (`openclaw gateway`) — eseguire, interrogare e rilevare Gateway +summary: OpenClaw Gateway CLI (`openclaw gateway`) — avvia, interroga e rileva Gateway title: Gateway x-i18n: - generated_at: "2026-05-02T22:17:38Z" + generated_at: "2026-05-04T18:24:03Z" model: gpt-5.5 provider: openai - source_hash: f7f948a8f0ee6e065afa02f354e690ad5cc4f71bdb8b8674f1b0396c439ab242 + source_hash: 310867c59148577f2e8ce6f708da6bce936e09243ce7fbe5daeb453c6b3b370d source_path: cli/gateway.md workflow: 16 --- -Il Gateway è il server WebSocket di OpenClaw (canali, nodi, sessioni, hook). I sottocomandi in questa pagina si trovano sotto `openclaw gateway …`. +The Gateway è il server WebSocket di OpenClaw (canali, nodi, sessioni, hook). I sottocomandi in questa pagina si trovano sotto `openclaw gateway …`. - - Configurazione mDNS locale + DNS-SD wide-area. + + Configurazione mDNS locale + DNS-SD ad area vasta. - + Come OpenClaw pubblicizza e trova i gateway. - - Chiavi di configurazione del gateway di primo livello. + + Chiavi di configurazione di primo livello del gateway. @@ -44,13 +44,13 @@ openclaw gateway run ``` - - - Per impostazione predefinita, il Gateway rifiuta di avviarsi a meno che `gateway.mode=local` sia impostato in `~/.openclaw/openclaw.json`. Usa `--allow-unconfigured` per esecuzioni ad hoc/di sviluppo. - - `openclaw onboard --mode local` e `openclaw setup` dovrebbero scrivere `gateway.mode=local`. Se il file esiste ma manca `gateway.mode`, considerala una configurazione danneggiata o sovrascritta e riparala invece di assumere implicitamente la modalità locale. - - Se il file esiste e manca `gateway.mode`, il Gateway lo considera un danno di configurazione sospetto e rifiuta di "indovinare local" per te. - - L'associazione oltre il loopback senza autenticazione è bloccata (barriera di sicurezza). - - `SIGUSR1` attiva un riavvio nel processo quando autorizzato (`commands.restart` è abilitato per impostazione predefinita; imposta `commands.restart: false` per bloccare il riavvio manuale, mentre l'applicazione/aggiornamento degli strumenti/configurazione del gateway rimane consentita). - - Gli handler `SIGINT`/`SIGTERM` arrestano il processo gateway, ma non ripristinano eventuali stati personalizzati del terminale. Se avvolgi la CLI con una TUI o input in modalità raw, ripristina il terminale prima dell'uscita. + + - Per impostazione predefinita, il Gateway rifiuta di avviarsi a meno che `gateway.mode=local` non sia impostato in `~/.openclaw/openclaw.json`. Usa `--allow-unconfigured` per esecuzioni ad hoc/di sviluppo. + - `openclaw onboard --mode local` e `openclaw setup` dovrebbero scrivere `gateway.mode=local`. Se il file esiste ma `gateway.mode` manca, consideralo come una configurazione rotta o sovrascritta e riparala invece di presumere implicitamente la modalità locale. + - Se il file esiste e `gateway.mode` manca, il Gateway lo considera un danno sospetto alla configurazione e rifiuta di "indovinare local" per te. + - Il binding oltre il loopback senza autenticazione è bloccato (protezione di sicurezza). + - `SIGUSR1` attiva un riavvio in-process quando autorizzato (`commands.restart` è abilitato per impostazione predefinita; imposta `commands.restart: false` per bloccare il riavvio manuale, mentre l'applicazione/aggiornamento di strumenti/configurazione del gateway rimangono consentiti). + - I gestori `SIGINT`/`SIGTERM` arrestano il processo gateway, ma non ripristinano eventuali stati personalizzati del terminale. Se avvolgi la CLI con una TUI o input in raw mode, ripristina il terminale prima dell'uscita. @@ -61,7 +61,7 @@ openclaw gateway run Porta WebSocket (il valore predefinito viene da config/env; di solito `18789`). - Modalità di bind del listener. + Modalità di binding del listener. Override della modalità di autenticazione. @@ -79,10 +79,10 @@ openclaw gateway run Espone il Gateway tramite Tailscale. - Reimposta la configurazione serve/funnel di Tailscale allo spegnimento. + Reimposta la configurazione Tailscale serve/funnel all'arresto. - Consenti l'avvio del gateway senza `gateway.mode=local` nella configurazione. Ignora la protezione di avvio solo per bootstrap ad hoc/di sviluppo; non scrive né ripara il file di configurazione. + Consenti l'avvio del gateway senza `gateway.mode=local` nella configurazione. Aggira la protezione di avvio solo per bootstrap ad hoc/di sviluppo; non scrive né ripara il file di configurazione. Crea una configurazione di sviluppo + workspace se mancanti (salta BOOTSTRAP.md). @@ -106,45 +106,55 @@ openclaw gateway run Alias per `--ws-log compact`. - Registra gli eventi raw dello stream del modello in jsonl. + Registra gli eventi grezzi dello stream del modello in jsonl. - Percorso jsonl dello stream raw. + Percorso jsonl dello stream grezzo. +## Riavviare il Gateway + +```bash +openclaw gateway restart +openclaw gateway restart --safe +openclaw gateway restart --force +``` + +`openclaw gateway restart --safe` chiede al Gateway in esecuzione di eseguire un preflight del lavoro OpenClaw attivo prima di riavviare. Se sono attive operazioni in coda, consegna di risposte, esecuzioni embedded o esecuzioni di attività, il Gateway segnala i blocchi, unisce le richieste duplicate di riavvio sicuro e riavvia quando il lavoro attivo si esaurisce. Il semplice `restart` mantiene il comportamento esistente del gestore di servizio per compatibilità. Usa `--force` solo quando vuoi esplicitamente il percorso di override immediato. + -`--password` inline può essere esposto negli elenchi dei processi locali. Preferisci `--password-file`, env, o un `gateway.auth.password` basato su SecretRef. +`--password` inline può essere esposto negli elenchi dei processi locali. Preferisci `--password-file`, env o un `gateway.auth.password` basato su SecretRef. ### Profilazione dell'avvio -- Imposta `OPENCLAW_GATEWAY_STARTUP_TRACE=1` per registrare i tempi delle fasi durante l'avvio del Gateway, inclusi il ritardo `eventLoopMax` per fase e i tempi delle tabelle di ricerca dei plugin per installed-index, manifest registry, pianificazione dell'avvio e lavoro owner-map. -- Imposta `OPENCLAW_DIAGNOSTICS=timeline` con `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=` per scrivere una timeline diagnostica di avvio JSONL best-effort per harness QA esterni. Puoi anche abilitare il flag con `diagnostics.flags: ["timeline"]` nella configurazione; il percorso resta fornito dall'env. Aggiungi `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` per includere campioni dell'event loop. -- Esegui `pnpm test:startup:gateway -- --runs 5 --warmup 1` per misurare le prestazioni dell'avvio del Gateway. Il benchmark registra il primo output del processo, `/healthz`, `/readyz`, i tempi della traccia di avvio, il ritardo dell'event loop e i dettagli dei tempi delle tabelle di ricerca dei plugin. +- Imposta `OPENCLAW_GATEWAY_STARTUP_TRACE=1` per registrare i tempi delle fasi durante l'avvio del Gateway, inclusi il ritardo `eventLoopMax` per fase e i tempi delle tabelle di ricerca dei plugin per indice installato, registro manifest, pianificazione dell'avvio e lavoro owner-map. +- Imposta `OPENCLAW_DIAGNOSTICS=timeline` con `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=` per scrivere una timeline diagnostica di avvio JSONL best-effort per harness QA esterni. Puoi anche abilitare il flag con `diagnostics.flags: ["timeline"]` nella configurazione; il percorso viene comunque fornito tramite env. Aggiungi `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` per includere campioni dell'event loop. +- Esegui `pnpm test:startup:gateway -- --runs 5 --warmup 1` per eseguire benchmark dell'avvio del Gateway. Il benchmark registra il primo output del processo, `/healthz`, `/readyz`, i tempi della traccia di avvio, il ritardo dell'event loop e i dettagli dei tempi delle tabelle di ricerca dei plugin. ## Interrogare un Gateway in esecuzione -Tutti i comandi di interrogazione usano WebSocket RPC. +Tutti i comandi di interrogazione usano RPC WebSocket. - - - Predefinito: leggibile dall'utente (colorato in TTY). - - `--json`: JSON leggibile dalla macchina (nessuno stile/spinner). + + - Predefinita: leggibile da persone (colorata in TTY). + - `--json`: JSON leggibile da macchine (senza stile/spinner). - `--no-color` (o `NO_COLOR=1`): disabilita ANSI mantenendo il layout umano. - + - `--url `: URL WebSocket del Gateway. - `--token `: token del Gateway. - `--password `: password del Gateway. - - `--timeout `: timeout/budget (varia in base al comando). - - `--expect-final`: attendi una risposta "final" (chiamate agente). + - `--timeout `: timeout/budget (varia per comando). + - `--expect-final`: attende una risposta "final" (chiamate dell'agente). -Quando imposti `--url`, la CLI non ripiega su credenziali da configurazione o ambiente. Passa `--token` o `--password` esplicitamente. La mancanza di credenziali esplicite è un errore. +Quando imposti `--url`, la CLI non esegue fallback alle credenziali di configurazione o ambiente. Passa `--token` o `--password` esplicitamente. La mancanza di credenziali esplicite è un errore. ### `gateway health` @@ -153,7 +163,7 @@ Quando imposti `--url`, la CLI non ripiega su credenziali da configurazione o am openclaw gateway health --url ws://127.0.0.1:18789 ``` -L'endpoint HTTP `/healthz` è una sonda di liveness: restituisce una risposta quando il server può rispondere via HTTP. L'endpoint HTTP `/readyz` è più rigoroso e resta rosso mentre sidecar dei plugin di avvio, canali o hook configurati si stanno ancora stabilizzando. Le risposte di readiness dettagliate locali o autenticate includono un blocco diagnostico `eventLoop` con ritardo dell'event loop, utilizzo dell'event loop, rapporto dei core CPU e un flag `degraded`. +L'endpoint HTTP `/healthz` è un probe di liveness: restituisce una risposta quando il server può rispondere a HTTP. L'endpoint HTTP `/readyz` è più rigoroso e resta rosso mentre sidecar dei plugin di avvio, canali o hook configurati sono ancora in assestamento. Le risposte di readiness dettagliate locali o autenticate includono un blocco diagnostico `eventLoop` con ritardo dell'event loop, utilizzo dell'event loop, rapporto dei core CPU e un flag `degraded`. ### `gateway usage-cost` @@ -171,7 +181,7 @@ openclaw gateway usage-cost --json ### `gateway stability` -Recupera il registratore diagnostico recente di stabilità da un Gateway in esecuzione. +Recupera il registratore diagnostico di stabilità recente da un Gateway in esecuzione. ```bash openclaw gateway stability @@ -194,23 +204,23 @@ openclaw gateway stability --json Leggi un bundle di stabilità persistito invece di chiamare il Gateway in esecuzione. Usa `--bundle latest` (o solo `--bundle`) per il bundle più recente nella directory di stato, oppure passa direttamente un percorso JSON del bundle. - Scrivi uno zip diagnostico di supporto condivisibile invece di stampare i dettagli di stabilità. + Scrivi uno zip di diagnostica di supporto condivisibile invece di stampare i dettagli di stabilità. Percorso di output per `--export`. - - - I record mantengono metadati operativi: nomi degli eventi, conteggi, dimensioni in byte, letture di memoria, stato di code/sessioni, nomi di canali/plugin e riepiloghi di sessione redatti. Non mantengono testo delle chat, corpi dei Webhook, output degli strumenti, corpi raw di richieste o risposte, token, cookie, valori segreti, hostname o ID raw delle sessioni. Imposta `diagnostics.enabled: false` per disabilitare completamente il registratore. - - In caso di uscite fatali del Gateway, timeout di spegnimento e fallimenti di avvio dopo riavvio, OpenClaw scrive lo stesso snapshot diagnostico in `~/.openclaw/logs/stability/openclaw-stability-*.json` quando il registratore contiene eventi. Ispeziona il bundle più recente con `openclaw gateway stability --bundle latest`; `--limit`, `--type` e `--since-seq` si applicano anche all'output del bundle. + + - I record conservano metadati operativi: nomi degli eventi, conteggi, dimensioni in byte, letture di memoria, stato di coda/sessione, nomi di canali/plugin e riepiloghi di sessione redatti. Non conservano testo delle chat, corpi dei webhook, output degli strumenti, corpi grezzi di richieste o risposte, token, cookie, valori segreti, hostname o ID di sessione grezzi. Imposta `diagnostics.enabled: false` per disabilitare completamente il registratore. + - In caso di uscite fatali del Gateway, timeout di arresto e fallimenti di avvio dopo riavvio, OpenClaw scrive lo stesso snapshot diagnostico in `~/.openclaw/logs/stability/openclaw-stability-*.json` quando il registratore contiene eventi. Ispeziona il bundle più recente con `openclaw gateway stability --bundle latest`; `--limit`, `--type` e `--since-seq` si applicano anche all'output del bundle. ### `gateway diagnostics export` -Scrive uno zip diagnostico locale progettato per essere allegato alle segnalazioni di bug. Per il modello di privacy e i contenuti del bundle, consulta [Esportazione diagnostica](/it/gateway/diagnostics). +Scrive uno zip diagnostico locale progettato per essere allegato alle segnalazioni di bug. Per il modello di privacy e il contenuto del bundle, vedi [Esportazione diagnostica](/it/gateway/diagnostics). ```bash openclaw gateway diagnostics export @@ -219,7 +229,7 @@ openclaw gateway diagnostics export --json ``` - Percorso dello zip di output. Per impostazione predefinita è un'esportazione di supporto nella directory di stato. + Percorso dello zip di output. Il valore predefinito è un'esportazione di supporto nella directory di stato. Numero massimo di righe di log sanificate da includere. @@ -228,31 +238,31 @@ openclaw gateway diagnostics export --json Numero massimo di byte di log da ispezionare. - URL WebSocket del Gateway per lo snapshot di health. + URL WebSocket del Gateway per lo snapshot di salute. - Token del Gateway per lo snapshot di health. + Token del Gateway per lo snapshot di salute. - Password del Gateway per lo snapshot di health. + Password del Gateway per lo snapshot di salute. - Timeout dello snapshot di stato/health. + Timeout dello snapshot di stato/salute. Salta la ricerca del bundle di stabilità persistito. - Stampa il percorso scritto, la dimensione e il manifesto come JSON. + Stampa percorso scritto, dimensione e manifest come JSON. -L'esportazione contiene un manifesto, un riepilogo Markdown, forma della configurazione, dettagli di configurazione sanificati, riepiloghi dei log sanificati, snapshot sanificati di stato/health del Gateway e il bundle di stabilità più recente quando esiste. +L'esportazione contiene un manifest, un riepilogo Markdown, forma della configurazione, dettagli di configurazione sanificati, riepiloghi di log sanificati, snapshot di stato/salute del Gateway sanificati e il bundle di stabilità più recente quando ne esiste uno. -È pensata per essere condivisa. Mantiene dettagli operativi che aiutano il debug, come campi sicuri dei log di OpenClaw, nomi di sottosistemi, codici di stato, durate, modalità configurate, porte, ID dei plugin, ID dei provider, impostazioni non segrete delle funzionalità e messaggi di log operativi redatti. Omette o redige testo delle chat, corpi dei Webhook, output degli strumenti, credenziali, cookie, identificatori di account/messaggi, testo di prompt/istruzioni, hostname e valori segreti. Quando un messaggio in stile LogTape sembra testo di payload utente/chat/strumento, l'esportazione conserva solo il fatto che un messaggio è stato omesso più il suo conteggio in byte. +È pensata per essere condivisa. Conserva dettagli operativi utili al debug, come campi di log sicuri di OpenClaw, nomi dei sottosistemi, codici di stato, durate, modalità configurate, porte, ID plugin, ID provider, impostazioni di funzionalità non segrete e messaggi di log operativi redatti. Omette o redige testo delle chat, corpi dei webhook, output degli strumenti, credenziali, cookie, identificatori di account/messaggi, testo di prompt/istruzioni, hostname e valori segreti. Quando un messaggio in stile LogTape sembra testo di payload utente/chat/strumento, l'esportazione conserva solo il fatto che un messaggio è stato omesso più il relativo conteggio in byte. ### `gateway status` -`gateway status` mostra il servizio Gateway (launchd/systemd/schtasks) più una sonda facoltativa della connettività/capacità di autenticazione. +`gateway status` mostra il servizio Gateway (launchd/systemd/schtasks) più un probe opzionale di capacità di connettività/autenticazione. ```bash openclaw gateway status @@ -261,63 +271,63 @@ openclaw gateway status --require-rpc ``` - Aggiungi un target di sonda esplicito. Remote configurato + localhost vengono comunque sondati. + Aggiungi una destinazione di probe esplicita. Remote configurato + localhost vengono comunque sottoposti a probe. - Autenticazione token per la sonda. + Autenticazione con token per il probe. - Autenticazione password per la sonda. + Autenticazione con password per il probe. - Timeout della sonda. + Timeout del probe. - Salta la sonda di connettività (vista solo servizio). + Salta il probe di connettività (vista solo servizio). Scansiona anche i servizi a livello di sistema. - Eleva la sonda di connettività predefinita a una sonda di lettura ed esci con codice non zero quando quella sonda di lettura fallisce. Non può essere combinato con `--no-probe`. + Aggiorna il probe di connettività predefinito a un probe di lettura ed esce con codice diverso da zero quando quel probe di lettura fallisce. Non può essere combinato con `--no-probe`. - `gateway status` resta disponibile per la diagnostica anche quando la configurazione CLI locale manca o non è valida. - - `gateway status` predefinito verifica lo stato del servizio, la connessione WebSocket e la capacità di autenticazione visibile al momento dell'handshake. Non verifica le operazioni di lettura/scrittura/amministrazione. - - Le sonde diagnostiche non modificano l'autenticazione del dispositivo al primo utilizzo: riutilizzano un token dispositivo memorizzato nella cache quando esiste, ma non creano una nuova identità dispositivo CLI o un record di pairing del dispositivo di sola lettura solo per controllare lo stato. - - `gateway status` risolve le SecretRefs di autenticazione configurate per l'autenticazione della sonda quando possibile. - - Se una SecretRef di autenticazione richiesta non viene risolta in questo percorso di comando, `gateway status --json` segnala `rpc.authWarning` quando connettività/autenticazione della sonda falliscono; passa esplicitamente `--token`/`--password` oppure risolvi prima l'origine del segreto. - - Se la sonda riesce, gli avvisi per riferimenti di autenticazione non risolti vengono soppressi per evitare falsi positivi. - - Usa `--require-rpc` in script e automazione quando un servizio in ascolto non basta e hai bisogno che anche le chiamate RPC con ambito di lettura siano sane. - - `--deep` aggiunge una scansione best-effort per installazioni launchd/systemd/schtasks extra. Quando vengono rilevati più servizi simili al gateway, l'output leggibile stampa suggerimenti di pulizia e avvisa che la maggior parte delle configurazioni dovrebbe eseguire un gateway per macchina. - - L'output leggibile include il percorso risolto del file di log più l'istantanea dei percorsi/validità della configurazione CLI rispetto al servizio per aiutare a diagnosticare derive di profilo o directory di stato. + - `gateway status` predefinito verifica lo stato del servizio, la connessione WebSocket e la capability di autenticazione visibile al momento dell'handshake. Non verifica operazioni di lettura/scrittura/amministrazione. + - I probe diagnostici non modificano nulla per l'autenticazione iniziale del dispositivo: riutilizzano un token dispositivo già presente nella cache quando esiste, ma non creano una nuova identità dispositivo CLI o un record di associazione dispositivo in sola lettura solo per controllare lo stato. + - `gateway status` risolve i SecretRef di autenticazione configurati per l'autenticazione del probe quando possibile. + - Se un SecretRef di autenticazione richiesto non viene risolto in questo percorso di comando, `gateway status --json` segnala `rpc.authWarning` quando connettività/autenticazione del probe fallisce; passa `--token`/`--password` esplicitamente o risolvi prima l'origine del secret. + - Se il probe riesce, gli avvisi di auth-ref non risolti vengono soppressi per evitare falsi positivi. + - Usa `--require-rpc` negli script e nell'automazione quando un servizio in ascolto non basta e hai bisogno che anche le chiamate RPC con scope di lettura siano sane. + - `--deep` aggiunge una scansione best-effort per installazioni launchd/systemd/schtasks aggiuntive. Quando vengono rilevati più servizi simili a Gateway, l'output per utenti stampa suggerimenti di pulizia e avvisa che la maggior parte delle configurazioni dovrebbe eseguire un solo Gateway per macchina. + - L'output per utenti include il percorso del file di log risolto più uno snapshot dei percorsi/validità della configurazione CLI rispetto al servizio, per aiutare a diagnosticare divergenze di profilo o state-dir. - - - Nelle installazioni systemd su Linux, i controlli di deriva dell'autenticazione del servizio leggono sia i valori `Environment=` sia `EnvironmentFile=` dall'unità (inclusi `%h`, percorsi tra virgolette, file multipli e file opzionali con `-`). - - I controlli di deriva risolvono le SecretRefs `gateway.auth.token` usando l'ambiente runtime unito (prima l'ambiente del comando del servizio, poi il fallback dell'ambiente del processo). - - Se l'autenticazione con token non è effettivamente attiva (`gateway.auth.mode` esplicito di `password`/`none`/`trusted-proxy`, oppure modalità non impostata in cui la password può prevalere e nessun candidato token può prevalere), i controlli di deriva del token saltano la risoluzione del token di configurazione. + + - Nelle installazioni Linux systemd, i controlli di deriva dell'autenticazione del servizio leggono sia i valori `Environment=` sia `EnvironmentFile=` dall'unità (inclusi `%h`, percorsi tra virgolette, più file e file opzionali `-`). + - I controlli di deriva risolvono i SecretRef `gateway.auth.token` usando l'ambiente runtime unito (prima l'ambiente del comando di servizio, poi fallback sull'ambiente del processo). + - Se l'autenticazione con token non è effettivamente attiva (`gateway.auth.mode` esplicito pari a `password`/`none`/`trusted-proxy`, oppure modalità non impostata in cui la password può prevalere e nessun candidato token può prevalere), i controlli di deriva del token saltano la risoluzione del token di configurazione. ### `gateway probe` -`gateway probe` è il comando per "debuggare tutto". Sonda sempre: +`gateway probe` è il comando "debug tutto". Sottopone sempre a probe: -- il tuo gateway remoto configurato (se impostato), e -- localhost (loopback) **anche se il remoto è configurato**. +- il tuo Gateway remote configurato (se impostato), e +- localhost (loopback) **anche se remote è configurato**. -Se passi `--url`, quel target esplicito viene aggiunto prima di entrambi. L'output leggibile etichetta i target come: +Se passi `--url`, quella destinazione esplicita viene aggiunta prima di entrambe. L'output per utenti etichetta le destinazioni come: -- `URL (explicit)` -- `Remote (configured)` o `Remote (configured, inactive)` +- `URL (esplicito)` +- `Remote (configurato)` o `Remote (configurato, inattivo)` - `Local loopback` -Se più gateway sono raggiungibili, li stampa tutti. Più gateway sono supportati quando usi profili/porte isolati (per esempio, un bot di recupero), ma la maggior parte delle installazioni esegue comunque un solo gateway. +Se più Gateway sono raggiungibili, li stampa tutti. Più Gateway sono supportati quando usi profili/porte isolati (ad esempio, un bot di recupero), ma la maggior parte delle installazioni esegue comunque un solo Gateway. ```bash @@ -327,51 +337,51 @@ openclaw gateway probe --json - - `Reachable: yes` significa che almeno un target ha accettato una connessione WebSocket. - - `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` segnala cosa la sonda ha potuto verificare sull'autenticazione. È separato dalla raggiungibilità. - - `Read probe: ok` significa che anche le chiamate RPC di dettaglio con ambito di lettura (`health`/`status`/`system-presence`/`config.get`) sono riuscite. - - `Read probe: limited - missing scope: operator.read` significa che la connessione è riuscita ma l'RPC con ambito di lettura è limitato. Questo viene segnalato come raggiungibilità **degradata**, non come errore completo. + - `Reachable: yes` significa che almeno una destinazione ha accettato una connessione WebSocket. + - `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` segnala cosa il probe ha potuto verificare sull'autenticazione. È separato dalla raggiungibilità. + - `Read probe: ok` significa che anche le chiamate RPC di dettaglio con scope di lettura (`health`/`status`/`system-presence`/`config.get`) sono riuscite. + - `Read probe: limited - missing scope: operator.read` significa che la connessione è riuscita ma l'RPC con scope di lettura è limitato. Questo viene segnalato come raggiungibilità **degradata**, non come errore completo. - `Read probe: failed` dopo `Connect: ok` significa che il Gateway ha accettato la connessione WebSocket, ma la diagnostica di lettura successiva è andata in timeout o è fallita. Anche questa è raggiungibilità **degradata**, non un Gateway irraggiungibile. - - Come `gateway status`, la sonda riutilizza l'autenticazione dispositivo memorizzata nella cache ma non crea identità dispositivo al primo utilizzo o stato di pairing. - - Il codice di uscita è diverso da zero solo quando nessun target sondato è raggiungibile. + - Come `gateway status`, il probe riutilizza l'autenticazione dispositivo già presente nella cache ma non crea un'identità dispositivo iniziale o uno stato di associazione. + - Il codice di uscita è diverso da zero solo quando nessuna destinazione sottoposta a probe è raggiungibile. - Livello superiore: + Livello principale: - - `ok`: almeno un target è raggiungibile. - - `degraded`: almeno un target ha accettato una connessione ma non ha completato la diagnostica RPC di dettaglio completa. - - `capability`: migliore capacità osservata tra i target raggiungibili (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope` o `unknown`). - - `primaryTargetId`: miglior target da trattare come vincitore attivo in quest'ordine: URL esplicito, tunnel SSH, remoto configurato, poi local loopback. + - `ok`: almeno una destinazione è raggiungibile. + - `degraded`: almeno una destinazione ha accettato una connessione ma non ha completato la diagnostica RPC di dettaglio completa. + - `capability`: migliore capability vista tra le destinazioni raggiungibili (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope` o `unknown`). + - `primaryTargetId`: migliore destinazione da trattare come vincitore attivo in quest'ordine: URL esplicito, tunnel SSH, remote configurato, poi local loopback. - `warnings[]`: record di avviso best-effort con `code`, `message` e `targetIds` opzionali. - - `network`: suggerimenti URL local loopback/tailnet derivati dalla configurazione corrente e dalla rete dell'host. - - `discovery.timeoutMs` e `discovery.count`: budget di discovery effettivo/conteggio risultati usato per questo passaggio di sonda. + - `network`: suggerimenti di URL local loopback/tailnet derivati dalla configurazione corrente e dal networking dell'host. + - `discovery.timeoutMs` e `discovery.count`: budget/numero di risultati di discovery effettivamente usati per questo passaggio di probe. - Per target (`targets[].connect`): + Per destinazione (`targets[].connect`): - `ok`: raggiungibilità dopo connessione + classificazione degradata. - `rpcOk`: successo RPC di dettaglio completo. - - `scopeLimited`: RPC di dettaglio fallita per ambito operatore mancante. + - `scopeLimited`: RPC di dettaglio fallita per scope operatore mancante. - Per target (`targets[].auth`): + Per destinazione (`targets[].auth`): - `role`: ruolo di autenticazione riportato in `hello-ok` quando disponibile. - - `scopes`: ambiti concessi riportati in `hello-ok` quando disponibili. - - `capability`: classificazione della capacità di autenticazione esposta per quel target. + - `scopes`: scope concessi riportati in `hello-ok` quando disponibili. + - `capability`: la classificazione della capability di autenticazione esposta per quella destinazione. - - `ssh_tunnel_failed`: configurazione del tunnel SSH fallita; il comando è passato alle sonde dirette. - - `multiple_gateways`: più di un target era raggiungibile; è insolito a meno che tu non esegua intenzionalmente profili isolati, come un bot di recupero. - - `auth_secretref_unresolved`: una SecretRef di autenticazione configurata non ha potuto essere risolta per un target fallito. - - `probe_scope_limited`: connessione WebSocket riuscita, ma la sonda di lettura era limitata dalla mancanza di `operator.read`. + - `ssh_tunnel_failed`: configurazione del tunnel SSH fallita; il comando ha ripiegato sui probe diretti. + - `multiple_gateways`: più di una destinazione era raggiungibile; questo è insolito a meno che tu non esegua intenzionalmente profili isolati, come un bot di recupero. + - `auth_secretref_unresolved`: un SecretRef di autenticazione configurato non ha potuto essere risolto per una destinazione fallita. + - `probe_scope_limited`: connessione WebSocket riuscita, ma il probe di lettura è stato limitato dall'assenza di `operator.read`. -#### Remoto su SSH (parità dell'app Mac) +#### Remote via SSH (parità con l'app Mac) -La modalità "Remote over SSH" dell'app macOS usa un port-forward locale così che il gateway remoto (che può essere vincolato solo al loopback) diventi raggiungibile su `ws://127.0.0.1:`. +La modalità "Remote via SSH" dell'app macOS usa un port-forward locale affinché il Gateway remote (che potrebbe essere associato solo al loopback) diventi raggiungibile a `ws://127.0.0.1:`. Equivalente CLI: @@ -386,7 +396,7 @@ openclaw gateway probe --ssh user@gateway-host File di identità. - Seleziona il primo host gateway scoperto come target SSH dall'endpoint di discovery risolto (`local.` più il dominio wide-area configurato, se presente). I suggerimenti solo TXT vengono ignorati. + Scegli il primo host Gateway scoperto come destinazione SSH dall'endpoint di discovery risolto (`local.` più il dominio wide-area configurato, se presente). I suggerimenti solo TXT vengono ignorati. Configurazione (opzionale, usata come valori predefiniti): @@ -404,7 +414,7 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}' ``` - Stringa oggetto JSON per i params. + Stringa oggetto JSON per i parametri. URL WebSocket del Gateway. @@ -419,10 +429,10 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}' Budget di timeout. - Principalmente per RPC in stile agent che trasmettono eventi intermedi prima di un payload finale. + Principalmente per RPC in stile agente che trasmettono eventi intermedi prima di un payload finale. - Output JSON leggibile dalla macchina. + Output JSON leggibile da macchina. @@ -441,7 +451,7 @@ openclaw gateway uninstall ### Installare con un wrapper -Usa `--wrapper` quando il servizio gestito deve avviarsi tramite un altro eseguibile, per esempio uno shim di gestione segreti o un helper run-as. Il wrapper riceve i normali argomenti del Gateway ed è responsabile di eseguire infine `openclaw` o Node con quegli argomenti. +Usa `--wrapper` quando il servizio gestito deve avviarsi tramite un altro eseguibile, ad esempio uno shim di un gestore di secret o un helper run-as. Il wrapper riceve i normali argomenti del Gateway ed è responsabile di eseguire infine `openclaw` o Node con quegli argomenti. ```bash cat > ~/.local/bin/openclaw-doppler <<'EOF' @@ -455,7 +465,7 @@ openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force openclaw gateway restart ``` -Puoi anche impostare il wrapper tramite l'ambiente. `gateway install` verifica che il percorso sia un file eseguibile, scrive il wrapper in `ProgramArguments` del servizio e persiste `OPENCLAW_WRAPPER` nell'ambiente del servizio per reinstallazioni forzate, aggiornamenti e riparazioni doctor successive. +Puoi impostare il wrapper anche tramite l'ambiente. `gateway install` verifica che il percorso sia un file eseguibile, scrive il wrapper in `ProgramArguments` del servizio e persiste `OPENCLAW_WRAPPER` nell'ambiente del servizio per reinstallazioni forzate, aggiornamenti e riparazioni doctor successive. ```bash OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force @@ -478,40 +488,40 @@ openclaw gateway restart - - Usa `gateway restart` per riavviare un servizio gestito. Non concatenare `gateway stop` e `gateway start` come sostituto del riavvio; su macOS, `gateway stop` disabilita intenzionalmente il LaunchAgent prima di fermarlo. - - `gateway restart --wait 30s` sovrascrive il budget di svuotamento del riavvio configurato per quel riavvio. I numeri senza unità sono millisecondi; sono accettate unità come `s`, `m` e `h`. `--wait 0` attende indefinitamente. - - `gateway restart --force` salta lo svuotamento del lavoro attivo e riavvia immediatamente. Usalo quando un operatore ha già ispezionato i blocchi di attività elencati e vuole che il gateway torni operativo subito. + - Usa `gateway restart` per riavviare un servizio gestito. Non concatenare `gateway stop` e `gateway start` come sostituto del riavvio; su macOS, `gateway stop` disabilita intenzionalmente il LaunchAgent prima di arrestarlo. + - `gateway restart --wait 30s` sovrascrive il budget di drain del riavvio configurato per quel riavvio. I numeri senza unità sono millisecondi; sono accettate unità come `s`, `m` e `h`. `--wait 0` attende a tempo indefinito. + - `gateway restart --force` salta il drain del lavoro attivo e riavvia immediatamente. Usalo quando un operatore ha già ispezionato i blocchi di attività elencati e vuole ripristinare subito il Gateway. - I comandi del ciclo di vita accettano `--json` per lo scripting. - - - Quando l'autenticazione con token richiede un token e `gateway.auth.token` è gestito da SecretRef, `gateway install` verifica che la SecretRef sia risolvibile ma non persiste il token risolto nei metadati dell'ambiente del servizio. - - Se l'autenticazione con token richiede un token e la SecretRef del token configurata non viene risolta, l'installazione fallisce in modo chiuso invece di persistere testo in chiaro di fallback. - - Per l'autenticazione con password su `gateway run`, preferisci `OPENCLAW_GATEWAY_PASSWORD`, `--password-file` o un `gateway.auth.password` supportato da SecretRef rispetto a `--password` inline. - - In modalità di autenticazione inferita, `OPENCLAW_GATEWAY_PASSWORD` solo da shell non allenta i requisiti del token di installazione; usa configurazione durevole (`gateway.auth.password` o `env` di configurazione) quando installi un servizio gestito. - - Se sia `gateway.auth.token` sia `gateway.auth.password` sono configurati e `gateway.auth.mode` non è impostato, l'installazione viene bloccata finché la modalità non viene impostata esplicitamente. + + - Quando l'autenticazione con token richiede un token e `gateway.auth.token` è gestito da SecretRef, `gateway install` verifica che il SecretRef sia risolvibile ma non persiste il token risolto nei metadati dell'ambiente del servizio. + - Se l'autenticazione con token richiede un token e il SecretRef del token configurato non è risolto, l'installazione fallisce in modo chiuso invece di persistere testo in chiaro di fallback. + - Per l'autenticazione con password su `gateway run`, preferisci `OPENCLAW_GATEWAY_PASSWORD`, `--password-file` o un `gateway.auth.password` basato su SecretRef rispetto a `--password` inline. + - In modalità di autenticazione inferita, `OPENCLAW_GATEWAY_PASSWORD` solo shell non allenta i requisiti di token per l'installazione; usa una configurazione durevole (`gateway.auth.password` o `env` di configurazione) quando installi un servizio gestito. + - Se sono configurati sia `gateway.auth.token` sia `gateway.auth.password` e `gateway.auth.mode` non è impostato, l'installazione viene bloccata finché la modalità non viene impostata esplicitamente. -## Scoprire gateway (Bonjour) +## Scoprire Gateway (Bonjour) -`gateway discover` esegue la scansione dei beacon Gateway (`_openclaw-gw._tcp`). +`gateway discover` scansiona i beacon Gateway (`_openclaw-gw._tcp`). - DNS-SD multicast: `local.` -- DNS-SD unicast (Bonjour wide-area): scegli un dominio (esempio: `openclaw.internal.`) e configura split DNS + un server DNS; vedi [Bonjour](/it/gateway/bonjour). +- DNS-SD unicast (Bonjour ad area estesa): scegli un dominio (esempio: `openclaw.internal.`) e configura DNS split + un server DNS; consulta [Bonjour](/it/gateway/bonjour). -Solo i gateway con discovery Bonjour abilitata (predefinito) pubblicizzano il beacon. +Solo i Gateway con individuazione Bonjour abilitata (predefinita) pubblicizzano il beacon. -I record di discovery wide-area includono (TXT): +I record di individuazione ad area estesa includono (TXT): -- `role` (suggerimento sul ruolo del gateway) -- `transport` (suggerimento sul trasporto, per esempio `gateway`) +- `role` (suggerimento sul ruolo del Gateway) +- `transport` (suggerimento sul trasporto, ad es. `gateway`) - `gatewayPort` (porta WebSocket, di solito `18789`) -- `sshPort` (opzionale; i client usano `22` come target SSH predefinito quando assente) +- `sshPort` (opzionale; i client impostano come predefinita la destinazione SSH su `22` quando è assente) - `tailnetDns` (nome host MagicDNS, quando disponibile) -- `gatewayTls` / `gatewayTlsSha256` (TLS abilitato + fingerprint del certificato) -- `cliPath` (suggerimento di installazione remota scritto nella zona wide-area) +- `gatewayTls` / `gatewayTlsSha256` (TLS abilitato + impronta del certificato) +- `cliPath` (suggerimento di installazione remota scritto nella zona ad area estesa) ### `gateway discover` @@ -520,7 +530,7 @@ openclaw gateway discover ``` - Timeout per comando (browse/resolve). + Timeout per comando (esplorazione/risoluzione). Output leggibile da macchina (disabilita anche stile/spinner). @@ -534,13 +544,13 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl' ``` -- La CLI scansiona `local.` più il dominio wide-area configurato quando ne è abilitato uno. -- `wsUrl` nell'output JSON deriva dall'endpoint di servizio risolto, non da indicazioni solo TXT come `lanHost` o `tailnetDns`. -- Su mDNS `local.`, `sshPort` e `cliPath` vengono trasmessi solo quando `discovery.mdns.mode` è `full`. DNS-SD wide-area scrive comunque `cliPath`; anche lì `sshPort` resta opzionale. +- La CLI esamina `local.` più il dominio ad area estesa configurato quando ne è abilitato uno. +- `wsUrl` nell'output JSON deriva dall'endpoint del servizio risolto, non da suggerimenti solo TXT come `lanHost` o `tailnetDns`. +- Su mDNS `local.`, `sshPort` e `cliPath` vengono trasmessi solo quando `discovery.mdns.mode` è `full`. DNS-SD ad area estesa scrive comunque `cliPath`; anche lì `sshPort` resta opzionale. ## Correlati - [Riferimento CLI](/it/cli) -- [Runbook del Gateway](/it/gateway) +- [Guida operativa del Gateway](/it/gateway) diff --git a/docs/it/cli/models.md b/docs/it/cli/models.md index d8eeed17f..13dcdb539 100644 --- a/docs/it/cli/models.md +++ b/docs/it/cli/models.md @@ -1,27 +1,27 @@ --- read_when: - - Vuoi modificare i modelli predefiniti o visualizzare lo stato dell'autenticazione del provider - - Vuoi esaminare i modelli/fornitori disponibili e diagnosticare i profili di autenticazione. -summary: Riferimento CLI per `openclaw models` (status/list/set/scan, alias, meccanismi di ripiego, autenticazione) + - Vuoi modificare i modelli predefiniti o visualizzare lo stato di autenticazione del provider + - Vuoi esaminare i modelli/provider disponibili ed eseguire il debug dei profili di autenticazione +summary: Riferimento CLI per `openclaw models` (status/list/set/scan, alias, fallback, autenticazione) title: Modelli x-i18n: - generated_at: "2026-05-01T08:28:51Z" + generated_at: "2026-05-04T18:23:48Z" model: gpt-5.5 provider: openai - source_hash: 538d3e4808329737fdc044dc6e14e5c7c78052e75d8a8b3b257b1ebd821c84d1 + source_hash: dc7842f02e29aa0ac2ae88f3d42bba71f1890a58ab22d818dbee0585bc562fea source_path: cli/models.md workflow: 16 --- # `openclaw models` -Individuazione, scansione e configurazione dei modelli (modello predefinito, fallback, profili di autenticazione). +Rilevamento, scansione e configurazione dei modelli (modello predefinito, fallback, profili di autenticazione). -Correlato: +Correlati: - Provider + modelli: [Modelli](/it/providers/models) -- Concetti di selezione del modello + comando slash `/models`: [Concetto dei modelli](/it/concepts/models) -- Configurazione dell’autenticazione del provider: [Primi passi](/it/start/getting-started) +- Concetti di selezione del modello + comando slash `/models`: [Concetto di modelli](/it/concepts/models) +- Configurazione dell'autenticazione del provider: [Per iniziare](/it/start/getting-started) ## Comandi comuni @@ -32,82 +32,82 @@ openclaw models set openclaw models scan ``` -`openclaw models status` mostra il valore risolto per predefinito/fallback più una panoramica dell’autenticazione. -Quando sono disponibili snapshot dell’utilizzo del provider, la sezione di stato OAuth/chiave API include -finestre di utilizzo del provider e snapshot delle quote. -Provider attuali con finestre di utilizzo: Anthropic, GitHub Copilot, Gemini CLI, OpenAI -Codex, MiniMax, Xiaomi e z.ai. L’autenticazione per l’utilizzo proviene da hook specifici del provider -quando disponibili; altrimenti OpenClaw ripiega sulle credenziali OAuth/chiave API corrispondenti +`openclaw models status` mostra il valore predefinito risolto/i fallback risolti più una panoramica dell'autenticazione. +Quando sono disponibili snapshot dell'utilizzo dei provider, la sezione dello stato OAuth/chiave API include +finestre di utilizzo dei provider e snapshot delle quote. +Provider attuali per finestre di utilizzo: Anthropic, GitHub Copilot, Gemini CLI, OpenAI +Codex, MiniMax, Xiaomi e z.ai. L'autenticazione per l'utilizzo proviene da hook specifici del provider +quando disponibili; altrimenti OpenClaw usa come fallback le credenziali OAuth/chiave API corrispondenti da profili di autenticazione, env o configurazione. -Nell’output `--json`, `auth.providers` è la panoramica dei provider consapevole di env/config/store, -mentre `auth.oauth` è solo lo stato di salute dei profili dello store di autenticazione. -Aggiungi `--probe` per eseguire probe di autenticazione live su ciascun profilo provider configurato. -I probe sono richieste reali (possono consumare token e attivare rate limit). -Usa `--agent ` per ispezionare lo stato modello/autenticazione di un agente configurato. Se omesso, -il comando usa `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR` se impostato, altrimenti l’agente +Nell'output `--json`, `auth.providers` è la panoramica dei provider consapevole di env/configurazione/store, +mentre `auth.oauth` è solo lo stato di integrità dei profili dell'auth-store. +Aggiungi `--probe` per eseguire sonde di autenticazione live su ciascun profilo provider configurato. +Le sonde sono richieste reali (possono consumare token e attivare limiti di frequenza). +Usa `--agent ` per ispezionare lo stato di modello/autenticazione di un agente configurato. Se omesso, +il comando usa `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR` se impostato, altrimenti l'agente predefinito configurato. -Le righe dei probe possono provenire da profili di autenticazione, credenziali env o `models.json`. +Le righe delle sonde possono provenire da profili di autenticazione, credenziali env o `models.json`. Note: - `models set ` accetta `provider/model` o un alias. -- `models list` è in sola lettura: legge configurazione, profili di autenticazione, stato del catalogo esistente - e righe di catalogo possedute dal provider, ma non riscrive +- `models list` è di sola lettura: legge configurazione, profili di autenticazione, stato del catalogo + esistente e righe del catalogo di proprietà del provider, ma non riscrive `models.json`. -- La colonna `Auth` è a livello di provider e in sola lettura. È calcolata da metadati locali - dei profili di autenticazione, marcatori env, chiavi provider configurate, marcatori di provider locali, - marcatori env/profilo AWS Bedrock e metadati di autenticazione sintetica dei plugin; - non carica il runtime del provider, non legge segreti dal keychain, non chiama API - del provider e non dimostra l’esatta prontezza di esecuzione per modello. -- `models list --all --provider ` può includere righe di catalogo statiche possedute dal provider - da manifest di Plugin o metadati di catalogo provider inclusi anche quando - non ti sei ancora autenticato con quel provider. Quelle righe continuano a comparire come - non disponibili finché non viene configurata l’autenticazione corrispondente. -- `models list` mantiene reattivo il piano di controllo mentre la scoperta del catalogo provider - è lenta. Le viste predefinita e configurata ripiegano su righe modello configurate o - sintetiche dopo una breve attesa e lasciano completare la scoperta in - background. Usa `--all` quando ti serve il catalogo scoperto completo esatto e - sei disposto ad attendere la scoperta del provider. -- Un ampio `models list --all` unisce le righe di catalogo del manifest sopra le righe del registro - senza caricare hook supplementari del runtime del provider. I percorsi rapidi del manifest filtrati per provider - usano solo provider marcati `static`; i provider marcati `refreshable` - restano basati su registro/cache e aggiungono righe del manifest come supplementi, mentre - i provider marcati `runtime` restano su scoperta registro/runtime. -- `models list` mantiene distinti i metadati nativi del modello e i limiti del runtime. Nell’output tabellare, - `Ctx` mostra `contextTokens/contextWindow` quando un limite effettivo del runtime +- La colonna `Auth` è a livello di provider ed è di sola lettura. È calcolata da metadati locali + dei profili di autenticazione, marker env, chiavi provider configurate, marker di provider locali, + marker env/profilo AWS Bedrock e metadati di autenticazione sintetica dei Plugin; + non carica il runtime del provider, non legge segreti dal portachiavi, non chiama API del provider + né dimostra l'esatta prontezza di esecuzione per modello. +- `models list --all --provider ` può includere righe statiche del catalogo di proprietà del provider + da manifest dei Plugin o metadati del catalogo dei provider inclusi anche quando non ti sei ancora + autenticato con quel provider. Quelle righe vengono comunque mostrate come non disponibili + finché non viene configurata l'autenticazione corrispondente. +- `models list` mantiene reattivo il piano di controllo mentre il rilevamento del catalogo del provider + è lento. Le viste predefinita e configurata usano come fallback righe di modello configurate o + sintetiche dopo una breve attesa e lasciano terminare il rilevamento in background. + Usa `--all` quando ti serve l'esatto catalogo completo rilevato e sei disposto ad attendere + il rilevamento del provider. +- `models list --all` ampio unisce le righe di catalogo dei manifest sopra le righe del registro + senza caricare gli hook supplementari del runtime del provider. I percorsi rapidi dei manifest filtrati per provider + usano solo i provider marcati `static`; i provider marcati `refreshable` + restano basati su registro/cache e aggiungono righe dei manifest come supplementi, mentre + i provider marcati `runtime` restano sul rilevamento registro/runtime. +- `models list` mantiene distinti i metadati nativi del modello e i limiti del runtime. Nell'output tabellare, + `Ctx` mostra `contextTokens/contextWindow` quando un limite di runtime effettivo differisce dalla finestra di contesto nativa; le righe JSON includono `contextTokens` - quando un provider espone quel limite. + quando un provider espone tale limite. - `models list --provider ` filtra per id provider, come `moonshot` o - `openai-codex`. Non accetta etichette visualizzate dai selettori interattivi dei provider, + `openai-codex`. Non accetta le etichette visualizzate dai selettori interattivi dei provider, come `Moonshot AI`. -- I riferimenti ai modelli vengono analizzati dividendo sulla **prima** `/`. Se l’ID del modello include `/` (stile OpenRouter), includi il prefisso del provider (esempio: `openrouter/moonshotai/kimi-k2`). -- Se ometti il provider, OpenClaw risolve prima l’input come alias, poi - come corrispondenza univoca di provider configurato per quell’esatto id modello, e solo dopo - ripiega sul provider predefinito configurato con un avviso di deprecazione. +- I riferimenti ai modelli vengono analizzati dividendo alla **prima** `/`. Se l'ID modello include `/` (stile OpenRouter), includi il prefisso del provider (esempio: `openrouter/moonshotai/kimi-k2`). +- Se ometti il provider, OpenClaw risolve prima l'input come alias, poi + come corrispondenza unica del provider configurato per quell'esatto id modello, e solo allora + usa come fallback il provider predefinito configurato con un avviso di deprecazione. Se quel provider non espone più il modello predefinito configurato, OpenClaw - ripiega sul primo provider/modello configurato invece di mostrare un - predefinito di provider rimosso obsoleto. -- `models status` può mostrare `marker()` nell’output di autenticazione per segnaposto non segreti (per esempio `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) invece di mascherarli come segreti. + usa come fallback il primo provider/modello configurato invece di mostrare un + predefinito obsoleto di un provider rimosso. +- `models status` può mostrare `marker()` nell'output di autenticazione per segnaposto non segreti (per esempio `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) invece di mascherarli come segreti. ### Scansione dei modelli `models scan` legge il catalogo pubblico `:free` di OpenRouter e classifica i candidati per -l’uso come fallback. Il catalogo stesso è pubblico, quindi le scansioni solo metadati non richiedono +l'uso come fallback. Il catalogo stesso è pubblico, quindi le scansioni solo metadati non richiedono una chiave OpenRouter. -Per impostazione predefinita OpenClaw prova a verificare il supporto per strumenti e immagini con chiamate live ai modelli. -Se non è configurata alcuna chiave OpenRouter, il comando ripiega sull’output solo metadati +Per impostazione predefinita OpenClaw prova a sondare il supporto per strumenti e immagini con chiamate live ai modelli. +Se non è configurata alcuna chiave OpenRouter, il comando ripiega su output solo metadati e spiega che i modelli `:free` richiedono comunque `OPENROUTER_API_KEY` per -probe e inferenza. +sonde e inferenza. Opzioni: -- `--no-probe` (solo metadati; nessuna ricerca di config/segreti) +- `--no-probe` (solo metadati; nessuna ricerca di configurazione/segreti) - `--min-params ` - `--max-age-days ` - `--provider ` - `--max-candidates ` -- `--timeout ` (richiesta al catalogo e timeout per probe) +- `--timeout ` (richiesta del catalogo e timeout per sonda) - `--concurrency ` - `--yes` - `--no-input` @@ -115,7 +115,7 @@ Opzioni: - `--set-image` - `--json` -`--set-default` e `--set-image` richiedono probe live; i risultati della scansione +`--set-default` e `--set-image` richiedono sonde live; i risultati delle scansioni solo metadati sono informativi e non vengono applicati alla configurazione. ### Stato dei modelli @@ -124,20 +124,20 @@ Opzioni: - `--json` - `--plain` -- `--check` (uscita 1=scaduto/mancante, 2=in scadenza) -- `--probe` (probe live dei profili di autenticazione configurati) -- `--probe-provider ` (probe di un provider) +- `--check` (codici di uscita 1=scaduto/mancante, 2=in scadenza) +- `--probe` (sonda live dei profili di autenticazione configurati) +- `--probe-provider ` (sonda un provider) - `--probe-profile ` (id profilo ripetuti o separati da virgole) - `--probe-timeout ` - `--probe-concurrency ` - `--probe-max-tokens ` -- `--agent ` (id agente configurato; sovrascrive `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`) +- `--agent ` (id agente configurato; sostituisce `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`) -`--json` mantiene stdout riservato al payload JSON. I diagnostici di profili di autenticazione, provider -e avvio vengono indirizzati a stderr così gli script possono inoltrare stdout direttamente +`--json` mantiene stdout riservato al payload JSON. Le diagnostiche di profilo di autenticazione, provider +e avvio vengono indirizzate a stderr così gli script possono collegare stdout direttamente a strumenti come `jq`. -Categorie di stato dei probe: +Bucket dello stato della sonda: - `ok` - `auth` @@ -148,15 +148,15 @@ Categorie di stato dei probe: - `unknown` - `no_model` -Casi di dettaglio/codice motivo dei probe da aspettarsi: +Casi di dettaglio/codice motivo della sonda da aspettarsi: -- `excluded_by_auth_order`: esiste un profilo memorizzato, ma l’esplicito - `auth.order.` lo ha omesso, quindi il probe segnala l’esclusione invece di +- `excluded_by_auth_order`: esiste un profilo salvato, ma un + `auth.order.` esplicito lo ha omesso, quindi la sonda segnala l'esclusione invece di provarlo. - `missing_credential`, `invalid_expires`, `expired`, `unresolved_ref`: il profilo è presente ma non è idoneo/risolvibile. -- `no_model`: l’autenticazione del provider esiste, ma OpenClaw non è riuscito a risolvere un - modello candidato verificabile per quel provider. +- `no_model`: l'autenticazione del provider esiste, ma OpenClaw non è riuscito a risolvere un candidato + modello sondabile per quel provider. ## Alias + fallback @@ -169,45 +169,52 @@ openclaw models fallbacks list ```bash openclaw models auth add +openclaw models auth list [--provider ] [--json] openclaw models auth login --provider openclaw models auth setup-token --provider openclaw models auth paste-token ``` -`models auth add` è l’helper interattivo di autenticazione. Può avviare un flusso di autenticazione del provider -(OAuth/chiave API) o guidarti nell’incollare manualmente un token, a seconda del -provider scelto. +`models auth add` è l'helper interattivo per l'autenticazione. Può avviare un flusso di autenticazione del provider +(OAuth/chiave API) o guidarti nell'incollare manualmente un token, a seconda del +provider che scegli. + +`models auth list` elenca i profili di autenticazione salvati per l'agente selezionato senza +stampare token, chiavi API o materiale segreto OAuth. Usa `--provider ` per +filtrare su un provider, come `openai-codex`, e `--json` per gli script. `models auth login` esegue il flusso di autenticazione di un Plugin provider (OAuth/chiave API). Usa `openclaw plugins list` per vedere quali provider sono installati. -Usa `openclaw models auth --agent ` per scrivere i risultati dell’autenticazione in uno -store agente configurato specifico. Il flag padre `--agent` è rispettato da -`add`, `login`, `setup-token`, `paste-token` e `login-github-copilot`. +Usa `openclaw models auth --agent ` per scrivere i risultati di autenticazione in uno +store di agente configurato specifico. Il flag padre `--agent` è rispettato da +`add`, `list`, `login`, `setup-token`, `paste-token` e +`login-github-copilot`. Esempi: ```bash openclaw models auth login --provider openai-codex --set-default +openclaw models auth list --provider openai-codex ``` Note: - `setup-token` e `paste-token` restano comandi token generici per i provider che espongono metodi di autenticazione tramite token. -- `setup-token` richiede un TTY interattivo ed esegue il metodo di autenticazione tramite token - del provider (usando per impostazione predefinita il metodo `setup-token` di quel provider quando ne espone +- `setup-token` richiede un TTY interattivo ed esegue il metodo di autenticazione tramite token del provider + (per impostazione predefinita il metodo `setup-token` di quel provider quando ne espone uno). -- `paste-token` accetta una stringa token generata altrove o da automazione. +- `paste-token` accetta una stringa token generata altrove o dall'automazione. - `paste-token` richiede `--provider`, chiede il valore del token e lo scrive - nell’id profilo predefinito `:manual` a meno che tu non passi + nell'id profilo predefinito `:manual` a meno che tu non passi `--profile-id`. -- `paste-token --expires-in ` memorizza una scadenza assoluta del token da una +- `paste-token --expires-in ` salva una scadenza assoluta del token da una durata relativa come `365d` o `12h`. -- Nota Anthropic: lo staff di Anthropic ci ha detto che l’uso di Claude CLI in stile OpenClaw è di nuovo consentito, quindi OpenClaw tratta il riuso di Claude CLI e l’uso di `claude -p` come autorizzati per questa integrazione, a meno che Anthropic non pubblichi una nuova policy. -- Anthropic `setup-token` / `paste-token` restano disponibili come percorso token OpenClaw supportato, ma OpenClaw ora preferisce il riuso di Claude CLI e `claude -p` quando disponibili. +- Nota su Anthropic: lo staff di Anthropic ci ha detto che l'uso in stile Claude CLI di OpenClaw è di nuovo consentito, quindi OpenClaw considera il riuso di Claude CLI e l'uso di `claude -p` come autorizzati per questa integrazione, salvo pubblicazione di una nuova policy da parte di Anthropic. +- Anthropic `setup-token` / `paste-token` restano disponibili come percorso token OpenClaw supportato, ma ora OpenClaw preferisce il riuso di Claude CLI e `claude -p` quando disponibili. -## Correlato +## Correlati - [Riferimento CLI](/it/cli) - [Selezione del modello](/it/concepts/model-providers) -- [Failover dei modelli](/it/concepts/model-failover) +- [Failover del modello](/it/concepts/model-failover) diff --git a/docs/it/cli/proxy.md b/docs/it/cli/proxy.md index 0f5bd638b..02c01a2e5 100644 --- a/docs/it/cli/proxy.md +++ b/docs/it/cli/proxy.md @@ -1,37 +1,36 @@ --- read_when: - - È necessario verificare il routing del proxy gestito dall'operatore prima della distribuzione + - È necessario convalidare il routing del proxy gestito dall’operatore prima della distribuzione - È necessario acquisire localmente il traffico di trasporto di OpenClaw per il debug - Vuoi ispezionare le sessioni del proxy di debug, i blob o i preset di query integrati summary: Riferimento CLI per `openclaw proxy`, inclusa la convalida del proxy gestito dall'operatore e l'ispettore di acquisizione del proxy di debug locale title: Proxy x-i18n: - generated_at: "2026-05-04T07:02:55Z" + generated_at: "2026-05-04T18:23:59Z" model: gpt-5.5 provider: openai - source_hash: 9589bedafb97c31bcb6536a04307cd0c6550e1f307693bd4401785d79f34a1eb + source_hash: 092c4e946dcab5e78e37d6fc77bb067b7a649368f8571fa127e462a85fa14ce5 source_path: cli/proxy.md workflow: 16 --- # `openclaw proxy` -Convalida l'instradamento del proxy gestito dall'operatore, oppure esegui il proxy -di debug esplicito locale e ispeziona il traffico acquisito. +Convalida l'instradamento proxy gestito dall'operatore oppure esegue il proxy di debug esplicito locale +e ispeziona il traffico acquisito. -Usa `validate` per eseguire una verifica preliminare di un proxy forward gestito -dall'operatore prima di abilitare l'instradamento proxy di OpenClaw. Gli altri -comandi sono strumenti di debug per indagini a livello di trasporto: possono -avviare un proxy locale, eseguire un comando figlio con l'acquisizione abilitata, -elencare le sessioni di acquisizione, interrogare pattern di traffico comuni, -leggere blob acquisiti ed eliminare i dati di acquisizione locali. +Usa `validate` per eseguire il preflight di un proxy di inoltro gestito dall'operatore prima di abilitare +l'instradamento proxy di OpenClaw. Gli altri comandi sono strumenti di debug per +indagini a livello di trasporto: possono avviare un proxy locale, eseguire un comando figlio +con l'acquisizione abilitata, elencare le sessioni di acquisizione, interrogare pattern di traffico comuni, leggere +blob acquisiti ed eliminare i dati di acquisizione locali. ## Comandi ```bash openclaw proxy start [--host ] [--port ] openclaw proxy run [--host ] [--port ] -- -openclaw proxy validate [--json] [--proxy-url ] [--allowed-url ] [--denied-url ] [--timeout-ms ] +openclaw proxy validate [--json] [--proxy-url ] [--allowed-url ] [--denied-url ] [--apns-reachable] [--apns-authority ] [--timeout-ms ] openclaw proxy coverage openclaw proxy sessions [--limit ] openclaw proxy query --preset [--session ] @@ -41,27 +40,29 @@ openclaw proxy purge ## Convalida -`openclaw proxy validate` controlla l'URL effettivo del proxy gestito -dall'operatore da `--proxy-url`, dalla configurazione o da `OPENCLAW_PROXY_URL`. -Segnala un problema di configurazione quando nessun proxy è abilitato e -configurato; usa `--proxy-url` per una verifica preliminare una tantum prima di -modificare la configurazione. Per impostazione predefinita verifica che una -destinazione pubblica riesca attraverso il proxy e che il proxy non possa -raggiungere un canary temporaneo di loopback. Le destinazioni negate -personalizzate sono fail-closed: le risposte HTTP e gli errori di trasporto -ambigui falliscono entrambi, a meno che tu non possa verificare separatamente un -segnale di negazione specifico della distribuzione. +`openclaw proxy validate` controlla l'URL proxy effettivo gestito dall'operatore da +`--proxy-url`, dalla configurazione o da `OPENCLAW_PROXY_URL`. Segnala un problema di configurazione quando +nessun proxy è abilitato e configurato; usa `--proxy-url` per un preflight una tantum +prima di modificare la configurazione. Per impostazione predefinita verifica che una destinazione pubblica abbia esito positivo +attraverso il proxy e che il proxy non possa raggiungere un canary di loopback temporaneo. +Le destinazioni negate personalizzate sono fail-closed: le risposte HTTP e gli errori di trasporto +ambigui falliscono entrambi, a meno che tu possa verificare separatamente un segnale di negazione +specifico della distribuzione. Aggiungi `--apns-reachable` per aprire anche un tunnel +CONNECT HTTP/2 APNs attraverso il proxy e confermare che APNs sandbox risponda; il probe usa un +token provider intenzionalmente non valido, quindi una risposta APNs `403 InvalidProviderToken` +è un segnale di raggiungibilità riuscito. Opzioni: -- `--json`: stampa JSON leggibile dalla macchina. -- `--proxy-url `: convalida questo URL del proxy invece della configurazione o dell'ambiente. +- `--json`: stampa JSON leggibile da macchina. +- `--proxy-url `: convalida questo URL proxy invece della configurazione o dell'ambiente. - `--allowed-url `: aggiunge una destinazione che dovrebbe riuscire attraverso il proxy. Ripeti per controllare più destinazioni. - `--denied-url `: aggiunge una destinazione che dovrebbe essere bloccata dal proxy. Ripeti per controllare più destinazioni. +- `--apns-reachable`: verifica anche che APNs sandbox HTTP/2 sia raggiungibile attraverso il proxy. +- `--apns-authority `: autorità APNs da sondare con `--apns-reachable` (`https://api.sandbox.push.apple.com` per impostazione predefinita; la produzione è `https://api.push.apple.com`). - `--timeout-ms `: timeout per richiesta in millisecondi. -Vedi [Proxy di rete](/it/security/network-proxy) per indicazioni sulla distribuzione -e sulla semantica della negazione. +Consulta [Proxy di rete](/it/security/network-proxy) per indicazioni sulla distribuzione e semantica di negazione. ## Preset di query @@ -76,14 +77,14 @@ e sulla semantica della negazione. ## Note -- `start` usa `127.0.0.1` per impostazione predefinita, a meno che `--host` non sia impostato. +- `start` usa `127.0.0.1` per impostazione predefinita, a meno che `--host` sia impostato. - `run` avvia un proxy di debug locale e poi esegue il comando dopo `--`. - L'inoltro upstream diretto del proxy di debug apre socket upstream per la diagnostica. Quando la modalità proxy gestita di OpenClaw è attiva, l'inoltro diretto per le richieste proxy e i tunnel CONNECT è disabilitato per impostazione predefinita; imposta `OPENCLAW_DEBUG_PROXY_ALLOW_DIRECT_CONNECT_WITH_MANAGED_PROXY=1` solo per diagnostica locale approvata. -- `validate` termina con codice 1 quando la configurazione del proxy o i controlli delle destinazioni falliscono. +- `validate` esce con codice 1 quando la configurazione proxy o i controlli delle destinazioni falliscono. - Le acquisizioni sono dati di debug locali; usa `openclaw proxy purge` quando hai finito. ## Correlati - [Riferimento CLI](/it/cli) - [Proxy di rete](/it/security/network-proxy) -- [Autenticazione del proxy attendibile](/it/gateway/trusted-proxy-auth) +- [Autenticazione proxy attendibile](/it/gateway/trusted-proxy-auth) diff --git a/docs/it/gateway/cli-backends.md b/docs/it/gateway/cli-backends.md index c92c2d7c5..bcc19dda8 100644 --- a/docs/it/gateway/cli-backends.md +++ b/docs/it/gateway/cli-backends.md @@ -1,36 +1,36 @@ --- read_when: - - Vuoi una soluzione di fallback affidabile quando i provider API non funzionano - - Stai eseguendo Codex CLI o altre CLI di IA locali e vuoi riutilizzarle - - Vuoi comprendere il ponte di ritorno locale MCP per l’accesso agli strumenti del backend della CLI -summary: 'Backend CLI: fallback della CLI di IA locale con bridge opzionale per strumenti MCP' + - Vuoi una soluzione di ripiego affidabile quando i fornitori di API non funzionano + - Stai eseguendo Codex CLI o altre CLI AI locali e vuoi riutilizzarle + - Vuoi comprendere il bridge di loopback MCP per l'accesso agli strumenti del backend CLI +summary: 'Backend CLI: fallback CLI di IA locale con bridge opzionale per strumenti MCP' title: Backend della CLI x-i18n: - generated_at: "2026-05-02T20:44:59Z" + generated_at: "2026-05-04T18:24:01Z" model: gpt-5.5 provider: openai - source_hash: f343469d6a42dc6146196355dc2ba3feed045515c3d8446941b90971aadc9a16 + source_hash: 55534c48c5e226857b9320fd369416583e5c2efc80eabd4746f939afdd027dc1 source_path: gateway/cli-backends.md workflow: 16 --- -OpenClaw può eseguire **CLI AI locali** come **fallback solo testuale** quando i provider API sono inattivi, -soggetti a limiti di frequenza o temporaneamente instabili. Questo approccio è intenzionalmente conservativo: +OpenClaw può eseguire **CLI AI locali** come **fallback solo testo** quando i provider API non sono disponibili, +sono soggetti a limiti di frequenza o hanno temporaneamente comportamenti anomali. Questa scelta è intenzionalmente conservativa: - **Gli strumenti OpenClaw non vengono iniettati direttamente**, ma i backend con `bundleMcp: true` - possono ricevere strumenti del gateway tramite un bridge MCP di loopback. + possono ricevere gli strumenti del Gateway tramite un bridge MCP in local loopback. - **Streaming JSONL** per le CLI che lo supportano. - **Le sessioni sono supportate** (quindi i turni successivi restano coerenti). -- **Le immagini possono essere inoltrate** se la CLI accetta percorsi di immagini. +- **Le immagini possono essere passate** se la CLI accetta percorsi di immagini. -Questo è progettato come una **rete di sicurezza** più che come percorso principale. Usalo quando vuoi -risposte testuali che "funzionano sempre" senza dipendere da API esterne. +È progettato come **rete di sicurezza** più che come percorso principale. Usalo quando vuoi +risposte di testo che “funzionano sempre” senza dipendere da API esterne. Se vuoi un runtime harness completo con controlli di sessione ACP, attività in background, -associazione a thread/conversazione e sessioni di coding esterne persistenti, usa invece -[Agenti ACP](/it/tools/acp-agents). I backend CLI non sono ACP. +associazione a thread/conversazioni e sessioni di codifica esterne persistenti, usa invece +[agenti ACP](/it/tools/acp-agents). I backend CLI non sono ACP. -## Avvio rapido per principianti +## Avvio rapido adatto ai principianti Puoi usare Codex CLI **senza alcuna configurazione** (il plugin OpenAI incluso registra un backend predefinito): @@ -39,7 +39,7 @@ registra un backend predefinito): openclaw agent --message "hi" --model codex-cli/gpt-5.5 ``` -Se il tuo gateway viene eseguito sotto launchd/systemd e PATH è minimale, aggiungi solo il +Se il tuo Gateway viene eseguito con launchd/systemd e PATH è minimo, aggiungi solo il percorso del comando: ```json5 @@ -56,10 +56,10 @@ percorso del comando: } ``` -È tutto. Non servono chiavi né configurazione di autenticazione extra oltre alla CLI stessa. +Tutto qui. Nessuna chiave, nessuna configurazione di autenticazione aggiuntiva necessaria oltre alla CLI stessa. Se usi un backend CLI incluso come **provider di messaggi principale** su un -host gateway, OpenClaw ora carica automaticamente il plugin incluso proprietario quando la tua configurazione +host Gateway, OpenClaw ora carica automaticamente il plugin incluso proprietario quando la tua configurazione fa riferimento esplicitamente a quel backend in un riferimento modello o sotto `agents.defaults.cliBackends`. @@ -92,14 +92,14 @@ Note: ## Panoramica della configurazione -Tutti i backend CLI si trovano sotto: +Tutti i backend CLI vivono sotto: ``` agents.defaults.cliBackends ``` -Ogni voce ha come chiave un **id provider** (ad es. `codex-cli`, `my-cli`). -L'id provider diventa la parte sinistra del tuo riferimento modello: +Ogni voce usa come chiave un **id provider** (ad esempio `codex-cli`, `my-cli`). +L’id provider diventa il lato sinistro del tuo riferimento modello: ``` / @@ -148,45 +148,51 @@ L'id provider diventa la parte sinistra del tuo riferimento modello: ## Come funziona 1. **Seleziona un backend** in base al prefisso del provider (`codex-cli/...`). -2. **Costruisce un prompt di sistema** usando lo stesso prompt OpenClaw + contesto workspace. -3. **Esegue la CLI** con un id sessione (se supportato) così la cronologia resta coerente. - Il backend `claude-cli` incluso mantiene vivo un processo stdio Claude per ogni - sessione OpenClaw e invia i turni successivi tramite stdin stream-json. -4. **Analizza l'output** (JSON o testo semplice) e restituisce il testo finale. +2. **Costruisce un prompt di sistema** usando lo stesso prompt OpenClaw e lo stesso contesto dell’area di lavoro. +3. **Esegue la CLI** con un id sessione (se supportato) in modo che la cronologia resti coerente. + Il backend `claude-cli` incluso mantiene attivo un processo stdio Claude per ogni + sessione OpenClaw e invia i turni successivi su stdin stream-json. +4. **Analizza l’output** (JSON o testo semplice) e restituisce il testo finale. 5. **Persiste gli id sessione** per backend, così i turni successivi riutilizzano la stessa sessione CLI. Il backend Anthropic `claude-cli` incluso è di nuovo supportato. Il personale Anthropic -ci ha detto che l'uso di Claude CLI in stile OpenClaw è di nuovo consentito, quindi OpenClaw tratta -l'uso di `claude -p` come autorizzato per questa integrazione salvo che Anthropic pubblichi +ci ha detto che l’uso di Claude CLI in stile OpenClaw è di nuovo consentito, quindi OpenClaw tratta +l’uso di `claude -p` come autorizzato per questa integrazione, salvo che Anthropic pubblichi una nuova policy. Il backend OpenAI `codex-cli` incluso passa il prompt di sistema di OpenClaw tramite -l'override di configurazione `model_instructions_file` di Codex (`-c +l’override di configurazione `model_instructions_file` di Codex (`-c model_instructions_file="..."`). Codex non espone un flag in stile Claude `--append-system-prompt`, quindi OpenClaw scrive il prompt assemblato in un file temporaneo per ogni nuova sessione Codex CLI. -Il backend Anthropic `claude-cli` incluso riceve lo snapshot delle skill OpenClaw -in due modi: il catalogo compatto delle skill OpenClaw nel prompt di sistema aggiunto, e +Il backend Anthropic `claude-cli` incluso riceve lo snapshot delle Skills OpenClaw +in due modi: il catalogo compatto delle Skills OpenClaw nel prompt di sistema aggiunto e un plugin Claude Code temporaneo passato con `--plugin-dir`. Il plugin contiene -solo le skill idonee per quell'agente/sessione, quindi il resolver di skill nativo di Claude Code -vede lo stesso insieme filtrato che OpenClaw altrimenti pubblicherebbe nel -prompt. Gli override di env/chiave API delle skill sono ancora applicati da OpenClaw -all'ambiente del processo figlio per l'esecuzione. +solo le Skills idonee per quell’agente/sessione, quindi il resolver nativo delle skill di Claude Code +vede lo stesso insieme filtrato che OpenClaw altrimenti pubblicizzerebbe nel +prompt. Gli override env/chiave API delle skill vengono comunque applicati da OpenClaw +all’ambiente del processo figlio per l’esecuzione. -Claude CLI ha anche una propria modalità di permessi non interattiva. OpenClaw la mappa +Claude CLI ha anche una propria modalità di autorizzazione non interattiva. OpenClaw la mappa alla policy exec esistente invece di aggiungere configurazione specifica per Claude: quando la policy exec effettiva richiesta è YOLO (`tools.exec.security: "full"` e `tools.exec.ask: "off"`), OpenClaw aggiunge `--permission-mode bypassPermissions`. Le impostazioni per agente `agents.list[].tools.exec` sovrascrivono `tools.exec` globale per -quell'agente. Per forzare una modalità Claude diversa, imposta argomenti backend raw espliciti +quell’agente. Per forzare una modalità Claude diversa, imposta argomenti backend raw espliciti come `--permission-mode default` o `--permission-mode acceptEdits` sotto -`agents.defaults.cliBackends.claude-cli.args` e i corrispondenti `resumeArgs`. +`agents.defaults.cliBackends.claude-cli.args` e `resumeArgs` corrispondenti. + +Il backend Anthropic `claude-cli` incluso mappa anche i livelli OpenClaw `/think` +al flag nativo `--effort` di Claude Code per i livelli non disattivati. `minimal` e +`low` vengono mappati a `low`, `adaptive` e `medium` a `medium`, e `high`, +`xhigh` e `max` vengono mappati direttamente. Gli altri backend CLI hanno bisogno che il plugin proprietario +dichiari un mapper argv equivalente prima che `/think` possa influenzare la CLI generata. Prima che OpenClaw possa usare il backend `claude-cli` incluso, Claude Code stesso -deve già aver effettuato l'accesso sullo stesso host: +deve già aver eseguito l’accesso sullo stesso host: ```bash claude auth login @@ -199,60 +205,60 @@ non è già in `PATH`. ## Sessioni -- Se la CLI supporta le sessioni, imposta `sessionArg` (ad es. `--session-id`) o - `sessionArgs` (placeholder `{sessionId}`) quando l'ID deve essere inserito +- Se la CLI supporta le sessioni, imposta `sessionArg` (ad esempio `--session-id`) o + `sessionArgs` (placeholder `{sessionId}`) quando l’ID deve essere inserito in più flag. -- Se la CLI usa un **sottocomando resume** con flag diversi, imposta - `resumeArgs` (sostituisce `args` durante il ripristino) e facoltativamente `resumeOutput` - (per ripristini non JSON). +- Se la CLI usa un **sottocomando di ripresa** con flag diversi, imposta + `resumeArgs` (sostituisce `args` quando si riprende) e facoltativamente `resumeOutput` + (per riprese non JSON). - `sessionMode`: - `always`: invia sempre un id sessione (nuovo UUID se non ne è memorizzato nessuno). - `existing`: invia un id sessione solo se ne era già stato memorizzato uno. - - `none`: non invia mai un id sessione. -- `claude-cli` usa per impostazione predefinita `liveSession: "claude-stdio"`, `output: "jsonl"`, + - `none`: non inviare mai un id sessione. +- `claude-cli` usa come default `liveSession: "claude-stdio"`, `output: "jsonl"`, e `input: "stdin"` così i turni successivi riutilizzano il processo Claude live mentre - è attivo. Warm stdio è ora il valore predefinito, anche per configurazioni personalizzate + è attivo. Lo stdio caldo ora è l’impostazione predefinita, anche per configurazioni personalizzate che omettono i campi di trasporto. Se il Gateway si riavvia o il processo inattivo - termina, OpenClaw riprende dall'id sessione Claude memorizzato. Gli id sessione - memorizzati sono verificati rispetto a una trascrizione di progetto esistente e leggibile prima del - ripristino, quindi le associazioni fantasma vengono cancellate con `reason=transcript-missing` + termina, OpenClaw riprende dall’id sessione Claude memorizzato. Gli id sessione + memorizzati vengono verificati rispetto a una trascrizione di progetto leggibile esistente prima della + ripresa, quindi i binding fantasma vengono cancellati con `reason=transcript-missing` invece di avviare silenziosamente una nuova sessione Claude CLI sotto `--resume`. -- Le sessioni live Claude mantengono guardie delimitate per l'output JSONL. I valori predefiniti consentono fino a - 8 MiB e 20.000 righe JSONL raw per turno. I turni Claude con molti strumenti possono aumentarli +- Le sessioni live Claude mantengono guardrail limitati sull’output JSONL. I default consentono fino a + 8 MiB e 20.000 righe JSONL raw per turno. I turni Claude ricchi di strumenti possono aumentarli per backend con `agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars` e `maxTurnLines`; OpenClaw limita queste impostazioni a 64 MiB e 100.000 righe. -- Le sessioni CLI memorizzate sono continuità di proprietà del provider. Il reset giornaliero implicito della sessione +- Le sessioni CLI memorizzate sono continuità posseduta dal provider. Il reset giornaliero implicito della sessione non le interrompe; `/reset` e le policy esplicite `session.reset` lo fanno ancora. Note sulla serializzazione: -- `serialize: true` mantiene ordinate le esecuzioni sulla stessa corsia. +- `serialize: true` mantiene ordinate le esecuzioni nella stessa corsia. - La maggior parte delle CLI serializza su una corsia provider. -- OpenClaw abbandona il riutilizzo della sessione CLI memorizzata quando cambia l'identità di autenticazione selezionata, - incluso un id profilo auth modificato, chiave API statica, token statico o identità - account OAuth quando la CLI ne espone una. La rotazione dei token OAuth di accesso e refresh +- OpenClaw scarta il riutilizzo della sessione CLI memorizzata quando l’identità di autenticazione selezionata cambia, + inclusi un id profilo di autenticazione modificato, una chiave API statica, un token statico o l’identità + dell’account OAuth quando la CLI ne espone una. La rotazione dei token di accesso e refresh OAuth non interrompe la sessione CLI memorizzata. Se una CLI non espone un - id account OAuth stabile, OpenClaw lascia che quella CLI applichi i permessi di resume. + id account OAuth stabile, OpenClaw lascia che quella CLI applichi le autorizzazioni di ripresa. -## Prelude di fallback dalle sessioni claude-cli +## Preambolo di fallback dalle sessioni claude-cli Quando un tentativo `claude-cli` passa a un candidato non CLI in [`agents.defaults.model.fallbacks`](/it/concepts/model-failover), OpenClaw inizializza -il tentativo successivo con un prelude di contesto ricavato dalla trascrizione JSONL locale di Claude Code +il tentativo successivo con un preambolo di contesto raccolto dalla trascrizione JSONL locale di Claude Code in `~/.claude/projects/`. Senza questo seed, il provider di fallback -partirebbe da zero perché la trascrizione di sessione propria di OpenClaw è vuota +partirebbe a freddo perché la trascrizione della sessione di OpenClaw è vuota per le esecuzioni `claude-cli`. -- Il prelude preferisce l'ultimo riepilogo `/compact` o marker `compact_boundary`, - poi aggiunge i turni post-boundary più recenti fino a un budget di caratteri. - I turni pre-boundary vengono scartati perché il riepilogo li rappresenta già. -- I blocchi di strumenti sono coalescenti in suggerimenti compatti `(tool call: name)` e - `(tool result: …)` per mantenere onesto il budget del prompt. Il riepilogo è - etichettato `(truncated)` se supera il limite. -- I fallback dallo stesso provider `claude-cli` a `claude-cli` si basano sul - `--resume` proprio di Claude e saltano il prelude. +- Il preambolo preferisce l’ultimo riepilogo `/compact` o marker `compact_boundary`, + poi aggiunge i turni più recenti dopo il boundary fino a un budget di caratteri. + I turni precedenti al boundary vengono scartati perché il riepilogo li rappresenta già. +- I blocchi di strumenti vengono uniti in suggerimenti compatti `(tool call: name)` e + `(tool result: …)` per mantenere onesto il budget del prompt. Il riepilogo viene + etichettato `(truncated)` se eccede. +- I fallback da `claude-cli` a `claude-cli` dello stesso provider si affidano al + `--resume` di Claude e saltano il preambolo. - Il seed riutilizza la validazione esistente del percorso file di sessione Claude, quindi percorsi arbitrari non possono essere letti. @@ -267,27 +273,27 @@ imageMode: "repeat" OpenClaw scriverà le immagini base64 in file temporanei. Se `imageArg` è impostato, quei percorsi vengono passati come argomenti CLI. Se `imageArg` manca, OpenClaw aggiunge i -percorsi dei file al prompt (path injection), il che è sufficiente per le CLI che caricano -automaticamente file locali da percorsi in testo semplice. +percorsi dei file al prompt (iniezione del percorso), il che è sufficiente per le CLI che caricano automaticamente +file locali da percorsi in testo semplice. ## Input / output -- `output: "json"` (predefinito) prova ad analizzare JSON ed estrarre testo + id sessione. -- Per l'output JSON di Gemini CLI, OpenClaw legge il testo della risposta da `response` e - l'utilizzo da `stats` quando `usage` manca o è vuoto. -- `output: "jsonl"` analizza stream JSONL (per esempio Codex CLI `--json`) ed estrae il messaggio finale dell'agente più gli +- `output: "json"` (default) prova ad analizzare JSON ed estrarre testo + id sessione. +- Per l’output JSON di Gemini CLI, OpenClaw legge il testo della risposta da `response` e + l’uso da `stats` quando `usage` manca o è vuoto. +- `output: "jsonl"` analizza stream JSONL (ad esempio Codex CLI `--json`) ed estrae il messaggio finale dell’agente più gli identificatori di sessione quando presenti. - `output: "text"` tratta stdout come risposta finale. Modalità di input: -- `input: "arg"` (predefinito) passa il prompt come ultimo argomento CLI. +- `input: "arg"` (default) passa il prompt come ultimo argomento CLI. - `input: "stdin"` invia il prompt tramite stdin. - Se il prompt è molto lungo e `maxPromptArgChars` è impostato, viene usato stdin. -## Predefiniti (di proprietà del plugin) +## Default (di proprietà del plugin) -Il plugin OpenAI incluso registra anche un predefinito per `codex-cli`: +Il plugin OpenAI incluso registra anche un default per `codex-cli`: - `command: "codex"` - `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]` @@ -298,7 +304,7 @@ Il plugin OpenAI incluso registra anche un predefinito per `codex-cli`: - `imageArg: "--image"` - `sessionMode: "existing"` -Il plugin Google incluso registra anche un predefinito per `google-gemini-cli`: +Il plugin Google incluso registra anche un default per `google-gemini-cli`: - `command: "gemini"` - `args: ["--output-format", "json", "--prompt", "{prompt}"]` @@ -313,27 +319,27 @@ Prerequisito: la Gemini CLI locale deve essere installata e disponibile come `gemini` in `PATH` (`brew install gemini-cli` o `npm install -g @google/gemini-cli`). -Note JSON di Gemini CLI: +Note JSON per Gemini CLI: - Il testo della risposta viene letto dal campo JSON `response`. -- L'utilizzo ripiega su `stats` quando `usage` è assente o vuoto. -- `stats.cached` viene normalizzato in OpenClaw `cacheRead`. -- Se `stats.input` manca, OpenClaw deriva i token di input da +- L'uso ripiega su `stats` quando `usage` è assente o vuoto. +- `stats.cached` viene normalizzato in `cacheRead` di OpenClaw. +- Se `stats.input` manca, OpenClaw ricava i token di input da `stats.input_tokens - stats.cached`. -Sovrascrivi solo se necessario (caso comune: percorso `command` assoluto). +Sovrascrivi solo se necessario (caso comune: percorso assoluto di `command`). -## Predefiniti di proprietà del plugin +## Impostazioni predefinite di proprietà del Plugin -I predefiniti dei backend CLI ora fanno parte della superficie del plugin: +Le impostazioni predefinite del backend CLI ora fanno parte della superficie del Plugin: -- I Plugin li registrano con `api.registerCliBackend(...)`. +- I Plugin le registrano con `api.registerCliBackend(...)`. - L'`id` del backend diventa il prefisso del provider nei riferimenti ai modelli. -- La configurazione utente in `agents.defaults.cliBackends.` continua a sovrascrivere il valore predefinito del plugin. -- La pulizia della configurazione specifica del backend resta di proprietà del plugin tramite l'hook opzionale +- La configurazione utente in `agents.defaults.cliBackends.` sovrascrive ancora l'impostazione predefinita del Plugin. +- La pulizia della configurazione specifica del backend rimane di proprietà del Plugin tramite l'hook opzionale `normalizeConfig`. -I Plugin che necessitano di piccoli shim di compatibilità per prompt/messaggi possono dichiarare +I Plugin che hanno bisogno di piccoli adattatori di compatibilità per prompt/messaggi possono dichiarare trasformazioni di testo bidirezionali senza sostituire un provider o un backend CLI: ```typescript @@ -352,53 +358,53 @@ api.registerTextTransforms({ ``` `input` riscrive il prompt di sistema e il prompt utente passati alla CLI. `output` -riscrive i delta dell'assistente trasmessi in streaming e il testo finale analizzato prima che OpenClaw gestisca +riscrive i delta dell'assistente in streaming e il testo finale analizzato prima che OpenClaw gestisca i propri marcatori di controllo e la consegna al canale. Per le CLI che emettono JSONL compatibile con Claude Code stream-json, imposta `jsonlDialect: "claude-stream-json"` nella configurazione di quel backend. -## Sovrapposizioni MCP del bundle +## Overlay MCP in bundle I backend CLI **non** ricevono direttamente chiamate agli strumenti OpenClaw, ma un backend può -attivare una sovrapposizione di configurazione MCP generata con `bundleMcp: true`. +aderire a un overlay di configurazione MCP generato con `bundleMcp: true`. -Comportamento attuale incluso nel bundle: +Comportamento in bundle attuale: - `claude-cli`: file di configurazione MCP rigoroso generato - `codex-cli`: override di configurazione inline per `mcp_servers`; il server - local loopback OpenClaw generato è contrassegnato con la modalità di approvazione degli strumenti per server di Codex - così le chiamate MCP non possono bloccarsi in attesa di prompt di approvazione locali + loopback OpenClaw generato è contrassegnato con la modalità di approvazione degli strumenti per-server di Codex + così le chiamate MCP non possono bloccarsi sui prompt di approvazione locali - `google-gemini-cli`: file di impostazioni di sistema Gemini generato -Quando MCP del bundle è abilitato, OpenClaw: +Quando bundle MCP è abilitato, OpenClaw: - avvia un server MCP HTTP di loopback che espone gli strumenti del Gateway al processo CLI - autentica il bridge con un token per sessione (`OPENCLAW_MCP_TOKEN`) - limita l'accesso agli strumenti al contesto della sessione, dell'account e del canale correnti -- carica i server bundle-MCP abilitati per l'area di lavoro corrente -- li unisce a qualsiasi forma esistente di configurazione/impostazioni MCP del backend +- carica i server bundle-MCP abilitati per il workspace corrente +- li unisce a qualsiasi forma di configurazione/impostazioni MCP del backend esistente - riscrive la configurazione di avvio usando la modalità di integrazione di proprietà del backend dall'estensione proprietaria -Se non sono abilitati server MCP, OpenClaw inietta comunque una configurazione rigorosa quando un -backend attiva MCP del bundle, così le esecuzioni in background restano isolate. +Se nessun server MCP è abilitato, OpenClaw inietta comunque una configurazione rigorosa quando un +backend aderisce a bundle MCP, così le esecuzioni in background restano isolate. -I runtime MCP inclusi nel bundle e con ambito di sessione vengono memorizzati nella cache per il riuso all'interno di una sessione, quindi +I runtime MCP in bundle con ambito di sessione vengono memorizzati nella cache per il riutilizzo all'interno di una sessione, poi rimossi dopo `mcp.sessionIdleTtlMs` millisecondi di inattività (predefinito 10 -minuti; imposta `0` per disabilitare). Le esecuzioni incorporate una tantum, come probe di autenticazione, -generazione di slug e richiamo di Active Memory richiedono la pulizia alla fine dell'esecuzione, così i processi figlio stdio +minuti; imposta `0` per disabilitare). Le esecuzioni incorporate one-shot come sonde di autenticazione, +generazione di slug e richiamo di Active Memory richiedono la pulizia al termine dell'esecuzione, così i processi figlio stdio e gli stream Streamable HTTP/SSE non sopravvivono all'esecuzione. ## Limitazioni - **Nessuna chiamata diretta agli strumenti OpenClaw.** OpenClaw non inietta chiamate agli strumenti nel - protocollo del backend CLI. I backend vedono gli strumenti del Gateway solo quando attivano + protocollo del backend CLI. I backend vedono gli strumenti del Gateway solo quando aderiscono a `bundleMcp: true`. - **Lo streaming è specifico del backend.** Alcuni backend trasmettono JSONL in streaming; altri accumulano fino all'uscita. - **Gli output strutturati** dipendono dal formato JSON della CLI. -- **Le sessioni Codex CLI** riprendono tramite output testuale (senza JSONL), che è meno - strutturato dell'esecuzione iniziale con `--json`. Le sessioni OpenClaw funzionano comunque +- **Le sessioni Codex CLI** riprendono tramite output testuale (niente JSONL), che è meno + strutturato rispetto all'esecuzione iniziale `--json`. Le sessioni OpenClaw funzionano comunque normalmente. ## Risoluzione dei problemi diff --git a/docs/it/help/testing-live.md b/docs/it/help/testing-live.md index f75fe5199..09ce6651a 100644 --- a/docs/it/help/testing-live.md +++ b/docs/it/help/testing-live.md @@ -1,29 +1,29 @@ --- read_when: - - Esecuzione degli smoke test della matrice dei modelli live / backend CLI / ACP / media-provider + - Esecuzione degli smoke test della matrice dei modelli live / backend CLI / ACP / provider multimediale - Debug della risoluzione delle credenziali per i test live - - Aggiungere un nuovo test live specifico del provider + - Aggiunta di un nuovo test in ambiente reale specifico per fornitore sidebarTitle: Live tests -summary: 'Test live (che accedono alla rete): matrice dei modelli, backend CLI, ACP, provider multimediali, credenziali' +summary: 'Test reali (che accedono alla rete): matrice dei modelli, backend della CLI, ACP, provider multimediali, credenziali' title: 'Test: suite live' x-i18n: - generated_at: "2026-05-03T21:36:03Z" + generated_at: "2026-05-04T18:24:02Z" model: gpt-5.5 provider: openai - source_hash: 4057d8875fa3404108e89e4381c1dd14e96abbc2af13c4934fc6c0dbf878fc00 + source_hash: 03b8ca6348137a55c8d5f67c9c166a130a75a744f6a433cb00496756b29d7016 source_path: help/testing-live.md workflow: 16 --- -Per l'avvio rapido, i runner QA, le suite unità/integrazione e i flussi Docker, vedi -[Test](/it/help/testing). Questa pagina copre le suite di test **dal vivo** (che toccano la rete): -matrice dei modelli, backend CLI, ACP e test dal vivo dei provider multimediali, oltre alla +Per avvio rapido, runner QA, suite di unit/integration e flussi Docker, consulta +[Testing](/it/help/testing). Questa pagina copre le suite di test **live** (che usano la rete): +matrice dei modelli, backend CLI, ACP e test live dei provider multimediali, oltre alla gestione delle credenziali. -## Dal vivo: comandi smoke del profilo locale +## Live: comandi smoke del profilo locale -Sorgente `~/.profile` prima dei controlli dal vivo ad hoc, in modo che le chiavi dei provider e i percorsi degli strumenti locali -corrispondano alla tua shell: +Esegui il source di `~/.profile` prima dei controlli live ad hoc, così le chiavi dei provider e i percorsi degli strumenti locali +corrispondono alla tua shell: ```bash source ~/.profile @@ -37,102 +37,102 @@ pnpm openclaw infer tts convert --local --json \ --output /tmp/openclaw-live-smoke.mp3 ``` -Smoke sicuro di prontezza per chiamata vocale: +Smoke sicuro di preparazione alle chiamate vocali: ```bash pnpm openclaw voicecall setup --json pnpm openclaw voicecall smoke --to "+15555550123" ``` -`voicecall smoke` è un'esecuzione di prova a secco, a meno che non sia presente anche `--yes`. Usa `--yes` solo +`voicecall smoke` è una prova a secco a meno che non sia presente anche `--yes`. Usa `--yes` solo quando vuoi intenzionalmente effettuare una vera chiamata di notifica. Per Twilio, Telnyx e -Plivo, un controllo di prontezza riuscito richiede un URL Webhook pubblico; i fallback solo locali -loopback/privati sono rifiutati per progettazione. +Plivo, un controllo di preparazione riuscito richiede un URL Webhook pubblico; i fallback +locali solo loopback/privati vengono rifiutati per progettazione. -## Dal vivo: sweep delle capacità del nodo Android +## Live: sweep delle capability del Node Android - Test: `src/gateway/android-node.capabilities.live.test.ts` - Script: `pnpm android:test:integration` -- Obiettivo: invocare **ogni comando attualmente pubblicizzato** da un nodo 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: - - Configurazione manuale/precondizionata (la suite non installa/esegue/abbina l'app). - - Convalida `node.invoke` del Gateway comando per comando per il nodo Android selezionato. + - Configurazione preliminare/manuale (la suite non installa/esegue/abbina l'app). + - Validazione comando per comando di `node.invoke` del Gateway per il Node Android selezionato. - Preconfigurazione richiesta: - App Android già connessa e abbinata al Gateway. - App mantenuta in primo piano. - - Permessi/consenso alla cattura concessi per le capacità che ti aspetti superino il test. -- Override opzionali del target: + - Autorizzazioni/consenso alla cattura concessi per le capability che ti aspetti superino il test. +- Override opzionali della destinazione: - `OPENCLAW_ANDROID_NODE_ID` o `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Dettagli completi della configurazione Android: [App Android](/it/platforms/android) +- Dettagli completi della configurazione Android: [Android App](/it/platforms/android) -## Dal vivo: smoke dei modelli (chiavi profilo) +## Live: smoke dei modelli (chiavi del profilo) -I test dal vivo sono divisi in due livelli, così possiamo isolare gli errori: +I test live sono divisi in due livelli per consentirci di isolare gli errori: -- “Modello diretto” ci dice se il provider/modello riesce a rispondere in assoluto con la chiave fornita. -- “Smoke Gateway” ci dice se l'intera pipeline gateway+agente funziona per quel modello (sessioni, cronologia, strumenti, policy sandbox, ecc.). +- “Modello diretto” ci dice se il provider/modello può rispondere in assoluto con la chiave fornita. +- “Gateway smoke” ci dice se l'intera pipeline gateway+agent funziona per quel modello (sessioni, cronologia, strumenti, policy sandbox, ecc.). -### Livello 1: completamento diretto del modello (nessun gateway) +### Livello 1: completamento modello diretto (nessun gateway) - Test: `src/agents/models.profiles.live.test.ts` - Obiettivo: - - Enumerare i modelli scoperti + - Enumerare i modelli rilevati - Usare `getApiKeyForModel` per selezionare i modelli per cui hai credenziali - Eseguire un piccolo completamento per modello (e regressioni mirate dove necessario) - Come abilitarlo: - - `pnpm test:live` (o `OPENCLAW_LIVE_TEST=1` se invochi Vitest direttamente) -- Imposta `OPENCLAW_LIVE_MODELS=modern` (o `all`, alias per modern) per eseguire davvero questa suite; altrimenti viene saltata per mantenere `pnpm test:live` concentrato sullo smoke del Gateway + - `pnpm test:live` (o `OPENCLAW_LIVE_TEST=1` se invochi direttamente Vitest) +- Imposta `OPENCLAW_LIVE_MODELS=modern` (o `all`, alias di modern) per eseguire effettivamente questa suite; altrimenti viene saltata per mantenere `pnpm test:live` concentrato sul gateway smoke - Come selezionare i modelli: - - `OPENCLAW_LIVE_MODELS=modern` per eseguire la lista consentita moderna (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4.3) - - `OPENCLAW_LIVE_MODELS=all` è un alias per la lista consentita moderna - - oppure `OPENCLAW_LIVE_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,..."` (lista consentita separata da virgole) - - Gli sweep modern/all usano per impostazione predefinita un limite curato ad alto segnale; imposta `OPENCLAW_LIVE_MAX_MODELS=0` per uno sweep moderno esaustivo o un numero positivo per un limite più piccolo. - - Gli sweep esaustivi usano `OPENCLAW_LIVE_TEST_TIMEOUT_MS` per il timeout dell'intero test del modello diretto. Predefinito: 60 minuti. - - Le sonde dei modelli diretti vengono eseguite con parallelismo a 20 vie per impostazione predefinita; imposta `OPENCLAW_LIVE_MODEL_CONCURRENCY` per eseguire l'override. + - `OPENCLAW_LIVE_MODELS=modern` per eseguire l'allowlist moderna (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4.3) + - `OPENCLAW_LIVE_MODELS=all` è un alias dell'allowlist moderna + - oppure `OPENCLAW_LIVE_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,..."` (allowlist separata da virgole) + - Gli sweep modern/all usano per impostazione predefinita un limite curato ad alto segnale; imposta `OPENCLAW_LIVE_MAX_MODELS=0` per uno sweep moderno esaustivo oppure un numero positivo per un limite più piccolo. + - Gli sweep esaustivi usano `OPENCLAW_LIVE_TEST_TIMEOUT_MS` per il timeout dell'intero test modello diretto. Predefinito: 60 minuti. + - Le sonde modello diretto vengono eseguite con parallelismo a 20 vie per impostazione predefinita; imposta `OPENCLAW_LIVE_MODEL_CONCURRENCY` per sovrascriverlo. - Come selezionare i provider: - - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (lista consentita separata da virgole) -- Da dove provengono le chiavi: + - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist separata da virgole) +- Da dove arrivano le chiavi: - Per impostazione predefinita: archivio profili e fallback env - Imposta `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per imporre solo **archivio profili** - Perché esiste: - - Separa “l'API del provider è rotta / la chiave non è valida” da “la pipeline dell'agente Gateway è rotta” - - Contiene regressioni piccole e isolate (esempio: replay del ragionamento OpenAI Responses/Codex Responses + flussi di chiamata strumento) + - Separa “l'API del provider è rotta / la chiave non è valida” da “la pipeline agent del gateway è rotta” + - Contiene piccole regressioni isolate (esempio: replay del ragionamento OpenAI Responses/Codex Responses + flussi tool-call) -### Livello 2: Gateway + smoke agente dev (ciò che "@openclaw" fa realmente) +### Livello 2: smoke Gateway + agent di sviluppo (ciò che "@openclaw" fa davvero) - Test: `src/gateway/gateway-models.profiles.live.test.ts` - Obiettivo: - - Avviare un Gateway nel processo - - Creare/correggere una sessione `agent:dev:*` (override del modello per esecuzione) - - Iterare i modelli con chiavi e verificare: + - Avviare un gateway in-process + - Creare/applicare patch a una sessione `agent:dev:*` (override del modello per esecuzione) + - Iterare sui modelli con chiavi e verificare: - risposta “significativa” (nessuno strumento) - - funziona una vera invocazione di strumento (sonda di lettura) - - sonde strumento extra opzionali (sonda exec+read) - - i percorsi di regressione OpenAI (solo chiamata strumento → seguito) continuano a funzionare -- Dettagli delle sonde (così puoi spiegare rapidamente gli errori): - - sonda `read`: il test scrive un file nonce nello spazio di lavoro e chiede all'agente di `read` leggerlo e restituire il nonce. - - sonda `exec+read`: il test chiede all'agente di scrivere con `exec` un nonce in un file temporaneo, quindi di rileggerlo con `read`. - - sonda immagine: il test allega un PNG generato (gatto + codice randomizzato) e si aspetta che il modello restituisca `cat `. + - un'invocazione reale di strumento funziona (sonda di lettura) + - sonde strumenti extra opzionali (sonda exec+read) + - i percorsi di regressione OpenAI (solo tool-call → follow-up) continuano a funzionare +- Dettagli delle sonde (per poter spiegare rapidamente gli errori): + - sonda `read`: il test scrive un file nonce nel workspace e chiede all'agent di `read` il file e restituire il nonce. + - sonda `exec+read`: il test chiede all'agent di scrivere con `exec` un nonce in un file temporaneo, poi di leggerlo di nuovo con `read`. + - sonda immagine: il test allega un PNG generato (cat + codice randomizzato) e si aspetta che il modello restituisca `cat `. - Riferimento implementativo: `src/gateway/gateway-models.profiles.live.test.ts` e `src/gateway/live-image-probe.ts`. - Come abilitarlo: - - `pnpm test:live` (o `OPENCLAW_LIVE_TEST=1` se invochi Vitest direttamente) + - `pnpm test:live` (o `OPENCLAW_LIVE_TEST=1` se invochi direttamente Vitest) - Come selezionare i modelli: - - Predefinito: lista consentita moderna (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4.3) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` è un alias per la lista consentita moderna - - Oppure imposta `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (o lista separata da virgole) per restringere - - Gli sweep Gateway modern/all usano per impostazione predefinita un limite curato ad alto segnale; imposta `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` per uno sweep moderno esaustivo o un numero positivo per un limite più piccolo. + - Predefinito: allowlist moderna (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4.3) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` è un alias dell'allowlist moderna + - 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 moderno 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"` (lista consentita separata da virgole) -- Le sonde strumento + immagine sono sempre attive in questo test dal vivo: + - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist separata da virgole) +- Le sonde strumenti + immagine sono sempre attive in questo test live: - sonda `read` + sonda `exec+read` (stress strumenti) - - la sonda immagine viene eseguita quando il modello pubblicizza il supporto per input immagine - - Flusso (alto livello): + - la sonda immagine viene eseguita quando il modello pubblicizza il supporto all'input immagine + - Flusso (ad alto livello): - Il test genera un piccolo PNG con “CAT” + codice casuale (`src/gateway/live-image-probe.ts`) - Lo invia tramite `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - Gateway analizza gli allegati in `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - L'agente incorporato inoltra un messaggio utente multimodale al modello - - Asserzione: la risposta contiene `cat` + il codice (tolleranza OCR: errori minori consentiti) + - L'agent incorporato inoltra al modello un messaggio utente multimodale + - Asserzione: la risposta contiene `cat` + il codice (tolleranza OCR: ammessi errori minori) Per vedere cosa puoi testare sulla tua macchina (e gli ID `provider/model` esatti), esegui: @@ -144,27 +144,27 @@ openclaw models list --json -## Dal vivo: smoke backend CLI (Claude, Codex, Gemini o altre CLI locali) +## Live: smoke backend CLI (Claude, Codex, Gemini o altre CLI locali) - Test: `src/gateway/gateway-cli-backend.live.test.ts` -- Obiettivo: convalidare la pipeline Gateway + agente usando un backend CLI locale, senza toccare la configurazione predefinita. -- I valori predefiniti dello smoke specifici del backend risiedono nella definizione `cli-backend.ts` del Plugin proprietario. -- Abilitazione: - - `pnpm test:live` (o `OPENCLAW_LIVE_TEST=1` se invochi Vitest direttamente) +- Obiettivo: validare la pipeline Gateway + agent usando un backend CLI locale, senza toccare la configurazione predefinita. +- Le impostazioni smoke predefinite specifiche del backend risiedono nella definizione `cli-backend.ts` dell'estensione proprietaria. +- Abilita: + - `pnpm test:live` (o `OPENCLAW_LIVE_TEST=1` se invochi direttamente Vitest) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Predefiniti: - Provider/modello predefinito: `claude-cli/claude-sonnet-4-6` - - Comportamento comando/argomenti/immagine proveniente dai metadati del Plugin backend CLI proprietario. + - Comando/argomenti/comportamento immagine provengono dai metadati del plugin backend CLI proprietario. - Override (opzionali): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.5"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` per inviare un vero allegato immagine (i percorsi vengono iniettati nel prompt). Le ricette Docker lo disattivano per impostazione predefinita, salvo richiesta esplicita. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` per inviare un vero allegato immagine (i percorsi vengono iniettati nel prompt). Le ricette Docker lo disattivano per impostazione predefinita salvo richiesta esplicita. - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` per passare i percorsi dei file immagine come argomenti CLI invece dell'iniezione nel prompt. - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (o `"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_RESUME_PROBE=1` per inviare un secondo turno e validare il flusso di ripresa. - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=1` per aderire alla sonda di continuità nella stessa sessione Claude Sonnet -> Opus quando il modello selezionato supporta un target di cambio. Le ricette Docker lo disattivano per impostazione predefinita per l'affidabilità aggregata. - - `OPENCLAW_LIVE_CLI_BACKEND_MCP_PROBE=1` per aderire alla sonda MCP/strumento loopback. Le ricette Docker lo disattivano per impostazione predefinita, salvo richiesta esplicita. + - `OPENCLAW_LIVE_CLI_BACKEND_MCP_PROBE=1` per aderire alla sonda MCP/tool local loopback. Le ricette Docker lo disattivano per impostazione predefinita salvo richiesta esplicita. Esempio: @@ -181,9 +181,9 @@ OPENCLAW_LIVE_TEST=1 \ pnpm test:live src/agents/cli-runner/bundle-mcp.gemini.live.test.ts ``` -Questo non chiede a Gemini di generare una risposta. Scrive le stesse -impostazioni di sistema che OpenClaw fornisce a Gemini, quindi esegue `gemini --debug mcp list` per dimostrare che un -server salvato `transport: "streamable-http"` viene normalizzato nella forma HTTP MCP di Gemini +Questo non chiede a Gemini di generare una risposta. Scrive le stesse impostazioni di sistema +che OpenClaw fornisce a Gemini, poi esegue `gemini --debug mcp list` per dimostrare che un +server `transport: "streamable-http"` salvato viene normalizzato nella forma HTTP MCP di Gemini e può connettersi a un server MCP streamable-HTTP locale. Ricetta Docker: @@ -204,24 +204,33 @@ pnpm test:docker:live-cli-backend:gemini Note: - Il runner Docker risiede in `scripts/test-live-cli-backend-docker.sh`. -- Esegue lo smoke dal vivo del backend CLI dentro l'immagine Docker del repo come utente non root `node`. -- Risolve i metadati dello smoke CLI dal Plugin proprietario, quindi installa il pacchetto CLI Linux corrispondente (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) in un prefisso scrivibile memorizzato nella 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`. Dimostra prima `claude -p` diretto in Docker, quindi esegue due turni backend CLI Gateway senza preservare le variabili env della chiave API Anthropic. Questa corsia di abbonamento disabilita per impostazione predefinita le sonde MCP/strumento e immagine di Claude perché Claude attualmente instrada l'uso di app di terze parti tramite fatturazione per uso extra invece dei normali limiti del piano di abbonamento. -- Lo smoke dal vivo del backend CLI ora esercita lo stesso flusso end-to-end per Claude, Codex e Gemini: turno testuale, turno di classificazione immagine, quindi chiamata strumento MCP `cron` verificata tramite la CLI Gateway. -- Lo smoke predefinito di Claude corregge anche la sessione da Sonnet a Opus e verifica che la sessione ripresa ricordi ancora una nota precedente. +- Esegue lo smoke live del backend CLI dentro l'immagine Docker del repo come utente non root `node`. +- Risolve i metadati smoke CLI dall'estensione proprietaria, poi installa il pacchetto CLI Linux corrispondente (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) in un prefisso scrivibile memorizzato 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 per 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 chiave API Anthropic. Questa corsia di abbonamento disabilita per impostazione predefinita le sonde MCP/tool e immagine di Claude perché Claude attualmente instrada l'uso di app di terze parti attraverso fatturazione di utilizzo extra invece dei 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 testuale, turno di classificazione immagine, poi chiamata allo strumento MCP `cron` verificata tramite la CLI gateway. +- Lo smoke predefinito di Claude applica anche una patch alla sessione da Sonnet a Opus e verifica che la sessione ripresa ricordi ancora una nota precedente. -## Dal vivo: smoke di binding ACP (`/acp spawn ... --bind here`) +## Live: raggiungibilità proxy APNs HTTP/2 + +- Test: `src/infra/push-apns-http2.live.test.ts` +- Obiettivo: creare un tunnel tramite un proxy HTTP CONNECT locale verso l'endpoint APNs sandbox di Apple, inviare la richiesta di validazione APNs HTTP/2 e verificare che la vera risposta `403 InvalidProviderToken` di Apple torni tramite il percorso proxy. +- Abilita: + - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_APNS_REACHABILITY=1 pnpm test:live src/infra/push-apns-http2.live.test.ts` +- Timeout opzionale: + - `OPENCLAW_LIVE_APNS_TIMEOUT_MS=30000` + +## Live: smoke bind ACP (`/acp spawn ... --bind here`) - Test: `src/gateway/gateway-acp-bind.live.test.ts` - Obiettivo: convalidare il flusso reale di associazione conversazione ACP con un agente ACP live: - inviare `/acp spawn --bind here` - - associare sul posto una conversazione sintetica di canale messaggi + - associare sul posto una conversazione sintetica del canale messaggi - inviare un normale follow-up sulla stessa conversazione - verificare che il follow-up arrivi nella trascrizione della sessione ACP associata -- Abilitare: +- Abilitazione: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` -- Predefiniti: +- 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 @@ -240,9 +249,9 @@ Note: - `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1` - `OPENCLAW_LIVE_ACP_BIND_PARENT_MODEL=openai/gpt-5.5` - Note: - - Questa lane usa la superficie `chat.send` del Gateway con campi di route originante sintetica solo per amministratori, così i test possono collegare il contesto del canale messaggi senza fingere una consegna esterna. - - Quando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` non è impostato, il test usa il registro agenti integrato del Plugin `acpx` incorporato per l’agente harness ACP selezionato. - - La creazione MCP Cron della sessione associata è best-effort per impostazione predefinita, perché gli harness ACP esterni possono annullare le chiamate MCP dopo che la prova di bind/immagine è passata; impostare `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1` per rendere rigorosa quella sonda Cron post-bind. + - Questa lane usa la superficie `chat.send` del Gateway con campi di originating-route sintetici riservati agli amministratori, così i test possono collegare il contesto del canale messaggi senza fingere di consegnarlo esternamente. + - Quando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` non è impostato, il test usa il registro agenti integrato del Plugin `acpx` incorporato per l'agente ACP harness selezionato. + - La creazione dell'MCP Cron della sessione associata è best-effort per impostazione predefinita perché gli harness ACP esterni possono annullare le chiamate MCP dopo che la prova di associazione/immagine è passata; imposta `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1` per rendere rigorosa quella sonda Cron post-associazione. Esempio: @@ -272,30 +281,37 @@ Note Docker: - Il runner Docker si trova in `scripts/test-live-acp-bind-docker.sh`. - Per impostazione predefinita, esegue lo smoke ACP bind contro gli agenti CLI live aggregati in sequenza: `claude`, `codex`, poi `gemini`. -- Usare `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=droid`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` oppure `OPENCLAW_LIVE_ACP_BIND_AGENTS=opencode` per restringere la matrice. -- Esegue il source di `~/.profile`, prepara nel container il materiale di autenticazione CLI corrispondente, quindi installa la CLI live richiesta (`@anthropic-ai/claude-code`, `@openai/codex`, Factory Droid tramite `https://app.factory.ai/cli`, `@google/gemini-cli` oppure `opencode-ai`) se manca. Il backend ACP stesso è il pacchetto `acpx/runtime` incorporato dal Plugin ufficiale `acpx`. -- La variante Docker Droid prepara `~/.factory` per le impostazioni, inoltra `FACTORY_API_KEY` e richiede quella chiave API perché l’autenticazione locale Factory OAuth/keyring non è portabile nel container. Usa la voce di registro integrata di ACPX `droid exec --output-format acp`. -- La variante Docker OpenCode è una lane di regressione rigorosa per singolo agente. Scrive un modello predefinito temporaneo `OPENCODE_CONFIG_CONTENT` da `OPENCLAW_LIVE_ACP_BIND_OPENCODE_MODEL` (predefinito `opencode/kimi-k2.6`) dopo il source di `~/.profile`, e `pnpm test:docker:live-acp-bind:opencode` richiede una trascrizione dell’assistente associata invece di accettare il generico skip post-bind. -- Le chiamate CLI dirette a `acpx` sono solo un percorso manuale/di workaround per confrontare il comportamento fuori dal Gateway. Lo smoke ACP bind Docker esercita il backend runtime `acpx` incorporato di OpenClaw. +- Usa `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=droid`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` oppure `OPENCLAW_LIVE_ACP_BIND_AGENTS=opencode` per restringere la matrice. +- Esegue il source di `~/.profile`, predispone nel container il materiale di autenticazione CLI corrispondente, poi installa la CLI live richiesta (`@anthropic-ai/claude-code`, `@openai/codex`, Factory Droid tramite `https://app.factory.ai/cli`, `@google/gemini-cli` oppure `opencode-ai`) se manca. Il backend ACP stesso è il pacchetto `acpx/runtime` incorporato dal Plugin ufficiale `acpx`. +- La variante Docker Droid predispone `~/.factory` per le impostazioni, inoltra `FACTORY_API_KEY` e richiede quella chiave API perché l'autenticazione locale Factory OAuth/keyring non è portabile nel container. Usa la voce di registro integrata di ACPX `droid exec --output-format acp`. +- La variante Docker OpenCode è una lane di regressione rigorosa per singolo agente. Scrive un modello predefinito temporaneo `OPENCODE_CONFIG_CONTENT` da `OPENCLAW_LIVE_ACP_BIND_OPENCODE_MODEL` (predefinito `opencode/kimi-k2.6`) dopo aver eseguito il source di `~/.profile`, e `pnpm test:docker:live-acp-bind:opencode` richiede una trascrizione dell'assistente associata invece di accettare lo skip generico post-associazione. +- Le chiamate dirette alla CLI `acpx` sono solo un percorso manuale/di workaround per confrontare il comportamento fuori dal Gateway. Lo smoke ACP bind Docker esercita il backend runtime `acpx` incorporato di OpenClaw. -## Live: smoke dell’harness app-server Codex +## Live: smoke dell'harness app-server Codex -- Obiettivo: convalidare l’harness Codex di proprietà del Plugin tramite il normale metodo gateway +- Obiettivo: convalidare l'harness Codex di proprietà del Plugin tramite il normale metodo Gateway `agent`: - - caricare il Plugin `codex` in bundle + - caricare il Plugin `codex` incluso - selezionare `OPENCLAW_AGENT_RUNTIME=codex` - - inviare un primo turno dell’agente Gateway a `openai/gpt-5.5` con l’harness Codex forzato - - inviare un secondo turno alla stessa sessione OpenClaw e verificare che il thread app-server possa riprendere - - eseguire `/codex status` e `/codex models` tramite lo stesso percorso di comando Gateway - - facoltativamente eseguire due sonde shell con escalation revisionate da Guardian: un comando benigno che dovrebbe essere approvato e un caricamento con segreto falso che dovrebbe essere negato così l’agente risponde con una domanda + - inviare un primo turno agente Gateway a `openai/gpt-5.5` con l'harness Codex forzato + - inviare un secondo turno alla stessa sessione OpenClaw e verificare che il thread + app-server possa riprendere + - eseguire `/codex status` e `/codex models` attraverso lo stesso percorso di comando + Gateway + - opzionalmente eseguire due sonde shell con escalation revisionate da Guardian: un comando + innocuo che dovrebbe essere approvato e un caricamento di falso segreto che dovrebbe essere + negato così l'agente risponde con una richiesta - Test: `src/gateway/gateway-codex-harness.live.test.ts` -- Abilitare: `OPENCLAW_LIVE_CODEX_HARNESS=1` +- Abilitazione: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Modello predefinito: `openai/gpt-5.5` -- Sonda immagine facoltativa: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- Sonda MCP/tool facoltativa: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- Sonda Guardian facoltativa: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` -- Lo smoke usa `agentRuntime.id: "codex"` così un harness Codex rotto non può passare ricadendo silenziosamente su PI. -- Autenticazione: autenticazione app-server Codex dal login dell’abbonamento Codex locale. Gli smoke Docker possono anche fornire `OPENAI_API_KEY` per sonde non Codex quando applicabile, più eventuali `~/.codex/auth.json` e `~/.codex/config.toml` copiati. +- Sonda immagine opzionale: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- Sonda MCP/strumento opzionale: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- Sonda Guardian opzionale: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` +- Lo smoke usa `agentRuntime.id: "codex"` così un harness Codex rotto non può + passare ripiegando silenziosamente su PI. +- Autenticazione: autenticazione app-server Codex dal login alla sottoscrizione Codex locale. Gli smoke Docker + possono anche fornire `OPENAI_API_KEY` per sonde non Codex quando applicabile, + più `~/.codex/auth.json` e `~/.codex/config.toml` copiati opzionalmente. Ricetta locale: @@ -319,64 +335,70 @@ pnpm test:docker:live-codex-harness Note Docker: - Il runner Docker si trova in `scripts/test-live-codex-harness-docker.sh`. -- Esegue il source del `~/.profile` montato, passa `OPENAI_API_KEY`, copia i file di autenticazione 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. -- Docker abilita per impostazione predefinita le sonde immagine, MCP/tool e Guardian. Impostare `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` oppure `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` oppure `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0` quando serve un’esecuzione di debug più ristretta. -- Docker usa la stessa configurazione runtime Codex esplicita, quindi alias legacy o fallback PI non possono nascondere una regressione dell’harness Codex. +- Esegue il source di `~/.profile` montato, passa `OPENAI_API_KEY`, copia i file di + autenticazione della CLI Codex quando presenti, installa `@openai/codex` in un prefisso npm + montato scrivibile, predispone l'albero sorgente, quindi esegue solo il test live dell'harness Codex. +- Docker abilita per impostazione predefinita le sonde immagine, MCP/strumento e Guardian. Imposta + `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` oppure + `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` oppure + `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0` quando serve un'esecuzione di debug più ristretta. +- Docker usa la stessa configurazione runtime Codex esplicita, quindi alias legacy o fallback PI + non possono nascondere una regressione dell'harness Codex. ### Ricette live consigliate -Le allowlist ristrette ed esplicite sono le più rapide e le meno instabili: +Le allowlist ristrette ed esplicite sono le più rapide e meno soggette a flakiness: -- Singolo modello, diretto (senza gateway): +- Singolo modello, diretto (senza Gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.5" pnpm test:live src/agents/models.profiles.live.test.ts` - Singolo modello, smoke Gateway: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Chiamata tool tra più provider: +- Chiamata di strumenti su più provider: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,deepseek/deepseek-v4-flash,zai/glm-5.1,minimax/MiniMax-M2.7" 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` -- Smoke di adaptive thinking Google: +- Smoke del thinking adattivo Google: - Se le chiavi locali stanno nel profilo shell: `source ~/.profile` - Predefinito dinamico Gemini 3: `pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-3.1-pro-preview --alt-model google/gemini-3.1-pro-preview --message '/think adaptive Reply exactly: GEMINI_ADAPTIVE_OK' --timeout-ms 180000` - Budget dinamico Gemini 2.5: `pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-2.5-flash --alt-model google/gemini-2.5-flash --message '/think adaptive Reply exactly: GEMINI25_ADAPTIVE_OK' --timeout-ms 180000` Note: -- `google/...` usa l’API Gemini (chiave API). +- `google/...` usa l'API Gemini (chiave API). - `google-antigravity/...` usa il bridge OAuth Antigravity (endpoint agente in stile Cloud Code Assist). -- `google-gemini-cli/...` usa la CLI Gemini locale sulla tua macchina (autenticazione separata + particolarità degli strumenti). -- Gemini API vs Gemini CLI: - - API: OpenClaw chiama l’API Gemini ospitata da Google su HTTP (chiave API / autenticazione profilo); questo è ciò che la maggior parte degli utenti intende per “Gemini”. - - CLI: OpenClaw invoca tramite shell un binario locale `gemini`; ha la propria autenticazione e può comportarsi diversamente (supporto streaming/tool/disallineamento versioni). +- `google-gemini-cli/...` usa la CLI Gemini locale sulla tua macchina (autenticazione separata + peculiarità degli strumenti). +- API Gemini rispetto a CLI Gemini: + - API: OpenClaw chiama l'API Gemini ospitata di Google via HTTP (chiave API / autenticazione profilo); questo è ciò che la maggior parte degli utenti intende con “Gemini”. + - CLI: OpenClaw esegue in shell un binario locale `gemini`; ha una propria autenticazione e può comportarsi diversamente (supporto streaming/strumenti/disallineamento di versione). -## Live: matrice modelli (cosa copriamo) +## Live: matrice dei modelli (cosa copriamo) Non esiste una “lista modelli CI” fissa (live è opt-in), ma questi sono i modelli **consigliati** da coprire regolarmente su una macchina di sviluppo con chiavi. -### Set smoke moderno (chiamata tool + immagine) +### Set smoke moderno (chiamata di strumenti + immagine) -Questa è l’esecuzione dei “modelli comuni” che ci aspettiamo continui a funzionare: +Questa è l'esecuzione dei “modelli comuni” che ci aspettiamo continui a funzionare: - OpenAI (non Codex): `openai/gpt-5.5` - OpenAI Codex OAuth: `openai-codex/gpt-5.5` - Anthropic: `anthropic/claude-opus-4-6` (oppure `anthropic/claude-sonnet-4-6`) -- Google (Gemini API): `google/gemini-3.1-pro-preview` e `google/gemini-3-flash-preview` (evitare i modelli Gemini 2.x più vecchi) +- Google (API Gemini): `google/gemini-3.1-pro-preview` e `google/gemini-3-flash-preview` (evitare i modelli Gemini 2.x più vecchi) - Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` e `google-antigravity/gemini-3-flash` - DeepSeek: `deepseek/deepseek-v4-flash` e `deepseek/deepseek-v4-pro` - Z.AI (GLM): `zai/glm-5.1` - MiniMax: `minimax/MiniMax-M2.7` -Eseguire lo smoke Gateway con tool + immagine: +Esegui lo smoke Gateway con strumenti + immagine: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,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,deepseek/deepseek-v4-flash,zai/glm-5.1,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Baseline: chiamata tool (Read + Exec facoltativo) +### Baseline: chiamata di strumenti (Read + Exec opzionale) -Sceglierne almeno uno per famiglia di provider: +Scegline almeno uno per famiglia di provider: - OpenAI: `openai/gpt-5.5` - Anthropic: `anthropic/claude-opus-4-6` (oppure `anthropic/claude-sonnet-4-6`) @@ -385,22 +407,22 @@ Sceglierne almeno uno per famiglia di provider: - Z.AI (GLM): `zai/glm-5.1` - MiniMax: `minimax/MiniMax-M2.7` -Copertura aggiuntiva facoltativa (utile da avere): +Copertura aggiuntiva opzionale (utile da avere): -- xAI: `xai/grok-4.3` (oppure l’ultimo disponibile) -- Mistral: `mistral/`… (scegliere un modello capace di “tools” che hai abilitato) +- xAI: `xai/grok-4.3` (oppure l'ultima disponibile) +- Mistral: `mistral/`… (scegli un modello capace di “tools” che hai abilitato) - Cerebras: `cerebras/`… (se hai accesso) -- LM Studio: `lmstudio/`… (locale; la chiamata tool dipende dalla modalità API) +- LM Studio: `lmstudio/`… (locale; la chiamata di strumenti dipende dalla modalità API) -### Vision: invio immagine (allegato → messaggio multimodale) +### Visione: invio immagine (allegato → messaggio multimodale) -Includere almeno un modello capace di immagini in `OPENCLAW_LIVE_GATEWAY_MODELS` (varianti Claude/Gemini/OpenAI con capacità vision, ecc.) per esercitare la sonda immagine. +Includi almeno un modello capace di immagini in `OPENCLAW_LIVE_GATEWAY_MODELS` (varianti Claude/Gemini/OpenAI capaci di visione, ecc.) per esercitare la sonda immagine. -### Aggregatori / gateway alternativi +### Aggregatori / Gateway alternativi Se hai chiavi abilitate, supportiamo anche il test tramite: -- OpenRouter: `openrouter/...` (centinaia di modelli; usare `openclaw models scan` per trovare candidati capaci di tool+immagine) +- OpenRouter: `openrouter/...` (centinaia di modelli; usa `openclaw models scan` per trovare candidati capaci di strumenti+immagine) - OpenCode: `opencode/...` per Zen e `opencode-go/...` per Go (autenticazione tramite `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) Altri provider che puoi includere nella matrice live (se hai credenziali/configurazione): @@ -409,54 +431,54 @@ Altri provider che puoi includere nella matrice live (se hai credenziali/configu - Tramite `models.providers` (endpoint personalizzati): `minimax` (cloud/API), più qualsiasi proxy compatibile con OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, ecc.) -Non codificare rigidamente "all models" nella documentazione. La lista autorevole è qualunque cosa `discoverModels(...)` restituisca sulla tua macchina più le chiavi disponibili. +Non codificare rigidamente "all models" nella documentazione. La lista autorevole è qualsiasi cosa `discoverModels(...)` restituisca sulla tua macchina più le chiavi disponibili. -## Credenziali (mai fare commit) +## Credenziali (non committare mai) I test live scoprono 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 “no creds”, esegui il debug nello stesso modo in cui eseguiresti il debug di `openclaw models list` / della selezione del modello. +- Se la CLI funziona, i test in ambiente reale dovrebbero trovare le stesse chiavi. +- Se un test in ambiente reale dice “nessuna credenziale”, esegui il debug nello stesso modo in cui eseguiresti il debug di `openclaw models list` / della selezione del modello. -- Profili di autenticazione per agente: `~/.openclaw/agents//agent/auth-profiles.json` (questo è ciò che “profile keys” significa nei test live) -- Configurazione: `~/.openclaw/openclaw.json` (o `OPENCLAW_CONFIG_PATH`) -- Directory di stato legacy: `~/.openclaw/credentials/` (copiata nella home live in staging quando presente, ma non nell’archivio principale delle chiavi profilo) -- Le esecuzioni live locali copiano per impostazione predefinita la configurazione attiva, i file `auth-profiles.json` per agente, `credentials/` legacy e le directory di autenticazione CLI esterne supportate in una home di test temporanea; le home live in staging saltano `workspace/` e `sandboxes/`, e gli override dei percorsi `agents.*.workspace` / `agentDir` vengono rimossi, così le sonde restano fuori dalla tua workspace host reale. +- Profili di autenticazione per agente: `~/.openclaw/agents//agent/auth-profiles.json` (questo è ciò che significa “chiavi profilo” nei test in ambiente reale) +- Configurazione: `~/.openclaw/openclaw.json` (oppure `OPENCLAW_CONFIG_PATH`) +- Directory di stato legacy: `~/.openclaw/credentials/` (copiata nella home temporanea per i test in ambiente reale quando presente, ma non è l'archivio principale delle chiavi profilo) +- Le esecuzioni locali in ambiente reale copiano per impostazione predefinita la configurazione attiva, i file `auth-profiles.json` per agente, `credentials/` legacy e le directory di autenticazione CLI esterne supportate in una home di test temporanea; le home temporanee per i test in ambiente reale saltano `workspace/` e `sandboxes/`, e gli override dei percorsi `agents.*.workspace` / `agentDir` vengono rimossi così le sonde restano fuori dal workspace reale del tuo host. -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 qui sotto (possono montare `~/.profile` nel container). +Se vuoi fare affidamento sulle chiavi di ambiente (ad es. esportate nel tuo `~/.profile`), esegui i test locali dopo `source ~/.profile`, oppure usa i runner Docker qui sotto (possono montare `~/.profile` nel container). -## Deepgram live (trascrizione audio) +## Deepgram in ambiente reale (trascrizione audio) - Test: `extensions/deepgram/audio.live.test.ts` - Abilita: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts` -## Piano di codifica BytePlus live +## Piano di codifica BytePlus in ambiente reale - Test: `extensions/byteplus/live.test.ts` - Abilita: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts` - Override opzionale del modello: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Media del workflow ComfyUI live +## Media del workflow ComfyUI in ambiente reale - 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` - Ambito: - - Esercita i percorsi comfy inclusi per immagine, video e `music_generate` - - Salta ciascuna capability a meno che `plugins.entries.comfy.config.` non sia configurata - - Utile dopo modifiche all’invio di workflow comfy, al polling, ai download o alla registrazione del Plugin + - Esercita i percorsi dell'immagine, del video e di `music_generate` comfy inclusi + - Salta ogni capability a meno che `plugins.entries.comfy.config.` non sia configurato + - Utile dopo modifiche all'invio dei workflow comfy, al polling, ai download o alla registrazione del Plugin -## Generazione di immagini live +## Generazione di immagini in ambiente reale - Test: `test/image-generation.runtime.live.test.ts` - Comando: `pnpm test:live test/image-generation.runtime.live.test.ts` - Harness: `pnpm test:live:media image` - Ambito: - - Enumera ogni Plugin provider di generazione immagini registrato - - Carica le variabili env del provider mancanti dalla tua shell di login (`~/.profile`) prima della sonda - - Usa per impostazione predefinita le chiavi API live/env prima dei profili di autenticazione salvati, così le chiavi di test obsolete in `auth-profiles.json` non mascherano le credenziali reali della shell + - Enumera ogni Plugin provider di generazione di immagini registrato + - Carica le variabili d'ambiente del provider mancanti dalla tua shell di login (`~/.profile`) prima della sonda + - Usa per impostazione predefinita le chiavi API in ambiente reale/di ambiente prima dei profili di autenticazione salvati, così le chiavi di test obsolete in `auth-profiles.json` non mascherano le credenziali reali della shell - Salta i provider senza autenticazione/profilo/modello utilizzabile - - Esegue ogni provider configurato tramite il runtime condiviso di generazione immagini: + - Esegue ogni provider configurato tramite il runtime condiviso di generazione di immagini: - `:generate` - `:edit` quando il provider dichiara il supporto alla modifica - Provider inclusi attualmente coperti: @@ -468,15 +490,15 @@ Se vuoi fare affidamento sulle chiavi env (ad esempio esportate nel tuo `~/.prof - `openrouter` - `vydra` - `xai` -- Restringimento opzionale: +- Restrizione opzionale: - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google,openrouter,xai"` - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="deepinfra"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,openrouter/google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,openrouter:generate,xai:default-generate,xai:default-edit"` - Comportamento di autenticazione opzionale: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per forzare l’autenticazione dall’archivio profili e ignorare gli override solo env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per forzare l'autenticazione dall'archivio profili e ignorare gli override solo di ambiente -Per il percorso CLI rilasciato, aggiungi uno smoke `infer` dopo che il test live provider/runtime è passato: +Per il percorso CLI distribuito, aggiungi uno smoke `infer` dopo che il test in ambiente reale del provider/runtime è passato: ```bash OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_INFER_CLI_TEST=1 pnpm test:live -- test/image-generation.infer-cli.live.test.ts @@ -488,81 +510,81 @@ openclaw infer image generate \ --json ``` -Questo copre il parsing degli argomenti CLI, la risoluzione della configurazione/agente predefinito, l’attivazione del Plugin incluso, il runtime condiviso di generazione immagini e la richiesta live al provider. Le dipendenze del Plugin devono essere presenti prima del caricamento del runtime. +Questo copre il parsing degli argomenti CLI, la risoluzione configurazione/agente predefinito, l'attivazione del Plugin incluso, il runtime condiviso di generazione di immagini e la richiesta al provider in ambiente reale. Le dipendenze del Plugin devono essere presenti prima del caricamento runtime. -## Generazione musicale live +## Generazione di musica in ambiente reale - Test: `extensions/music-generation-providers.live.test.ts` - Abilita: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Ambito: - - Esercita il percorso condiviso del provider di generazione musicale incluso + - Esercita il percorso condiviso del provider incluso di generazione di musica - Attualmente copre Google e MiniMax - - Carica le variabili env del provider dalla tua shell di login (`~/.profile`) prima della sonda - - Usa per impostazione predefinita le chiavi API live/env prima dei profili di autenticazione salvati, così le chiavi di test obsolete in `auth-profiles.json` non mascherano le credenziali reali della shell + - Carica le variabili d'ambiente del provider dalla tua shell di login (`~/.profile`) prima della sonda + - Usa per impostazione predefinita le chiavi API in ambiente reale/di ambiente prima dei profili di autenticazione salvati, così le chiavi di test obsolete in `auth-profiles.json` non mascherano le credenziali reali della shell - Salta i provider senza autenticazione/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 lane condivisa: + - Copertura attuale del percorso condiviso: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: file live Comfy separato, non questo sweep condiviso -- Restringimento opzionale: + - `comfy`: file Comfy in ambiente reale separato, non questo sweep condiviso +- Restrizione opzionale: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.6"` - Comportamento di autenticazione opzionale: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per forzare l’autenticazione dall’archivio profili e ignorare gli override solo env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per forzare l'autenticazione dall'archivio profili e ignorare gli override solo di ambiente -## Generazione video live +## Generazione di video in ambiente reale - Test: `extensions/video-generation-providers.live.test.ts` - Abilita: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Ambito: - - Esercita il percorso condiviso del provider di generazione video incluso - - Per impostazione predefinita usa il percorso smoke sicuro per il rilascio: provider non FAL, una richiesta text-to-video per provider, prompt di un secondo con aragosta e un limite operativo 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` o `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` per eseguirlo esplicitamente - - Carica le variabili env del provider dalla tua shell di login (`~/.profile`) prima della sonda - - Usa per impostazione predefinita le chiavi API live/env prima dei profili di autenticazione salvati, così le chiavi di test obsolete in `auth-profiles.json` non mascherano le credenziali reali della shell + - Esercita il percorso condiviso del provider incluso di generazione di video + - Usa per impostazione predefinita il percorso smoke sicuro per le release: provider non FAL, una richiesta text-to-video per provider, prompt di un secondo con aragosta e un limite operativo per provider da `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` per impostazione predefinita) + - Salta FAL per impostazione predefinita perché la latenza della coda lato provider può dominare il tempo di release; passa `--video-providers fal` oppure `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` per eseguirlo esplicitamente + - Carica le variabili d'ambiente del provider dalla tua shell di login (`~/.profile`) prima della sonda + - Usa per impostazione predefinita le chiavi API in ambiente reale/di ambiente prima dei profili di autenticazione salvati, così le chiavi di test obsolete in `auth-profiles.json` non mascherano le credenziali reali della shell - Salta i provider senza autenticazione/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 - Provider `imageToVideo` attualmente dichiarati ma saltati nello sweep condiviso: - - `vydra` perché il `veo3` incluso è solo testo e il `kling` incluso richiede un URL immagine remoto - - Copertura specifica per provider Vydra: + - `vydra` perché `veo3` incluso è solo testo e `kling` incluso richiede un URL immagine remoto + - Copertura Vydra specifica per 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 lane `kling` che usa per impostazione predefinita una fixture URL immagine remota - - Copertura live attuale di `videoToVideo`: - - solo `runway` quando il modello selezionato è `runway/gen4_aleph` + - quel file esegue `veo3` text-to-video più un percorso `kling` che usa per impostazione predefinita una fixture URL immagine remota + - Copertura attuale `videoToVideo` in ambiente reale: + - `runway` solo quando il modello selezionato è `runway/gen4_aleph` - Provider `videoToVideo` attualmente dichiarati ma saltati nello sweep condiviso: - `alibaba`, `qwen`, `xai` perché quei percorsi attualmente richiedono URL di riferimento remoti `http(s)` / MP4 - - `google` perché la lane condivisa Gemini/Veo attuale usa input locale basato su buffer e quel percorso non è accettato nello sweep condiviso - - `openai` perché la lane condivisa attuale non ha garanzie di accesso specifiche per org a video inpaint/remix -- Restringimento opzionale: + - `google` perché l'attuale percorso Gemini/Veo condiviso usa input locale basato su buffer e quel percorso non è accettato nello sweep condiviso + - `openai` perché l'attuale percorso condiviso non ha garanzie di accesso a inpaint/remix video specifiche per organizzazione +- Restrizione opzionale: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="deepinfra,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 operativo di ciascun provider per una smoke run aggressiva + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` per ridurre il limite di ogni operazione provider per uno smoke aggressivo - Comportamento di autenticazione opzionale: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per forzare l’autenticazione dall’archivio profili e ignorare gli override solo env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` per forzare l'autenticazione dall'archivio profili e ignorare gli override solo di ambiente -## Harness media live +## Harness media in ambiente reale - Comando: `pnpm test:live:media` - Scopo: - - Esegue le suite live condivise di immagini, musica e video tramite un unico entrypoint nativo del repo - - Carica automaticamente le variabili env del provider mancanti da `~/.profile` - - Restringe automaticamente per impostazione predefinita ciascuna suite ai provider che attualmente hanno un’autenticazione utilizzabile - - Riusa `scripts/test-live.mjs`, così il comportamento di Heartbeat e modalità silenziosa resta coerente + - Esegue le suite condivise in ambiente reale per immagini, musica e video tramite un unico punto di ingresso nativo del repo + - Carica automaticamente le variabili d'ambiente del provider mancanti da `~/.profile` + - Restringe automaticamente per impostazione predefinita ogni suite ai provider che attualmente hanno autenticazione utilizzabile + - Riutilizza `scripts/test-live.mjs`, quindi il comportamento di Heartbeat e quiet mode resta coerente - Esempi: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Correlati +## Correlato - [Testing](/it/help/testing) — suite unit, di integrazione, QA e Docker diff --git a/docs/it/plugins/hooks.md b/docs/it/plugins/hooks.md index 90ccc5d3e..b928bcf84 100644 --- a/docs/it/plugins/hooks.md +++ b/docs/it/plugins/hooks.md @@ -1,30 +1,30 @@ --- read_when: - - Stai sviluppando un Plugin che richiede before_tool_call, before_agent_reply, hook di messaggio o hook del ciclo di vita - - È necessario bloccare, riscrivere o richiedere l’approvazione per le chiamate agli strumenti da parte di un Plugin - - Stai scegliendo tra hook interni e hook Plugin -summary: 'Hook dei Plugin: intercetta gli eventi del ciclo di vita di agente, strumento, messaggio, sessione e Gateway' -title: Agganci dei Plugin + - Stai sviluppando un Plugin che necessita di before_tool_call, before_agent_reply, hook di messaggio o hook del ciclo di vita + - Devi bloccare, riscrivere o richiedere l'approvazione per le chiamate agli strumenti da un plugin + - Stai scegliendo tra hook interni e hook del Plugin +summary: 'Hook dei Plugin: intercettano gli eventi del ciclo di vita dell''agente, dello strumento, del messaggio, della sessione e del Gateway' +title: Hook dei Plugin x-i18n: - generated_at: "2026-05-03T21:38:50Z" + generated_at: "2026-05-04T18:24:02Z" model: gpt-5.5 provider: openai - source_hash: 2c4ed060f1b89917e1f2f46d2da9448cd562edbcd6ce03bc9b1a83da3ed9a591 + source_hash: 37c7273036463c87e478db5678822b676c89447caee65f2f3f47a45194d1e37b source_path: plugins/hooks.md workflow: 16 --- -Gli hook dei Plugin sono punti di estensione in-process per i Plugin OpenClaw. Usali -quando un Plugin deve ispezionare o modificare esecuzioni degli agenti, chiamate di strumenti, flusso dei messaggi, -ciclo di vita delle sessioni, instradamento dei subagent, installazioni o avvio del Gateway. +Gli hook dei Plugin sono punti di estensione in-process per i plugin OpenClaw. Usali +quando un plugin deve ispezionare o modificare esecuzioni degli agenti, chiamate agli strumenti, flusso dei messaggi, +ciclo di vita delle sessioni, instradamento dei subagenti, installazioni o avvio del Gateway. Usa invece gli [hook interni](/it/automation/hooks) quando vuoi un piccolo -script `HOOK.md` installato dall'operatore per eventi di comando e del Gateway come +script `HOOK.md` installato dall'operatore per eventi di comandi e Gateway come `/new`, `/reset`, `/stop`, `agent:bootstrap` o `gateway:startup`. ## Avvio rapido -Registra hook di Plugin tipizzati con `api.on(...)` dall'entrypoint del tuo Plugin: +Registra hook di plugin tipizzati con `api.on(...)` dal punto di ingresso del tuo plugin: ```typescript import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; @@ -56,19 +56,19 @@ export default definePluginEntry({ }); ``` -I gestori degli hook vengono eseguiti in sequenza in ordine decrescente di `priority`. Gli hook con la stessa priorità -mantengono l'ordine di registrazione. +I gestori degli hook vengono eseguiti in sequenza in ordine decrescente di `priority`. Gli hook +con la stessa priorità mantengono l'ordine di registrazione. `api.on(name, handler, opts?)` accetta: -- `priority` — ordinamento del gestore (i valori più alti vengono eseguiti per primi). -- `timeoutMs` — budget opzionale per hook. Quando è impostato, il runner degli hook interrompe quel - gestore dopo che il budget è trascorso e continua con quello successivo, invece di - lasciare che una configurazione lenta o un lavoro di richiamo consumino il timeout del modello - configurato dal chiamante. Omettilo per usare il timeout predefinito di osservazione/decisione che il +- `priority` — ordinamento dei gestori (i valori più alti vengono eseguiti per primi). +- `timeoutMs` — budget facoltativo per singolo hook. Quando impostato, il runner degli hook interrompe quel + gestore allo scadere del budget e continua con il successivo, invece di + lasciare che un setup lento o un lavoro di richiamo consumi il timeout del modello configurato dal chiamante. + Omettilo per usare il timeout predefinito di osservazione/decisione che il runner degli hook applica in modo generico. -Gli operatori possono anche impostare budget degli hook senza modificare il codice del Plugin: +Gli operatori possono anche impostare budget degli hook senza modificare il codice del plugin: ```json { @@ -89,54 +89,54 @@ Gli operatori possono anche impostare budget degli hook senza modificare il codi ``` `hooks.timeouts.` sovrascrive `hooks.timeoutMs`, che sovrascrive il -valore `api.on(..., { timeoutMs })` definito dall'autore del Plugin. Ogni valore configurato deve -essere un intero positivo non superiore a 600000 millisecondi. Preferisci -sovrascritture per singolo hook per gli hook notoriamente lenti, così un Plugin non ottiene un budget più lungo +valore `api.on(..., { timeoutMs })` scritto dall'autore del plugin. Ogni valore configurato deve +essere un intero positivo non superiore a 600000 millisecondi. Preferisci override per singolo hook +per gli hook notoriamente lenti, così un plugin non ottiene un budget più lungo ovunque. Ogni hook riceve `event.context.pluginConfig`, la configurazione risolta per il -Plugin che ha registrato quel gestore. Usala per decisioni degli hook che richiedono -le opzioni correnti del Plugin; OpenClaw la inietta per ciascun gestore senza mutare -l'oggetto evento condiviso visto dagli altri Plugin. +plugin che ha registrato quel gestore. Usala per decisioni degli hook che richiedono +le opzioni correnti del plugin; OpenClaw la inietta per gestore senza mutare +l'oggetto evento condiviso visto dagli altri plugin. ## Catalogo degli hook Gli hook sono raggruppati in base alla superficie che estendono. I nomi in **grassetto** accettano un -risultato decisionale (blocco, annullamento, sovrascrittura o richiesta di approvazione); tutti gli altri sono +risultato decisionale (blocco, annullamento, override o richiesta di approvazione); tutti gli altri sono solo di osservazione. **Turno dell'agente** -- `before_model_resolve` — sovrascrive provider o modello prima che i messaggi di sessione vengano caricati -- `agent_turn_prepare` — consuma le iniezioni di turno del Plugin accodate e aggiunge contesto dello stesso turno prima degli hook del prompt +- `before_model_resolve` — sovrascrive provider o modello prima che i messaggi della sessione vengano caricati +- `agent_turn_prepare` — consuma le iniezioni di turno dei plugin in coda e aggiunge contesto nello stesso turno prima degli hook del prompt - `before_prompt_build` — aggiunge contesto dinamico o testo del prompt di sistema prima della chiamata al modello - `before_agent_start` — fase combinata solo per compatibilità; preferisci i due hook sopra -- **`before_agent_reply`** — interrompe il turno del modello con una risposta sintetica o silenzio -- **`before_agent_finalize`** — ispeziona la risposta finale naturale e richiede un ulteriore passaggio del modello +- **`before_agent_reply`** — interrompe il turno del modello con una risposta sintetica o con silenzio +- **`before_agent_finalize`** — ispeziona la risposta finale naturale e richiede un altro passaggio del modello - `agent_end` — osserva messaggi finali, stato di successo e durata dell'esecuzione -- `heartbeat_prompt_contribution` — aggiunge contesto solo Heartbeat per Plugin di monitoraggio in background e ciclo di vita +- `heartbeat_prompt_contribution` — aggiunge contesto solo heartbeat per monitor in background e plugin del ciclo di vita **Osservazione della conversazione** -- `model_call_started` / `model_call_ended` — osserva metadati sanificati di chiamata provider/modello, tempistiche, esito e hash limitati degli ID richiesta senza contenuto di prompt o risposta +- `model_call_started` / `model_call_ended` — osserva metadati sanificati della chiamata provider/modello, tempi, esito e hash limitati degli ID richiesta senza contenuto di prompt o risposta - `llm_input` — osserva l'input del provider (prompt di sistema, prompt, cronologia) - `llm_output` — osserva l'output del provider **Strumenti** - **`before_tool_call`** — riscrive i parametri dello strumento, blocca l'esecuzione o richiede approvazione -- `after_tool_call` — osserva risultati degli strumenti, errori e durata +- `after_tool_call` — osserva risultati dello strumento, errori e durata - **`tool_result_persist`** — riscrive il messaggio dell'assistente prodotto da un risultato dello strumento - **`before_message_write`** — ispeziona o blocca una scrittura di messaggio in corso (raro) **Messaggi e consegna** -- **`inbound_claim`** — rivendica un messaggio in ingresso prima dell'instradamento all'agente (risposte sintetiche) +- **`inbound_claim`** — rivendica un messaggio in ingresso prima dell'instradamento dell'agente (risposte sintetiche) - `message_received` — osserva contenuto in ingresso, mittente, thread e metadati -- **`message_sending`** — riscrive contenuto in uscita o annulla la consegna -- `message_sent` — osserva successo o errore della consegna in uscita -- **`before_dispatch`** — ispeziona o riscrive un dispatch in uscita prima del passaggio al canale -- **`reply_dispatch`** — partecipa alla pipeline finale di dispatch della risposta +- **`message_sending`** — riscrive il contenuto in uscita o annulla la consegna +- `message_sent` — osserva successo o fallimento della consegna in uscita +- **`before_dispatch`** — ispeziona o riscrive un invio in uscita prima del passaggio al canale +- **`reply_dispatch`** — partecipa alla pipeline finale di invio della risposta **Sessioni e Compaction** @@ -144,26 +144,26 @@ solo di osservazione. - `before_compaction` / `after_compaction` — osserva o annota i cicli di Compaction - `before_reset` — osserva eventi di reset della sessione (`/reset`, reset programmatici) -**Subagent** +**Subagenti** -- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` — coordina l'instradamento dei subagent e la consegna del completamento +- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` — coordina instradamento dei subagenti e consegna del completamento **Ciclo di vita** -- `gateway_start` / `gateway_stop` — avvia o arresta servizi di proprietà del Plugin con il Gateway -- `cron_changed` — osserva modifiche del ciclo di vita dei cron di proprietà del gateway (aggiunto, aggiornato, rimosso, avviato, terminato, pianificato) -- **`before_install`** — ispeziona scansioni di installazione di Skills o Plugin e opzionalmente blocca +- `gateway_start` / `gateway_stop` — avvia o arresta servizi di proprietà del plugin con il Gateway +- `cron_changed` — osserva modifiche del ciclo di vita dei Cron di proprietà del gateway (aggiunto, aggiornato, rimosso, avviato, terminato, pianificato) +- **`before_install`** — ispeziona scansioni di installazione di skill o plugin e, facoltativamente, blocca -## Criteri per le chiamate degli strumenti +## Criterio per le chiamate agli strumenti `before_tool_call` riceve: - `event.toolName` - `event.params` -- `event.runId` opzionale -- `event.toolCallId` opzionale +- `event.runId` facoltativo +- `event.toolCallId` facoltativo - campi di contesto come `ctx.agentId`, `ctx.sessionKey`, `ctx.sessionId`, - `ctx.runId`, `ctx.jobId` (impostato nelle esecuzioni guidate da Cron) e `ctx.trace` diagnostico + `ctx.runId`, `ctx.jobId` (impostato sulle esecuzioni guidate da Cron) e `ctx.trace` diagnostico Può restituire: @@ -188,88 +188,103 @@ type BeforeToolCallResult = { Regole: -- `block: true` è terminale e salta i gestori a priorità inferiore. +- `block: true` è terminale e salta i gestori con priorità più bassa. - `block: false` viene trattato come nessuna decisione. - `params` riscrive i parametri dello strumento per l'esecuzione. -- `requireApproval` mette in pausa l'esecuzione dell'agente e chiede all'utente tramite le - approvazioni dei Plugin. Il comando `/approve` può approvare sia exec sia le approvazioni dei Plugin. -- Un `block: true` a priorità inferiore può ancora bloccare dopo che un hook a priorità superiore - ha richiesto approvazione. +- `requireApproval` mette in pausa l'esecuzione dell'agente e chiede all'utente tramite le approvazioni dei plugin. Il comando `/approve` può approvare sia approvazioni exec sia approvazioni di plugin. +- Un `block: true` con priorità più bassa può comunque bloccare dopo che un hook con priorità più alta + ha richiesto l'approvazione. - `onResolution` riceve la decisione di approvazione risolta — `allow-once`, `allow-always`, `deny`, `timeout` o `cancelled`. -I Plugin in bundle che richiedono criteri a livello host possono registrare criteri di strumenti attendibili -con `api.registerTrustedToolPolicy(...)`. Questi vengono eseguiti prima dei normali hook -`before_tool_call` e prima delle decisioni dei Plugin esterni. Usali solo -per gate attendibili dall'host come criteri dell'area di lavoro, applicazione del budget o -sicurezza dei workflow riservati. I Plugin esterni dovrebbero usare i normali hook `before_tool_call`. +I plugin inclusi che necessitano di criteri a livello host possono registrare criteri attendibili per gli strumenti +con `api.registerTrustedToolPolicy(...)`. Questi vengono eseguiti prima dei normali +hook `before_tool_call` e prima delle decisioni dei plugin esterni. Usali solo +per gate attendibili dall'host, come criteri dell'area di lavoro, applicazione del budget o +sicurezza dei workflow riservati. I plugin esterni dovrebbero usare i normali hook `before_tool_call`. ### Persistenza dei risultati degli strumenti -I risultati degli strumenti possono includere `details` strutturati per rendering dell'interfaccia, diagnostica, -instradamento dei media o metadati di proprietà del Plugin. Tratta `details` come metadati di runtime, +I risultati degli strumenti possono includere `details` strutturati per rendering UI, diagnostica, +instradamento dei media o metadati di proprietà del plugin. Tratta `details` come metadati runtime, non come contenuto del prompt: -- OpenClaw rimuove `toolResult.details` prima del replay del provider e dell'input di Compaction +- OpenClaw rimuove `toolResult.details` prima del replay verso il provider e dell'input di Compaction così i metadati non diventano contesto del modello. -- Le voci di sessione persistite mantengono solo `details` limitati. I details troppo grandi vengono +- Le voci di sessione persistite mantengono solo `details` limitati. I dettagli troppo grandi vengono sostituiti con un riepilogo compatto e `persistedDetailsTruncated: true`. - `tool_result_persist` e `before_message_write` vengono eseguiti prima del limite finale di - persistenza. Gli hook dovrebbero comunque mantenere piccoli i `details` restituiti ed evitare di - mettere testo rilevante per il prompt solo in `details`; inserisci l'output dello strumento visibile al modello + persistenza. Gli hook dovrebbero comunque mantenere piccoli i `details` restituiti ed evitare + di inserire testo rilevante per il prompt solo in `details`; inserisci l'output dello strumento visibile al modello in `content`. -## Hook di prompt e modello +## Hook per prompt e modello -Usa gli hook specifici per fase per i nuovi Plugin: +Usa gli hook specifici di fase per i nuovi plugin: - `before_model_resolve`: riceve solo il prompt corrente e i metadati degli allegati. - Restituisci `providerOverride` o `modelOverride`. + Restituisce `providerOverride` o `modelOverride`. - `agent_turn_prepare`: riceve il prompt corrente, i messaggi di sessione preparati - e qualsiasi iniezione accodata esattamente una volta svuotata per questa sessione. Restituisci + e tutte le iniezioni in coda exactly-once scaricate per questa sessione. Restituisce `prependContext` o `appendContext`. - `before_prompt_build`: riceve il prompt corrente e i messaggi di sessione. - Restituisci `prependContext`, `appendContext`, `systemPrompt`, + Restituisce `prependContext`, `appendContext`, `systemPrompt`, `prependSystemContext` o `appendSystemContext`. -- `heartbeat_prompt_contribution`: viene eseguito solo per i turni Heartbeat e restituisce +- `heartbeat_prompt_contribution`: viene eseguito solo per i turni heartbeat e restituisce `prependContext` o `appendContext`. È pensato per monitor in background - che devono riepilogare lo stato corrente senza modificare i turni avviati dall'utente. + che devono riassumere lo stato corrente senza modificare turni avviati dall'utente. -`before_agent_start` resta disponibile per compatibilità. Preferisci gli hook espliciti sopra -così il tuo Plugin non dipende da una fase combinata legacy. +`before_agent_start` rimane per compatibilità. Preferisci gli hook espliciti sopra +così il tuo plugin non dipende da una fase combinata legacy. `before_agent_start` e `agent_end` includono `event.runId` quando OpenClaw può identificare l'esecuzione attiva. Lo stesso valore è disponibile anche in `ctx.runId`. -Le esecuzioni guidate da Cron espongono anche `ctx.jobId` (l'ID del job Cron di origine) così -gli hook dei Plugin possono limitare metriche, effetti collaterali o stato a uno specifico job +Le esecuzioni guidate da Cron espongono anche `ctx.jobId` (l'ID del job Cron originario) così +gli hook dei plugin possono limitare metriche, effetti collaterali o stato a uno specifico job pianificato. Per le esecuzioni originate da canale, `ctx.messageProvider` è la superficie del provider come -`discord` o `telegram`, mentre `ctx.channelId` è l'identificatore del target della conversazione -quando OpenClaw può derivarne uno dalla chiave di sessione o dai metadati di consegna. +`discord` o `telegram`, mentre `ctx.channelId` è l'identificatore della destinazione della conversazione +quando OpenClaw può ricavarne uno dalla chiave di sessione o dai metadati di consegna. `agent_end` è un hook di osservazione e viene eseguito fire-and-forget dopo il turno. Il -runner degli hook applica un timeout di 30 secondi così un Plugin bloccato o un endpoint -di embedding non può lasciare la promise dell'hook in sospeso per sempre. Un timeout viene registrato e -OpenClaw continua; non annulla il lavoro di rete di proprietà del Plugin a meno che il -Plugin non usi anche il proprio segnale di abort. +runner degli hook applica un timeout di 30 secondi così un plugin bloccato o un endpoint +di embedding non può lasciare la promise dell'hook in sospeso per sempre. Un timeout viene registrato nei log e +OpenClaw continua; non annulla il lavoro di rete di proprietà del plugin a meno che +il plugin non usi anche un proprio segnale di abort. -Usa `model_call_started` e `model_call_ended` per telemetria delle chiamate provider -che non dovrebbe ricevere prompt grezzi, cronologia, risposte, intestazioni, corpi delle richieste +Usa `model_call_started` e `model_call_ended` per telemetria delle chiamate al provider +che non dovrebbe ricevere prompt grezzi, cronologia, risposte, header, corpi delle richieste o ID richiesta del provider. Questi hook includono metadati stabili come -`runId`, `callId`, `provider`, `model`, `api`/`transport` opzionali, elementi terminali -`durationMs`/`outcome` e `upstreamRequestIdHash` quando OpenClaw può derivare un -hash limitato dell'ID richiesta del provider. +`runId`, `callId`, `provider`, `model`, `api`/`transport` facoltativi, `durationMs`/`outcome` terminali +e `upstreamRequestIdHash` quando OpenClaw può derivare un hash limitato dell'ID richiesta +del provider. `before_agent_finalize` viene eseguito solo quando un harness sta per accettare una risposta finale naturale -dell'assistente. Non è il percorso di annullamento `/stop` e non viene -eseguito quando l'utente interrompe un turno. Restituisci `{ action: "revise", reason }` per chiedere -all'harness un ulteriore passaggio del modello prima della finalizzazione, `{ action: +dell'assistente. Non è il percorso di annullamento `/stop` e non viene eseguito +quando l'utente interrompe un turno. Restituisci `{ action: "revise", reason }` per chiedere +all'harness un altro passaggio del modello prima della finalizzazione, `{ action: "finalize", reason? }` per forzare la finalizzazione, oppure ometti un risultato per continuare. -Gli hook `Stop` nativi di Codex vengono inoltrati in questo hook come decisioni OpenClaw -`before_agent_finalize`. +Gli hook `Stop` nativi di Codex vengono inoltrati in questo hook come decisioni +`before_agent_finalize` di OpenClaw. -I Plugin non in bundle che richiedono `llm_input`, `llm_output`, +Quando restituiscono `action: "revise"`, i plugin possono includere metadati `retry` per rendere +il passaggio extra del modello limitato e sicuro per il replay: + +```typescript +type BeforeAgentFinalizeRetry = { + instruction: string; + idempotencyKey?: string; + maxAttempts?: number; +}; +``` + +`instruction` viene aggiunta al motivo di revisione inviato all'harness. +`idempotencyKey` consente all'host di contare i retry per la stessa richiesta del plugin tra +decisioni di finalizzazione equivalenti, e `maxAttempts` limita quanti passaggi extra +l'host permetterà prima di continuare con la risposta finale naturale. + +I plugin non inclusi che necessitano di `llm_input`, `llm_output`, `before_agent_finalize` o `agent_end` devono impostare: ```json @@ -286,20 +301,30 @@ I Plugin non in bundle che richiedono `llm_input`, `llm_output`, } ``` -Gli hook che modificano il prompt e le iniezioni durevoli al turno successivo possono essere disabilitati per Plugin +Gli hook che mutano il prompt e le iniezioni durevoli per il turno successivo possono essere disabilitati per plugin con `plugins.entries..hooks.allowPromptInjection=false`. -### Estensioni di sessione e iniezioni al turno successivo +### Estensioni di sessione e iniezioni per il turno successivo -I Plugin di workflow possono persistere piccoli stati di sessione compatibili con JSON con -`api.registerSessionExtension(...)` e aggiornarli tramite il metodo Gateway -`sessions.pluginPatch`. Le righe di sessione proiettano lo stato delle estensioni registrate -tramite `pluginExtensions`, consentendo alla Control UI e ad altri client di renderizzare -lo stato di proprietà del Plugin senza conoscere gli interni del Plugin. +I plugin di workflow possono rendere persistente un piccolo stato di sessione compatibile con JSON con +`api.registerSessionExtension(...)` e aggiornarlo tramite il metodo +`sessions.pluginPatch` del Gateway. Le righe di sessione proiettano lo stato dell'estensione registrata +tramite `pluginExtensions`, consentendo alla Control UI e ad altri client di visualizzare +lo stato di proprietà del plugin senza conoscere gli interni del plugin. -Usa `api.enqueueNextTurnInjection(...)` quando un plugin ha bisogno che un contesto durevole raggiunga il turno successivo del modello esattamente una volta. OpenClaw svuota le injection accodate prima dei prompt hook, elimina le injection scadute e deduplica per `idempotencyKey` per plugin. Questo è il punto di integrazione corretto per riprese di approvazione, riepiloghi di policy, delta dei monitor in background e continuazioni di comandi che devono essere visibili al modello al turno successivo ma non devono diventare testo permanente del prompt di sistema. +Usa `api.enqueueNextTurnInjection(...)` quando un plugin ha bisogno che un contesto durevole +raggiunga esattamente una volta il turno successivo del modello. OpenClaw svuota le injection in coda prima +degli hook del prompt, elimina le injection scadute e deduplica per `idempotencyKey` +per plugin. Questo è il seam corretto per riprese di approvazioni, riepiloghi di policy, +delta di monitor in background e continuazioni di comandi che devono essere visibili al +modello nel turno successivo ma non devono diventare testo permanente del prompt di sistema. -Le semantiche di cleanup fanno parte del contratto. Il cleanup delle estensioni di sessione e le callback di cleanup del ciclo di vita runtime ricevono `reset`, `delete`, `disable` o `restart`. L'host rimuove lo stato persistente dell'estensione di sessione del plugin proprietario e le injection next-turn in sospeso per reset/delete/disable; restart mantiene lo stato durevole della sessione mentre le callback di cleanup consentono ai plugin di rilasciare job dello scheduler, contesto di esecuzione e altre risorse fuori banda per la vecchia generazione runtime. +Le semantiche di pulizia fanno parte del contratto. La pulizia delle estensioni di sessione e +le callback di pulizia del ciclo di vita del runtime ricevono `reset`, `delete`, `disable` o +`restart`. L'host rimuove lo stato persistente dell'estensione di sessione del plugin proprietario +e le injection del turno successivo in sospeso per reset/delete/disable; restart mantiene +lo stato durevole della sessione mentre le callback di pulizia consentono ai plugin di rilasciare job dello scheduler, +contesto di esecuzione e altre risorse out-of-band per la vecchia generazione del runtime. ## Hook dei messaggi @@ -307,14 +332,18 @@ Usa gli hook dei messaggi per routing a livello di canale e policy di consegna: - `message_received`: osserva contenuto in ingresso, mittente, `threadId`, `messageId`, `senderId`, correlazione opzionale di run/sessione e metadati. -- `message_sending`: riscrivi `content` o restituisci `{ cancel: true }`. +- `message_sending`: riscrive `content` o restituisce `{ cancel: true }`. - `message_sent`: osserva successo o errore finale. -Per le risposte TTS solo audio, `content` può contenere la trascrizione parlata nascosta anche quando il payload del canale non ha testo/didascalia visibile. Riscrivere quel `content` aggiorna solo la trascrizione visibile agli hook; non viene renderizzata come didascalia multimediale. +Per risposte TTS solo audio, `content` può contenere la trascrizione parlata nascosta +anche quando il payload del canale non ha testo/caption visibile. Riscrivere quel +`content` aggiorna solo la trascrizione visibile all'hook; non viene renderizzata come +caption multimediale. I contesti degli hook dei messaggi espongono campi di correlazione stabili quando disponibili: `ctx.sessionKey`, `ctx.runId`, `ctx.messageId`, `ctx.senderId`, `ctx.trace`, -`ctx.traceId`, `ctx.spanId`, `ctx.parentSpanId` e `ctx.callDepth`. Preferisci questi campi di prima classe prima di leggere i metadati legacy. +`ctx.traceId`, `ctx.spanId`, `ctx.parentSpanId` e `ctx.callDepth`. Preferisci +questi campi first-class prima di leggere i metadati legacy. Preferisci i campi tipizzati `threadId` e `replyToId` prima di usare metadati specifici del canale. @@ -322,43 +351,61 @@ Regole decisionali: - `message_sending` con `cancel: true` è terminale. - `message_sending` con `cancel: false` viene trattato come nessuna decisione. -- Il `content` riscritto continua verso gli hook a priorità inferiore a meno che un hook successivo annulli la consegna. +- Il `content` riscritto continua verso gli hook con priorità inferiore, a meno che un hook successivo + annulli la consegna. ## Hook di installazione -`before_install` viene eseguito dopo la scansione integrata per le installazioni di Skills e plugin. Restituisci risultati aggiuntivi o `{ block: true, blockReason }` per interrompere l'installazione. +`before_install` viene eseguito dopo la scansione integrata per le installazioni di skill e plugin. +Restituisci risultati aggiuntivi o `{ block: true, blockReason }` per interrompere +l'installazione. `block: true` è terminale. `block: false` viene trattato come nessuna decisione. ## Ciclo di vita del Gateway -Usa `gateway_start` per i servizi dei plugin che richiedono stato di proprietà del Gateway. Il contesto espone `ctx.config`, `ctx.workspaceDir` e `ctx.getCron?.()` per ispezioni e aggiornamenti cron. Usa `gateway_stop` per ripulire risorse a lunga esecuzione. +Usa `gateway_start` per i servizi dei plugin che hanno bisogno di stato di proprietà del Gateway. Il +contesto espone `ctx.config`, `ctx.workspaceDir` e `ctx.getCron?.()` per +ispezione e aggiornamenti del cron. Usa `gateway_stop` per pulire le risorse a lunga esecuzione. -Non fare affidamento sull'hook interno `gateway:startup` per servizi runtime di proprietà del plugin. +Non fare affidamento sull'hook interno `gateway:startup` per i servizi runtime di proprietà del plugin. -`cron_changed` viene emesso per eventi del ciclo di vita cron di proprietà del gateway con un payload evento tipizzato che copre i motivi `added`, `updated`, `removed`, `started`, `finished` e `scheduled`. L'evento trasporta uno snapshot `PluginHookGatewayCronJob` (inclusi `state.nextRunAtMs`, `state.lastRunStatus` e `state.lastError` quando presenti) più un `PluginHookGatewayCronDeliveryStatus` di `not-requested` | `delivered` | `not-delivered` | `unknown`. Gli eventi rimossi trasportano comunque lo snapshot del job eliminato così che gli scheduler esterni possano riconciliare lo stato. Usa `ctx.getCron?.()` e `ctx.config` dal contesto runtime quando sincronizzi scheduler di risveglio esterni e mantieni OpenClaw come fonte di verità per i controlli di scadenza e l'esecuzione. +`cron_changed` scatta per eventi del ciclo di vita del cron di proprietà del Gateway con un payload +di evento tipizzato che copre i motivi `added`, `updated`, `removed`, `started`, `finished` +e `scheduled`. L'evento trasporta uno snapshot `PluginHookGatewayCronJob` +(inclusi `state.nextRunAtMs`, `state.lastRunStatus` e +`state.lastError` quando presenti) più un `PluginHookGatewayCronDeliveryStatus` +di `not-requested` | `delivered` | `not-delivered` | `unknown`. Gli eventi rimossi +trasportano comunque lo snapshot del job eliminato, così gli scheduler esterni possono +riconciliare lo stato. Usa `ctx.getCron?.()` e `ctx.config` dal contesto del runtime +quando sincronizzi scheduler di risveglio esterni, e mantieni OpenClaw come +fonte di verità per controlli di scadenza ed esecuzione. ## Deprecazioni imminenti -Alcune superfici adiacenti agli hook sono deprecate ma ancora supportate. Migra prima della prossima major release: +Alcune superfici adiacenti agli hook sono deprecate ma ancora supportate. Migra +prima della prossima major release: -- **Envelope dei canali in testo normale** nei gestori `inbound_claim` e `message_received`. - Leggi `BodyForAgent` e i blocchi strutturati del contesto utente invece di analizzare testo di envelope piatto. Vedi - [Envelope dei canali in testo normale → BodyForAgent](/it/plugins/sdk-migration#active-deprecations). +- **Envelope di canale in testo semplice** negli handler `inbound_claim` e `message_received`. + Leggi `BodyForAgent` e i blocchi strutturati del contesto utente + invece di analizzare testo envelope piatto. Vedi + [Envelope di canale in testo semplice → BodyForAgent](/it/plugins/sdk-migration#active-deprecations). - **`before_agent_start`** rimane per compatibilità. I nuovi plugin dovrebbero usare `before_model_resolve` e `before_prompt_build` invece della fase combinata. -- **`onResolution` in `before_tool_call`** ora usa l'union tipizzata +- **`onResolution` in `before_tool_call`** ora usa l'unione tipizzata `PluginApprovalResolution` (`allow-once` / `allow-always` / `deny` / `timeout` / `cancelled`) invece di una `string` libera. -Per l'elenco completo — registrazione delle capability di memoria, profilo di ragionamento del provider, provider di autenticazione esterni, tipi di discovery dei provider, accessor del runtime task e la rinomina `command-auth` → `command-status` — vedi -[Migrazione del Plugin SDK → Deprecazioni attive](/it/plugins/sdk-migration#active-deprecations). +Per l'elenco completo — registrazione della capability di memoria, profilo di thinking del provider, +provider di autenticazione esterni, tipi di discovery dei provider, accessor del runtime dei task +e la rinomina da `command-auth` a `command-status` — vedi +[Migrazione Plugin SDK → Deprecazioni attive](/it/plugins/sdk-migration#active-deprecations). ## Correlati -- [Migrazione del Plugin SDK](/it/plugins/sdk-migration) — deprecazioni attive e timeline di rimozione +- [Migrazione Plugin SDK](/it/plugins/sdk-migration) — deprecazioni attive e timeline di rimozione - [Creare plugin](/it/plugins/building-plugins) -- [Panoramica del Plugin SDK](/it/plugins/sdk-overview) +- [Panoramica Plugin SDK](/it/plugins/sdk-overview) - [Entry point dei plugin](/it/plugins/sdk-entrypoints) - [Hook interni](/it/automation/hooks) - [Interni dell'architettura dei plugin](/it/plugins/architecture-internals) diff --git a/docs/it/plugins/sdk-overview.md b/docs/it/plugins/sdk-overview.md index 693865163..271c95607 100644 --- a/docs/it/plugins/sdk-overview.md +++ b/docs/it/plugins/sdk-overview.md @@ -1,32 +1,32 @@ --- read_when: - È necessario sapere da quale sottopercorso dell'SDK importare - - Vuoi una documentazione di riferimento per tutti i metodi di registrazione per OpenClawPluginApi + - Vuoi un riferimento per tutti i metodi di registrazione di OpenClawPluginApi - Stai cercando un'esportazione specifica dell'SDK sidebarTitle: Plugin SDK overview -summary: Mappa di importazione, riferimento dell'API di registrazione e architettura dell'SDK -title: Panoramica del Plugin SDK +summary: Mappa di importazione, riferimento API di registrazione e architettura dell'SDK +title: Panoramica dell'SDK Plugin x-i18n: - generated_at: "2026-05-02T08:30:59Z" + generated_at: "2026-05-04T18:24:48Z" model: gpt-5.5 provider: openai - source_hash: be5fa531e603fb6d87f84e3193ebd61be1431b57b8f284871ae15f34ca93fc69 + source_hash: 8187e7d4cfb9d6fb19bbdebfbaea0bb4d98fa5cea4742d0f82a765ae5bc60127 source_path: plugins/sdk-overview.md workflow: 16 --- -L'SDK Plugin è il contratto tipizzato tra plugin e core. Questa pagina è il +L'SDK per plugin è il contratto tipizzato tra i plugin e il nucleo. Questa pagina è il riferimento per **cosa importare** e **cosa puoi registrare**. - Questa pagina è per gli autori di plugin che usano `openclaw/plugin-sdk/*` dentro + Questa pagina è destinata agli autori di plugin che usano `openclaw/plugin-sdk/*` dentro OpenClaw. Per app esterne, script, dashboard, job CI ed estensioni IDE che vogliono eseguire agenti tramite il Gateway, usa invece [OpenClaw App SDK](/it/concepts/openclaw-sdk) e il pacchetto `@openclaw/sdk`. -Cerchi invece una guida pratica? Inizia con [Creare plugin](/it/plugins/building-plugins), usa [Plugin di canale](/it/plugins/sdk-channel-plugins) per i plugin di canale, [Plugin provider](/it/plugins/sdk-provider-plugins) per i plugin provider e [Hook dei Plugin](/it/plugins/hooks) per plugin di hook degli strumenti o del ciclo di vita. +Cerchi invece una guida pratica? Inizia con [Creare plugin](/it/plugins/building-plugins), usa [Plugin di canale](/it/plugins/sdk-channel-plugins) per i plugin di canale, [Plugin provider](/it/plugins/sdk-provider-plugins) per i plugin provider e [Hook dei plugin](/it/plugins/hooks) per i plugin di hook di strumenti o ciclo di vita. ## Convenzione di importazione @@ -39,159 +39,165 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` Ogni sottopercorso è un modulo piccolo e autonomo. Questo mantiene rapido l'avvio e -previene problemi di dipendenze circolari. Per gli helper di entry/build specifici -del canale, preferisci `openclaw/plugin-sdk/channel-core`; mantieni -`openclaw/plugin-sdk/core` per la superficie ombrello più ampia e gli helper -condivisi come `buildChannelConfigSchema`. +previene problemi di dipendenze circolari. Per helper di entry/build specifici del canale, +preferisci `openclaw/plugin-sdk/channel-core`; conserva `openclaw/plugin-sdk/core` per +la superficie ombrello più ampia e gli helper condivisi come +`buildChannelConfigSchema`. -Per la configurazione del canale, pubblica lo JSON Schema di proprietà del canale tramite +Per la configurazione del canale, pubblica il JSON Schema di proprietà del canale tramite `openclaw.plugin.json#channelConfigs`. Il sottopercorso `plugin-sdk/channel-config-schema` -serve per primitive di schema condivise e per il builder generico. I plugin -inclusi in OpenClaw usano `plugin-sdk/bundled-channel-config-schema` per gli -schemi di canale incluso mantenuti. Gli export di compatibilità deprecati restano su -`plugin-sdk/channel-config-schema-legacy`; nessuno dei sottopercorsi di schema incluso è un +è per le primitive di schema condivise e il builder generico. I plugin inclusi in +OpenClaw usano `plugin-sdk/bundled-channel-config-schema` per gli schemi dei canali inclusi +mantenuti. Gli export di compatibilità deprecati restano su +`plugin-sdk/channel-config-schema-legacy`; nessuno dei sottopercorsi degli schemi inclusi è un modello per nuovi plugin. - Non importare seam di praticità con brand di provider o canale (per esempio + Non importare seam di comodità marcati provider o canale (per esempio `openclaw/plugin-sdk/slack`, `.../discord`, `.../signal`, `.../whatsapp`). - I plugin inclusi compongono sottopercorsi SDK generici dentro i propri barrel - `api.ts` / `runtime-api.ts`; i consumer core dovrebbero usare quei barrel locali - al plugin oppure aggiungere un contratto SDK generico ristretto quando un'esigenza è davvero + I plugin inclusi compongono sottopercorsi SDK generici dentro i propri barrel `api.ts` / + `runtime-api.ts`; i consumer del nucleo dovrebbero usare quei barrel locali al plugin + oppure aggiungere un contratto SDK generico ristretto quando un'esigenza è davvero trasversale ai canali. -Un piccolo insieme di seam helper per plugin inclusi appare ancora nella mappa degli export -generata quando ha utilizzo tracciato da parte degli owner. Esistono solo per la -manutenzione dei plugin inclusi e non sono percorsi di importazione consigliati per nuovi -plugin di terze parti. +Un piccolo insieme di seam helper dei plugin inclusi compare ancora nella mappa degli export +generata quando ha un utilizzo tracciato dal proprietario. Esistono solo per la manutenzione +dei plugin inclusi e non sono percorsi di importazione consigliati per nuovi plugin +di terze parti. `openclaw/plugin-sdk/discord` e `openclaw/plugin-sdk/telegram-account` sono -anche mantenuti come facade di compatibilità deprecate per utilizzo tracciato degli owner. Non -copiare quei percorsi di importazione in nuovi plugin; usa invece helper runtime iniettati e +anche mantenuti come facade di compatibilità deprecate per l'utilizzo tracciato dal proprietario. Non +copiare questi percorsi di importazione in nuovi plugin; usa invece helper runtime iniettati e sottopercorsi SDK di canale generici. ## Riferimento dei sottopercorsi -L'SDK Plugin è esposto come un insieme di sottopercorsi ristretti raggruppati per area (entry -plugin, canale, provider, auth, runtime, capability, memoria e helper riservati -ai plugin inclusi). Per il catalogo completo, raggruppato e collegato, consulta -[Sottopercorsi dell'SDK Plugin](/it/plugins/sdk-subpaths). +L'SDK per plugin è esposto come un insieme di sottopercorsi ristretti raggruppati per area (entry +del plugin, canale, provider, auth, runtime, capacità, memoria e helper riservati +ai plugin inclusi). Per il catalogo completo, raggruppato e con link, vedi +[Sottopercorsi dell'SDK per plugin](/it/plugins/sdk-subpaths). L'elenco generato di oltre 200 sottopercorsi si trova in `scripts/lib/plugin-sdk-entrypoints.json`. ## API di registrazione -Il callback `register(api)` riceve un oggetto `OpenClawPluginApi` con questi +La callback `register(api)` riceve un oggetto `OpenClawPluginApi` con questi metodi: -### Registrazione delle capability +### Registrazione delle capacità -| Metodo | Cosa registra | -| ------------------------------------------------ | ------------------------------------- | -| `api.registerProvider(...)` | Inferenza di testo (LLM) | -| `api.registerAgentHarness(...)` | Executor agente sperimentale di basso livello | -| `api.registerCliBackend(...)` | Backend di inferenza CLI locale | -| `api.registerChannel(...)` | Canale di messaggistica | -| `api.registerSpeechProvider(...)` | Sintesi text-to-speech / STT | -| `api.registerRealtimeTranscriptionProvider(...)` | Trascrizione realtime in streaming | -| `api.registerRealtimeVoiceProvider(...)` | Sessioni vocali realtime duplex | -| `api.registerMediaUnderstandingProvider(...)` | Analisi di immagini/audio/video | -| `api.registerImageGenerationProvider(...)` | Generazione di immagini | -| `api.registerMusicGenerationProvider(...)` | Generazione musicale | -| `api.registerVideoGenerationProvider(...)` | Generazione video | -| `api.registerWebFetchProvider(...)` | Provider di fetch / scrape web | -| `api.registerWebSearchProvider(...)` | Ricerca web | +| Metodo | Cosa registra | +| ------------------------------------------------ | ------------------------------------ | +| `api.registerProvider(...)` | Inferenza testuale (LLM) | +| `api.registerAgentHarness(...)` | Esecutore agente sperimentale di basso livello | +| `api.registerCliBackend(...)` | Backend locale di inferenza CLI | +| `api.registerChannel(...)` | Canale di messaggistica | +| `api.registerSpeechProvider(...)` | Sintesi text-to-speech / STT | +| `api.registerRealtimeTranscriptionProvider(...)` | Trascrizione realtime in streaming | +| `api.registerRealtimeVoiceProvider(...)` | Sessioni vocali realtime duplex | +| `api.registerMediaUnderstandingProvider(...)` | Analisi di immagini/audio/video | +| `api.registerImageGenerationProvider(...)` | Generazione di immagini | +| `api.registerMusicGenerationProvider(...)` | Generazione di musica | +| `api.registerVideoGenerationProvider(...)` | Generazione di video | +| `api.registerWebFetchProvider(...)` | Provider di web fetch / scraping | +| `api.registerWebSearchProvider(...)` | Ricerca web | ### Strumenti e comandi -| Metodo | Cosa registra | -| ------------------------------- | ------------------------------------------------ | +| Metodo | Cosa registra | +| ------------------------------ | -------------------------------------------------- | | `api.registerTool(tool, opts?)` | Strumento agente (obbligatorio o `{ optional: true }`) | -| `api.registerCommand(def)` | Comando personalizzato (bypassa l'LLM) | +| `api.registerCommand(def)` | Comando personalizzato (bypassa l'LLM) | I comandi dei plugin possono impostare `agentPromptGuidance` quando l'agente ha bisogno di un breve -suggerimento di instradamento di proprietà del comando. Mantieni quel testo sul comando stesso; non aggiungere -policy specifiche di provider o plugin ai builder di prompt core. +suggerimento di routing di proprietà del comando. Mantieni quel testo relativo al comando stesso; non aggiungere +policy specifiche del provider o del plugin ai builder dei prompt del nucleo. ### Infrastruttura -| Metodo | Cosa registra | -| ---------------------------------------------- | ---------------------------------------------- | -| `api.registerHook(events, handler, opts?)` | Hook evento | -| `api.registerHttpRoute(params)` | Endpoint HTTP del Gateway | -| `api.registerGatewayMethod(name, handler)` | Metodo RPC del Gateway | -| `api.registerGatewayDiscoveryService(service)` | Inserzionista di discovery del Gateway locale | -| `api.registerCli(registrar, opts?)` | Sottocomando CLI | -| `api.registerService(service)` | Servizio in background | -| `api.registerInteractiveHandler(registration)` | Handler interattivo | -| `api.registerAgentToolResultMiddleware(...)` | Middleware runtime per risultati degli strumenti | +| Metodo | Cosa registra | +| ---------------------------------------------- | ------------------------------------- | +| `api.registerHook(events, handler, opts?)` | Hook evento | +| `api.registerHttpRoute(params)` | Endpoint HTTP del Gateway | +| `api.registerGatewayMethod(name, handler)` | Metodo RPC del Gateway | +| `api.registerGatewayDiscoveryService(service)` | Inserzionista di discovery del Gateway locale | +| `api.registerCli(registrar, opts?)` | Sottocomando CLI | +| `api.registerService(service)` | Servizio in background | +| `api.registerInteractiveHandler(registration)` | Handler interattivo | +| `api.registerAgentToolResultMiddleware(...)` | Middleware runtime per risultato strumento | | `api.registerMemoryPromptSupplement(builder)` | Sezione prompt additiva adiacente alla memoria | -| `api.registerMemoryCorpusSupplement(adapter)` | Corpus additivo di ricerca/lettura memoria | +| `api.registerMemoryCorpusSupplement(adapter)` | Corpus additivo di ricerca/lettura memoria | ### Hook host per plugin di workflow -Gli hook host sono i seam SDK per plugin che devono partecipare al ciclo di vita -dell'host invece di aggiungere solo un provider, un canale o uno strumento. Sono -contratti generici; Plan Mode può usarli, ma anche workflow di approvazione, -gate di policy del workspace, monitor in background, wizard di configurazione e plugin companion -dell'interfaccia utente. +Gli hook host sono i seam SDK per i plugin che devono partecipare al ciclo di vita dell'host +invece di limitarsi ad aggiungere un provider, un canale o uno strumento. Sono +contratti generici; Plan Mode può usarli, ma possono farlo anche workflow di approvazione, +gate di policy workspace, monitor in background, wizard di configurazione e plugin companion +UI. -| Metodo | Contratto che possiede | -| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerSessionExtension(...)` | Stato sessione di proprietà del plugin, compatibile con JSON, proiettato tramite sessioni Gateway | -| `api.enqueueNextTurnInjection(...)` | Contesto durabile exactly-once iniettato nel prossimo turno agente per una sessione | -| `api.registerTrustedToolPolicy(...)` | Policy strumenti pre-plugin inclusa/attendibile che può bloccare o riscrivere i parametri degli strumenti | -| `api.registerToolMetadata(...)` | Metadati di visualizzazione del catalogo strumenti senza modificare l'implementazione dello strumento | -| `api.registerCommand(...)` | Comandi plugin con ambito; i risultati dei comandi possono impostare `continueAgent: true`; i comandi nativi Discord supportano `descriptionLocalizations` | -| `api.registerControlUiDescriptor(...)` | Descrittori di contributo Control UI per superfici di sessione, strumento, run o impostazioni | -| `api.registerRuntimeLifecycle(...)` | Callback di pulizia per risorse runtime di proprietà del plugin nei percorsi di reset/delete/reload | -| `api.registerAgentEventSubscription(...)` | Sottoscrizioni a eventi sanificate per stato e monitor dei workflow | -| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | Stato scratch del plugin per run cancellato sul ciclo di vita terminale della run | -| `api.registerSessionSchedulerJob(...)` | Record di job dello scheduler di sessione di proprietà del plugin con pulizia deterministica | +| Metodo | Contratto che possiede | +| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | +| `api.registerSessionExtension(...)` | Stato sessione di proprietà del plugin, compatibile con JSON, proiettato tramite le sessioni Gateway | +| `api.enqueueNextTurnInjection(...)` | Contesto durevole exactly-once iniettato nel prossimo turno dell'agente per una sessione | +| `api.registerTrustedToolPolicy(...)` | Policy strumenti pre-plugin inclusa/attendibile che può bloccare o riscrivere i parametri degli strumenti | +| `api.registerToolMetadata(...)` | Metadati di visualizzazione del catalogo strumenti senza modificare l'implementazione dello strumento | +| `api.registerCommand(...)` | Comandi scoped del plugin; i risultati dei comandi possono impostare `continueAgent: true`; i comandi nativi Discord supportano `descriptionLocalizations` | +| `api.registerControlUiDescriptor(...)` | Descrittori di contributo della Control UI per superfici sessione, strumento, esecuzione o impostazioni | +| `api.registerRuntimeLifecycle(...)` | Callback di cleanup per risorse runtime di proprietà del plugin sui percorsi reset/delete/reload | +| `api.registerAgentEventSubscription(...)` | Sottoscrizioni evento sanificate per stato workflow e monitor | +| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | Stato scratch del plugin per esecuzione cancellato sul ciclo di vita terminale dell'esecuzione | +| `api.registerSessionSchedulerJob(...)` | Record di job dello scheduler sessione di proprietà del plugin con cleanup deterministico | -I contratti separano intenzionalmente l'autorità: +I contratti dividono intenzionalmente l'autorità: -- I plugin esterni possono possedere estensioni di sessione, descrittori UI, comandi, metadati degli strumenti, iniezioni nel turno successivo e hook normali. -- Le policy strumenti attendibili vengono eseguite prima degli hook ordinari `before_tool_call` e sono solo incluse perché partecipano alla policy di sicurezza dell'host. -- La proprietà dei comandi riservati è solo inclusa. I plugin esterni dovrebbero usare i propri nomi comando o alias. -- `allowPromptInjection=false` disabilita gli hook che modificano il prompt, inclusi +- I plugin esterni possono possedere estensioni sessione, descrittori UI, comandi, metadati degli strumenti, iniezioni next-turn e hook normali. +- Le policy strumenti attendibili vengono eseguite prima degli hook ordinari `before_tool_call` e sono + solo per plugin inclusi perché partecipano alla policy di sicurezza dell'host. +- La proprietà dei comandi riservati è solo per plugin inclusi. I plugin esterni dovrebbero usare i propri + nomi o alias di comando. +- `allowPromptInjection=false` disabilita gli hook che modificano i prompt, inclusi `agent_turn_prepare`, `before_prompt_build`, `heartbeat_prompt_contribution`, - i campi prompt dal legacy `before_agent_start` e + i campi prompt dal vecchio `before_agent_start` e `enqueueNextTurnInjection`. Esempi di consumer non Plan: -| Archetipo di plugin | Hook usati | -| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| Workflow di approvazione | Estensione di sessione, continuazione comando, iniezione nel turno successivo, descrittore UI | +| Archetipo di plugin | Hook usati | +| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| Workflow di approvazione | Estensione sessione, continuazione comando, iniezione next-turn, descrittore UI | | Gate di policy budget/workspace | Policy strumenti attendibile, metadati strumenti, proiezione sessione | -| Monitor del ciclo di vita in background | Pulizia ciclo di vita runtime, sottoscrizione eventi agente, proprietà/pulizia scheduler di sessione, contributo prompt heartbeat, descrittore UI | -| Wizard di configurazione o onboarding | Estensione di sessione, comandi con ambito, descrittore Control UI | +| Monitor del ciclo di vita in background | Cleanup del ciclo di vita runtime, sottoscrizione eventi agente, proprietà/cleanup dello scheduler sessione, contributo prompt heartbeat, descrittore UI | +| Wizard di setup o onboarding | Estensione sessione, comandi scoped, descrittore Control UI | - Gli spazi dei nomi admin core riservati (`config.*`, `exec.approvals.*`, `wizard.*`, - `update.*`) restano sempre `operator.admin`, anche se un plugin prova ad assegnare un - ambito metodo gateway più ristretto. Preferisci prefissi specifici del plugin per i - metodi di proprietà del plugin. + I namespace amministrativi riservati del nucleo (`config.*`, `exec.approvals.*`, `wizard.*`, + `update.*`) restano sempre `operator.admin`, anche se un plugin prova ad assegnare uno + scope più ristretto al metodo gateway. Preferisci prefissi specifici del plugin per + i metodi di proprietà del plugin. - + I plugin inclusi possono usare `api.registerAgentToolResultMiddleware(...)` quando - devono riscrivere il risultato di uno strumento dopo l'esecuzione e prima che il runtime - reinserisca quel risultato nel modello. Questo è il seam attendibile e neutrale rispetto al runtime - per riduttori di output asincroni come tokenjuice. + devono riscrivere un risultato strumento dopo l'esecuzione e prima che il runtime + rimandi quel risultato al modello. Questo è il seam attendibile e neutrale rispetto al runtime + per reducer di output asincroni come tokenjuice. I plugin inclusi devono dichiarare `contracts.agentToolResultMiddleware` per ogni -runtime target, per esempio `["pi", "codex"]`. I plugin esterni -non possono registrare questo middleware; mantieni gli hook normali dei Plugin OpenClaw per il lavoro -che non richiede timing del risultato dello strumento prima del modello. Il vecchio percorso di -registrazione factory di estensione incorporata solo Pi è stato rimosso. +runtime mirato, per esempio `["pi", "codex"]`. I plugin esterni +non possono registrare questo middleware; mantieni i normali hook plugin OpenClaw per il lavoro +che non richiede il timing del risultato strumento pre-modello. Il vecchio percorso di registrazione della factory +di estensione incorporata solo per Pi è stato rimosso. ### Registrazione della discovery del Gateway -`api.registerGatewayDiscoveryService(...)` consente a un Plugin di pubblicizzare il Gateway attivo su un trasporto di discovery locale come mDNS/Bonjour. OpenClaw chiama il servizio durante l'avvio del Gateway quando la discovery locale è abilitata, passa le porte correnti del Gateway e dati di suggerimento TXT non segreti, e chiama il gestore `stop` restituito durante l'arresto del Gateway. +`api.registerGatewayDiscoveryService(...)` consente a un plugin di pubblicizzare il Gateway attivo +su un trasporto di discovery locale come mDNS/Bonjour. OpenClaw chiama il +servizio durante l'avvio del Gateway quando la discovery locale è abilitata, passa le +porte Gateway correnti e dati di suggerimento TXT non segreti, e chiama l'handler +`stop` restituito durante l'arresto del Gateway. ```typescript api.registerGatewayDiscoveryService({ @@ -207,17 +213,21 @@ api.registerGatewayDiscoveryService({ }); ``` -I Plugin di discovery del Gateway non devono trattare i valori TXT pubblicizzati come segreti o autenticazione. La discovery è un suggerimento di routing; l'autenticazione del Gateway e il pinning TLS rimangono responsabili della fiducia. +I plugin di discovery Gateway non devono trattare i valori TXT pubblicizzati come segreti o +autenticazione. La discovery è un suggerimento di routing; l'autenticazione Gateway e il pinning TLS +rimangono responsabili della fiducia. -### Metadati di registrazione della CLI +### Metadati di registrazione CLI `api.registerCli(registrar, opts?)` accetta due tipi di metadati di primo livello: -- `commands`: radici di comando esplicite possedute dal registrar -- `descriptors`: descrittori di comando in fase di parsing usati per l'aiuto della CLI radice, - il routing e la registrazione lazy della CLI del Plugin +- `commands`: radici di comando esplicite di proprietà del registrar +- `descriptors`: descrittori di comando in fase di parsing usati per l'help della CLI radice, + il routing e la registrazione lazy della CLI del plugin -Se vuoi che un comando di Plugin resti caricato in modo lazy nel normale percorso della CLI radice, fornisci `descriptors` che coprano ogni radice di comando di primo livello esposta da quel registrar. +Se vuoi che un comando plugin rimanga caricato in modo lazy nel normale percorso CLI radice, +fornisci `descriptors` che coprano ogni radice di comando di primo livello esposta da quel +registrar. ```typescript api.registerCli( @@ -237,93 +247,101 @@ api.registerCli( ); ``` -Usa `commands` da solo solo quando non ti serve la registrazione lazy della CLI radice. Quel percorso di compatibilità eager rimane supportato, ma non installa placeholder basati su descrittori per il caricamento lazy in fase di parsing. +Usa `commands` da solo solo quando non hai bisogno della registrazione lazy della CLI radice. +Quel percorso di compatibilità eager rimane supportato, ma non installa +segnaposto basati su descrittori per il caricamento lazy in fase di parsing. ### Registrazione del backend CLI -`api.registerCliBackend(...)` consente a un Plugin di possedere la configurazione predefinita per un backend CLI AI locale come `codex-cli`. +`api.registerCliBackend(...)` consente a un plugin di possedere la configurazione predefinita per un backend +CLI AI locale come `codex-cli`. -- L'`id` del backend diventa il prefisso del provider nei riferimenti ai modelli come `codex-cli/gpt-5`. +- L'`id` del backend diventa il prefisso provider nei riferimenti modello come `codex-cli/gpt-5`. - La `config` del backend usa la stessa forma di `agents.defaults.cliBackends.`. -- La configurazione utente ha comunque la precedenza. OpenClaw unisce `agents.defaults.cliBackends.` sopra il valore predefinito del Plugin prima di eseguire la CLI. -- Usa `normalizeConfig` quando un backend richiede riscritture di compatibilità dopo l'unione +- La configurazione utente ha comunque la precedenza. OpenClaw unisce `agents.defaults.cliBackends.` sopra il + valore predefinito del plugin prima di eseguire la CLI. +- Usa `normalizeConfig` quando un backend ha bisogno di riscritture di compatibilità dopo l'unione (per esempio normalizzando vecchie forme di flag). +- Usa `resolveExecutionArgs` per riscritture argv con ambito richiesta che appartengono al + dialetto CLI, come la mappatura dei livelli di ragionamento OpenClaw a un flag effort + nativo. ### Slot esclusivi -| Metodo | Cosa registra | -| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Metodo | Cosa registra | +| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `api.registerContextEngine(id, factory)` | Motore di contesto (uno attivo alla volta). Il callback `assemble()` riceve `availableTools` e `citationsMode` così il motore può adattare le aggiunte al prompt. | -| `api.registerMemoryCapability(capability)` | Capability di memoria unificata | -| `api.registerMemoryPromptSection(builder)` | Builder di sezione del prompt di memoria | -| `api.registerMemoryFlushPlan(resolver)` | Resolver del piano di flush della memoria | -| `api.registerMemoryRuntime(runtime)` | Adapter runtime di memoria | +| `api.registerMemoryCapability(capability)` | Capacità di memoria unificata | +| `api.registerMemoryPromptSection(builder)` | Builder della sezione del prompt di memoria | +| `api.registerMemoryFlushPlan(resolver)` | Resolver del piano di flush della memoria | +| `api.registerMemoryRuntime(runtime)` | Adapter runtime della memoria | ### Adapter di embedding della memoria -| Metodo | Cosa registra | -| ---------------------------------------------- | ---------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter di embedding della memoria per il Plugin attivo | +| Metodo | Cosa registra | +| ---------------------------------------------- | -------------------------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter di embedding della memoria per il plugin attivo | -- `registerMemoryCapability` è l'API esclusiva preferita per i Plugin di memoria. +- `registerMemoryCapability` è l'API esclusiva preferita per i plugin di memoria. - `registerMemoryCapability` può anche esporre `publicArtifacts.listArtifacts(...)` - così i Plugin companion possono consumare artefatti di memoria esportati tramite + così i plugin companion possono consumare artifact di memoria esportati tramite `openclaw/plugin-sdk/memory-host-core` invece di accedere al layout privato di uno specifico - Plugin di memoria. + plugin di memoria. - `registerMemoryPromptSection`, `registerMemoryFlushPlan` e - `registerMemoryRuntime` sono API esclusive per Plugin di memoria compatibili con il legacy. -- `MemoryFlushPlan.model` può fissare il turno di flush a un riferimento esatto `provider/model` - come `ollama/qwen3:8b`, senza ereditare la catena di fallback attiva. -- `registerMemoryEmbeddingProvider` consente al Plugin di memoria attivo di registrare uno + `registerMemoryRuntime` sono API esclusive legacy-compatibili per i plugin di memoria. +- `MemoryFlushPlan.model` può fissare il turno di flush a un riferimento `provider/model` + esatto, come `ollama/qwen3:8b`, senza ereditare la catena di fallback attiva. +- `registerMemoryEmbeddingProvider` consente al plugin di memoria attivo di registrare uno o più id di adapter di embedding (per esempio `openai`, `gemini` o un id personalizzato - definito dal Plugin). + definito dal plugin). - La configurazione utente come `agents.defaults.memorySearch.provider` e `agents.defaults.memorySearch.fallback` viene risolta rispetto a quegli id di adapter registrati. ### Eventi e ciclo di vita -| Metodo | Cosa fa | -| -------------------------------------------- | ------------------------------- | +| Metodo | Cosa fa | +| -------------------------------------------- | ----------------------------- | | `api.on(hookName, handler, opts?)` | Hook di ciclo di vita tipizzato | | `api.onConversationBindingResolved(handler)` | Callback di binding conversazione | -Vedi [Hook dei Plugin](/it/plugins/hooks) per esempi, nomi di hook comuni e semantica delle guardie. +Vedi [Hook dei plugin](/it/plugins/hooks) per esempi, nomi di hook comuni e +semantica delle guardie. ### Semantica delle decisioni degli hook -- `before_tool_call`: restituire `{ block: true }` è terminale. Quando un gestore lo imposta, i gestori con priorità inferiore vengono saltati. +- `before_tool_call`: restituire `{ block: true }` è terminale. Quando un handler lo imposta, gli handler con priorità inferiore vengono ignorati. - `before_tool_call`: restituire `{ block: false }` viene trattato come nessuna decisione (come omettere `block`), non come override. -- `before_install`: restituire `{ block: true }` è terminale. Quando un gestore lo imposta, i gestori con priorità inferiore vengono saltati. +- `before_install`: restituire `{ block: true }` è terminale. Quando un handler lo imposta, gli handler con priorità inferiore vengono ignorati. - `before_install`: restituire `{ block: false }` viene trattato come nessuna decisione (come omettere `block`), non come override. -- `reply_dispatch`: restituire `{ handled: true, ... }` è terminale. Quando un gestore rivendica il dispatch, i gestori con priorità inferiore e il percorso di dispatch predefinito del modello vengono saltati. -- `message_sending`: restituire `{ cancel: true }` è terminale. Quando un gestore lo imposta, i gestori con priorità inferiore vengono saltati. +- `reply_dispatch`: restituire `{ handled: true, ... }` è terminale. Quando un handler rivendica il dispatch, gli handler con priorità inferiore e il percorso di dispatch modello predefinito vengono ignorati. +- `message_sending`: restituire `{ cancel: true }` è terminale. Quando un handler lo imposta, gli handler con priorità inferiore vengono ignorati. - `message_sending`: restituire `{ cancel: false }` viene trattato come nessuna decisione (come omettere `cancel`), non come override. -- `message_received`: usa il campo tipizzato `threadId` quando ti serve il routing di thread/topic in entrata. Mantieni `metadata` per gli extra specifici del canale. -- `message_sending`: usa i campi di routing tipizzati `replyToId` / `threadId` prima di ricorrere ai `metadata` specifici del canale. -- `gateway_start`: usa `ctx.config`, `ctx.workspaceDir` e `ctx.getCron?.()` per lo stato di avvio posseduto dal Gateway invece di fare affidamento sugli hook interni `gateway:startup`. -- `cron_changed`: osserva le modifiche del ciclo di vita Cron possedute dal Gateway. Usa `event.job?.state?.nextRunAtMs` e `ctx.getCron?.()` quando sincronizzi scheduler di risveglio esterni, e mantieni OpenClaw come fonte di verità per i controlli delle scadenze e l'esecuzione. +- `message_received`: usa il campo tipizzato `threadId` quando hai bisogno del routing di thread/argomento in ingresso. Conserva `metadata` per extra specifici del canale. +- `message_sending`: usa i campi di routing tipizzati `replyToId` / `threadId` prima di ripiegare su `metadata` specifici del canale. +- `gateway_start`: usa `ctx.config`, `ctx.workspaceDir` e `ctx.getCron?.()` per lo stato di avvio di proprietà del gateway invece di affidarti agli hook interni `gateway:startup`. +- `cron_changed`: osserva le modifiche del ciclo di vita del cron di proprietà del gateway. Usa `event.job?.state?.nextRunAtMs` e `ctx.getCron?.()` quando sincronizzi scheduler di risveglio esterni, e mantieni OpenClaw come fonte di verità per i controlli di scadenza e l'esecuzione. ### Campi dell'oggetto API -| Campo | Tipo | Descrizione | -| ------------------------ | ------------------------- | ----------------------------------------------------------------------------------------------- | -| `api.id` | `string` | Id del Plugin | -| `api.name` | `string` | Nome visualizzato | -| `api.version` | `string?` | Versione del Plugin (opzionale) | -| `api.description` | `string?` | Descrizione del Plugin (opzionale) | -| `api.source` | `string` | Percorso sorgente del Plugin | -| `api.rootDir` | `string?` | Directory radice del Plugin (opzionale) | -| `api.config` | `OpenClawConfig` | Snapshot della configurazione corrente (snapshot runtime attivo in memoria quando disponibile) | -| `api.pluginConfig` | `Record` | Configurazione specifica del Plugin da `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Helper runtime](/it/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Logger con ambito (`debug`, `info`, `warn`, `error`) | -| `api.registrationMode` | `PluginRegistrationMode` | Modalità di caricamento corrente; `"setup-runtime"` è la finestra leggera di avvio/setup pre-ingresso completo | -| `api.resolvePath(input)` | `(string) => string` | Risolve il percorso relativo alla radice del Plugin | +| Campo | Tipo | Descrizione | +| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | +| `api.id` | `string` | Id del plugin | +| `api.name` | `string` | Nome visualizzato | +| `api.version` | `string?` | Versione del plugin (opzionale) | +| `api.description` | `string?` | Descrizione del plugin (opzionale) | +| `api.source` | `string` | Percorso sorgente del plugin | +| `api.rootDir` | `string?` | Directory radice del plugin (opzionale) | +| `api.config` | `OpenClawConfig` | Snapshot della configurazione corrente (snapshot runtime attivo in memoria quando disponibile) | +| `api.pluginConfig` | `Record` | Configurazione specifica del plugin da `plugins.entries..config` | +| `api.runtime` | `PluginRuntime` | [Helper runtime](/it/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | Logger con ambito (`debug`, `info`, `warn`, `error`) | +| `api.registrationMode` | `PluginRegistrationMode` | Modalità di caricamento corrente; `"setup-runtime"` è la finestra leggera di avvio/setup precedente all'entry completa | +| `api.resolvePath(input)` | `(string) => string` | Risolve il percorso relativo alla radice del plugin | ## Convenzione dei moduli interni -All'interno del tuo Plugin, usa file barrel locali per gli import interni: +Nel tuo plugin, usa file barrel locali per gli import interni: ``` my-plugin/ @@ -334,34 +352,35 @@ my-plugin/ ``` - Non importare mai il tuo Plugin tramite `openclaw/plugin-sdk/` + Non importare mai il tuo plugin tramite `openclaw/plugin-sdk/` dal codice di produzione. Instrada gli import interni tramite `./api.ts` o `./runtime-api.ts`. Il percorso SDK è solo il contratto esterno. -Le superfici pubbliche dei Plugin bundled caricate tramite facade (`api.ts`, `runtime-api.ts`, -`index.ts`, `setup-entry.ts` e file di ingresso pubblici simili) preferiscono lo -snapshot della configurazione runtime attiva quando OpenClaw è già in esecuzione. Se non esiste ancora -alcuno snapshot runtime, usano come fallback il file di configurazione risolto su disco. -Le facade dei Plugin bundled pacchettizzati devono essere caricate tramite i loader facade dei Plugin -di OpenClaw; gli import diretti da `dist/extensions/...` aggirano il manifest -e i controlli sidecar runtime che le installazioni pacchettizzate usano per il codice posseduto dai Plugin. +Le superfici pubbliche dei plugin in bundle caricate tramite facciata (`api.ts`, `runtime-api.ts`, +`index.ts`, `setup-entry.ts` e file entry pubblici simili) preferiscono lo +snapshot di configurazione runtime attivo quando OpenClaw è già in esecuzione. Se non esiste ancora alcuno snapshot +runtime, ripiegano sul file di configurazione risolto su disco. +Le facciate dei plugin in bundle pacchettizzati devono essere caricate tramite i loader di facciata +plugin di OpenClaw; gli import diretti da `dist/extensions/...` bypassano il manifest +e i controlli sidecar runtime che le installazioni pacchettizzate usano per il codice di proprietà del plugin. -I Plugin provider possono esporre un barrel di contratto ristretto e locale al Plugin quando un -helper è intenzionalmente specifico del provider e non appartiene ancora a un sottopercorso SDK generico. Esempi bundled: +I plugin provider possono esporre un barrel di contratto ristretto locale al plugin quando un +helper è intenzionalmente specifico del provider e non appartiene ancora a un sottopercorso SDK +generico. Esempi in bundle: -- **Anthropic**: seam pubblico `api.ts` / `contract-api.ts` per gli helper Claude - beta-header e stream `service_tier`. +- **Anthropic**: seam pubblico `api.ts` / `contract-api.ts` per helper di stream + beta-header Claude e `service_tier`. - **`@openclaw/openai-provider`**: `api.ts` esporta builder di provider, - helper per modelli predefiniti e builder di provider realtime. + helper del modello predefinito e builder di provider realtime. - **`@openclaw/openrouter-provider`**: `api.ts` esporta il builder di provider più helper di onboarding/configurazione. - Anche il codice di produzione delle estensioni dovrebbe evitare import da `openclaw/plugin-sdk/`. + Il codice di produzione delle estensioni dovrebbe anche evitare import `openclaw/plugin-sdk/`. Se un helper è davvero condiviso, promuovilo a un sottopercorso SDK neutrale come `openclaw/plugin-sdk/speech`, `.../provider-model-shared` o un'altra - superficie orientata alle capability invece di accoppiare due Plugin tra loro. + superficie orientata alla capability invece di accoppiare due plugin tra loro. ## Correlati @@ -373,16 +392,16 @@ helper è intenzionalmente specifico del provider e non appartiene ancora a un s Riferimento completo dello spazio dei nomi `api.runtime`. - - Packaging, manifest e schemi di configurazione. + + Packaging, manifest e schemi di config. - + Utilità di test e regole di lint. - + Migrazione da superfici deprecate. - - Architettura approfondita e modello di capability. + + Architettura approfondita e modello di capacità. diff --git a/docs/it/security/network-proxy.md b/docs/it/security/network-proxy.md index 366d07a1d..1d8a1a97c 100644 --- a/docs/it/security/network-proxy.md +++ b/docs/it/security/network-proxy.md @@ -1,40 +1,40 @@ --- read_when: - - Si desidera una difesa in profondità contro gli attacchi SSRF e di DNS rebinding - - Configurazione di un proxy forward esterno per il traffico di runtime di OpenClaw + - Vuoi una difesa in profondità contro attacchi SSRF e di DNS rebinding + - Configurazione di un proxy di inoltro esterno per il traffico di OpenClaw in fase di esecuzione summary: Come instradare il traffico HTTP e WebSocket del runtime OpenClaw attraverso un proxy di filtraggio gestito dall'operatore title: Proxy di rete x-i18n: - generated_at: "2026-05-04T07:08:34Z" + generated_at: "2026-05-04T18:24:38Z" model: gpt-5.5 provider: openai - source_hash: fc7140c5ced0e7454a6f85d1ea8f3256bbd28cc0cb42eeafe8e5e6439b90e3f0 + source_hash: eedbf3bac14800c34c7ca2e3b6879dac360a88d51b5b7449ddf41a4dd471648b source_path: security/network-proxy.md workflow: 16 --- # Proxy di rete -OpenClaw può instradare il traffico HTTP e WebSocket di runtime attraverso un proxy forward gestito dall'operatore. Si tratta di una difesa in profondità opzionale per distribuzioni che vogliono un controllo centralizzato dell'egresso, una protezione SSRF più forte e una migliore verificabilità della rete. +OpenClaw può instradare il traffico HTTP e WebSocket di runtime attraverso un proxy forward gestito dall'operatore. È una difesa opzionale in profondità per distribuzioni che vogliono controllo centrale dell'egress, protezione SSRF più forte e migliore verificabilità della rete. -OpenClaw non fornisce, scarica, avvia, configura o certifica un proxy. Esegui la tecnologia proxy adatta al tuo ambiente e OpenClaw instrada attraverso di essa i normali client HTTP e WebSocket locali al processo. +OpenClaw non fornisce, scarica, avvia, configura o certifica un proxy. Esegui la tecnologia proxy adatta al tuo ambiente e OpenClaw vi instrada i normali client HTTP e WebSocket locali al processo. ## Perché usare un proxy? -Un proxy offre agli operatori un unico punto di controllo di rete per il traffico HTTP e WebSocket in uscita. Può essere utile anche al di fuori dell'irrobustimento contro SSRF: +Un proxy offre agli operatori un unico punto di controllo di rete per il traffico HTTP e WebSocket in uscita. Può essere utile anche al di fuori dell'irrobustimento SSRF: -- Criterio centralizzato: mantieni un unico criterio di egresso invece di affidarti a ogni punto di chiamata HTTP dell'applicazione perché applichi correttamente le regole di rete. -- Controlli al momento della connessione: valuta la destinazione dopo la risoluzione DNS e immediatamente prima che il proxy apra la connessione upstream. -- Difesa dal DNS rebinding: riduce il divario tra un controllo DNS a livello applicativo e la connessione in uscita effettiva. -- Copertura JavaScript più ampia: instrada `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch e client simili ordinari attraverso lo stesso percorso. -- Verificabilità: registra destinazioni consentite e negate al confine di egresso. +- Policy centrale: mantieni una sola policy di egress invece di affidarti a ogni punto di chiamata HTTP dell'applicazione per applicare correttamente le regole di rete. +- Controlli al momento della connessione: valuta la destinazione dopo la risoluzione DNS e subito prima che il proxy apra la connessione upstream. +- Difesa da DNS rebinding: riduci lo scarto tra un controllo DNS a livello applicativo e la connessione in uscita effettiva. +- Copertura JavaScript più ampia: instrada i client ordinari `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch e simili attraverso lo stesso percorso. +- Verificabilità: registra le destinazioni consentite e negate al confine di egress. - Controllo operativo: applica regole di destinazione, segmentazione di rete, limiti di frequenza o allowlist in uscita senza ricompilare OpenClaw. -L'instradamento tramite proxy è un guardrail a livello di processo per il normale egresso HTTP e WebSocket. Offre agli operatori un percorso fail-closed per instradare i client HTTP JavaScript supportati attraverso il proprio proxy di filtraggio, ma non è una sandbox di rete a livello di sistema operativo e non fa sì che OpenClaw certifichi il criterio di destinazione del proxy. +L'instradamento tramite proxy è un limite di protezione a livello di processo per il normale egress HTTP e WebSocket. Offre agli operatori un percorso con chiusura in caso di errore per instradare i client HTTP JavaScript supportati attraverso il proprio proxy di filtraggio, ma non è una sandbox di rete a livello di sistema operativo e non fa sì che OpenClaw certifichi la policy di destinazione del proxy. ## Come OpenClaw instrada il traffico -Quando `proxy.enabled=true` e viene configurato un URL del proxy, i processi di runtime protetti come `openclaw gateway run`, `openclaw node run` e `openclaw agent --local` instradano il normale egresso HTTP e WebSocket attraverso il proxy configurato: +Quando `proxy.enabled=true` ed è configurato un URL proxy, i processi di runtime protetti come `openclaw gateway run`, `openclaw node run` e `openclaw agent --local` instradano il normale egress HTTP e WebSocket attraverso il proxy configurato: ```text OpenClaw process @@ -43,27 +43,27 @@ OpenClaw process WebSocket clients -> operator-managed filtering proxy -> public internet ``` -Il contratto pubblico è il comportamento di instradamento, non gli hook interni di Node usati per implementarlo. I client WebSocket del control plane di OpenClaw Gateway usano un percorso diretto ristretto per il traffico RPC del Gateway local loopback quando l'URL del Gateway usa `localhost` o un IP di loopback letterale come `127.0.0.1` o `[::1]`. Quel percorso del control plane deve poter raggiungere i Gateway di loopback anche quando il proxy dell'operatore blocca le destinazioni di loopback. Le normali richieste HTTP e WebSocket di runtime continuano a usare il proxy configurato. +Il contratto pubblico è il comportamento di instradamento, non gli hook Node interni usati per implementarlo. I client WebSocket del control plane di OpenClaw Gateway usano un percorso diretto ristretto per il traffico RPC Gateway su local loopback quando l'URL del Gateway usa `localhost` o un IP di loopback letterale come `127.0.0.1` o `[::1]`. Quel percorso del control plane deve poter raggiungere i Gateway in loopback anche quando il proxy dell'operatore blocca le destinazioni di loopback. Le normali richieste HTTP e WebSocket di runtime continuano a usare il proxy configurato. Internamente, OpenClaw usa due hook di instradamento a livello di processo per questa funzionalità: -- L'instradamento del dispatcher Undici copre `fetch`, i client basati su undici e i trasporti che forniscono il proprio dispatcher undici. -- L'instradamento `global-agent` copre i chiamanti core Node `node:http` e `node:https`, incluse molte librerie stratificate su `http.request`, `https.request`, `http.get` e `https.get`. La modalità proxy gestita forza quell'agente globale, così gli agent HTTP espliciti di Node non aggirano accidentalmente il proxy dell'operatore. +- L'instradamento tramite dispatcher Undici copre `fetch`, i client basati su undici e i trasporti che forniscono un proprio dispatcher undici. +- L'instradamento `global-agent` copre i chiamanti Node core `node:http` e `node:https`, incluse molte librerie stratificate su `http.request`, `https.request`, `http.get` e `https.get`. La modalità proxy gestita forza quell'agent globale in modo che gli agent HTTP Node espliciti non aggirino accidentalmente il proxy dell'operatore. -Alcuni plugin possiedono trasporti personalizzati che richiedono cablaggio proxy esplicito anche quando esiste l'instradamento a livello di processo. Per esempio, il trasporto Bot API di Telegram usa il proprio dispatcher HTTP/1 undici e quindi rispetta l'ambiente proxy del processo più il fallback gestito `OPENCLAW_PROXY_URL` in quel percorso di trasporto specifico del proprietario. +Alcuni plugin possiedono trasporti personalizzati che richiedono cablaggio esplicito del proxy anche quando esiste l'instradamento a livello di processo. Ad esempio, il trasporto Bot API di Telegram usa un proprio dispatcher HTTP/1 undici e quindi rispetta l'ambiente proxy di processo più il fallback gestito `OPENCLAW_PROXY_URL` in quel percorso di trasporto specifico del proprietario. -L'URL del proxy deve usare `http://`. Le destinazioni HTTPS sono comunque supportate attraverso il proxy con HTTP `CONNECT`; questo significa solo che OpenClaw si aspetta un listener proxy forward HTTP semplice, come `http://127.0.0.1:3128`. +L'URL del proxy deve usare `http://`. Le destinazioni HTTPS sono comunque supportate attraverso il proxy con HTTP `CONNECT`; questo significa solo che OpenClaw si aspetta un listener di proxy forward HTTP semplice, come `http://127.0.0.1:3128`. -Mentre il proxy è attivo, OpenClaw svuota `no_proxy`, `NO_PROXY` e `GLOBAL_AGENT_NO_PROXY`. Questi elenchi di bypass sono basati sulla destinazione, quindi lasciare lì `localhost` o `127.0.0.1` consentirebbe a destinazioni SSRF ad alto rischio di saltare il proxy di filtraggio. +Mentre il proxy è attivo, OpenClaw cancella `no_proxy`, `NO_PROXY` e `GLOBAL_AGENT_NO_PROXY`. Queste liste di bypass sono basate sulla destinazione, quindi lasciare `localhost` o `127.0.0.1` al loro interno consentirebbe a target SSRF ad alto rischio di saltare il proxy di filtraggio. -All'arresto, OpenClaw ripristina l'ambiente proxy precedente e reimposta lo stato di instradamento del processo memorizzato nella cache. +All'arresto, OpenClaw ripristina il precedente ambiente proxy e reimposta lo stato di instradamento di processo memorizzato nella cache. ## Termini proxy correlati -- `proxy.enabled` / `proxy.proxyUrl`: instradamento proxy forward in uscita per l'egresso di runtime di OpenClaw. Questa pagina documenta tale funzionalità. -- `gateway.auth.mode: "trusted-proxy"`: autenticazione reverse proxy in ingresso con consapevolezza dell'identità per l'accesso al Gateway. Vedi [Autenticazione trusted proxy](/it/gateway/trusted-proxy-auth). -- `openclaw proxy`: proxy di debug locale e ispettore di acquisizione per sviluppo e supporto. Vedi [openclaw proxy](/it/cli/proxy). -- Impostazioni proxy specifiche del canale o del provider: override specifici del proprietario per un determinato trasporto. Preferisci il proxy di rete gestito quando l'obiettivo è il controllo centralizzato dell'egresso in tutto il runtime. +- `proxy.enabled` / `proxy.proxyUrl`: instradamento tramite proxy forward in uscita per l'egress di runtime OpenClaw. Questa pagina documenta tale funzionalità. +- `gateway.auth.mode: "trusted-proxy"`: autenticazione inbound tramite reverse proxy consapevole dell'identità per l'accesso al Gateway. Vedi [Autenticazione tramite proxy attendibile](/it/gateway/trusted-proxy-auth). +- `openclaw proxy`: proxy locale di debug e ispettore di cattura per sviluppo e supporto. Vedi [openclaw proxy](/it/cli/proxy). +- Impostazioni proxy specifiche per canale o provider: override specifici del proprietario per un trasporto particolare. Preferisci il proxy di rete gestito quando l'obiettivo è il controllo centrale dell'egress in tutto il runtime. ## Configurazione @@ -79,11 +79,11 @@ Puoi anche fornire l'URL tramite l'ambiente, mantenendo `proxy.enabled=true` nel OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run ``` -`proxy.proxyUrl` ha la precedenza su `OPENCLAW_PROXY_URL`. +`proxy.proxyUrl` ha precedenza su `OPENCLAW_PROXY_URL`. -Se `enabled=true` ma non è configurato alcun URL del proxy valido, i comandi protetti non completano l'avvio invece di ripiegare sull'accesso diretto alla rete. +Se `enabled=true` ma non è configurato alcun URL proxy valido, i comandi protetti falliscono all'avvio invece di ricadere sull'accesso di rete diretto. -Per i servizi gateway gestiti avviati con `openclaw gateway start`, preferisci archiviare l'URL nella configurazione: +Per i servizi Gateway gestiti avviati con `openclaw gateway start`, preferisci archiviare l'URL nella configurazione: ```bash openclaw config set proxy.enabled true @@ -92,51 +92,51 @@ openclaw gateway install --force openclaw gateway start ``` -Il fallback tramite ambiente è più adatto alle esecuzioni in foreground. Se lo usi con un servizio installato, metti `OPENCLAW_PROXY_URL` nell'ambiente durevole del servizio, ad esempio `$OPENCLAW_STATE_DIR/.env` o `~/.openclaw/.env`, quindi reinstalla il servizio in modo che launchd, systemd o Scheduled Tasks avviino il gateway con quel valore. +Il fallback dell'ambiente è più adatto alle esecuzioni in primo piano. Se lo usi con un servizio installato, inserisci `OPENCLAW_PROXY_URL` nell'ambiente durevole del servizio, come `$OPENCLAW_STATE_DIR/.env` o `~/.openclaw/.env`, quindi reinstalla il servizio in modo che launchd, systemd o Scheduled Tasks avvii il gateway con quel valore. -Per i comandi `openclaw --container ...`, OpenClaw inoltra `OPENCLAW_PROXY_URL` alla CLI figlia destinata al container quando è impostato. L'URL deve essere raggiungibile dall'interno del container; `127.0.0.1` si riferisce al container stesso, non all'host. OpenClaw rifiuta gli URL proxy di loopback per i comandi destinati ai container, a meno che non sovrascrivi esplicitamente quel controllo di sicurezza. +Per i comandi `openclaw --container ...`, OpenClaw inoltra `OPENCLAW_PROXY_URL` nella CLI figlia destinata al container quando è impostato. L'URL deve essere raggiungibile dall'interno del container; `127.0.0.1` si riferisce al container stesso, non all'host. OpenClaw rifiuta gli URL proxy di loopback per i comandi destinati al container, a meno che tu non sovrascriva esplicitamente quel controllo di sicurezza. ## Requisiti del proxy -Il criterio del proxy è il confine di sicurezza. OpenClaw non può verificare che il proxy blocchi le destinazioni corrette. +La policy del proxy è il confine di sicurezza. OpenClaw non può verificare che il proxy blocchi i target corretti. Configura il proxy per: -- Eseguire il bind solo a loopback o a un'interfaccia privata attendibile. +- Restare in ascolto solo su loopback o su un'interfaccia privata attendibile. - Limitare l'accesso in modo che solo il processo, l'host, il container o l'account di servizio OpenClaw possano usarlo. - Risolvere autonomamente le destinazioni e bloccare gli IP di destinazione dopo la risoluzione DNS. -- Applicare il criterio al momento della connessione sia per le richieste HTTP semplici sia per i tunnel HTTPS `CONNECT`. -- Rifiutare i bypass basati sulla destinazione per intervalli di loopback, privati, link-local, metadata, multicast, riservati o di documentazione. -- Evitare allowlist di nomi host a meno che tu non abbia piena fiducia nel percorso di risoluzione DNS. +- Applicare la policy al momento della connessione sia per le richieste HTTP in chiaro sia per i tunnel HTTPS `CONNECT`. +- Rifiutare bypass basati sulla destinazione per intervalli loopback, privati, link-local, metadati, multicast, riservati o di documentazione. +- Evitare allowlist di nomi host a meno che tu non consideri completamente attendibile il percorso di risoluzione DNS. - Registrare destinazione, decisione, stato e motivo senza registrare corpi delle richieste, header di autorizzazione, cookie o altri segreti. -- Mantenere il criterio del proxy sotto controllo versione e revisionare le modifiche come configurazione sensibile per la sicurezza. +- Mantenere la policy del proxy sotto controllo versione e rivedere le modifiche come configurazioni sensibili per la sicurezza. ## Destinazioni bloccate consigliate -Usa questa denylist come punto di partenza per qualsiasi proxy forward, firewall o criterio di egresso. +Usa questa denylist come punto di partenza per qualsiasi proxy forward, firewall o policy di egress. -La logica di classificazione a livello applicativo di OpenClaw si trova in `src/infra/net/ssrf.ts` e `src/shared/net/ip.ts`. Gli hook di parità rilevanti sono `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` e la gestione sentinella IPv4 incorporata per NAT64, 6to4, Teredo, ISATAP e forme IPv4-mapped. Questi file sono riferimenti utili quando si mantiene un criterio proxy esterno, ma OpenClaw non esporta né applica automaticamente tali regole nel tuo proxy. +La logica di classificazione a livello applicativo di OpenClaw si trova in `src/infra/net/ssrf.ts` e `src/shared/net/ip.ts`. Gli hook di parità rilevanti sono `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` e la gestione integrata dei sentinel IPv4 per NAT64, 6to4, Teredo, ISATAP e forme IPv4-mapped. Questi file sono riferimenti utili quando mantieni una policy proxy esterna, ma OpenClaw non esporta né applica automaticamente tali regole nel tuo proxy. -| Intervallo o host | Perché bloccarlo | -| ------------------------------------------------------------------------------------ | --------------------------------------------------- | -| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | Loopback IPv4 | -| `::1/128` | Loopback IPv6 | -| `0.0.0.0/8`, `::/128` | Indirizzi non specificati e di questa rete | -| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | Reti private RFC1918 | -| `169.254.0.0/16`, `fe80::/10` | Indirizzi link-local e percorsi comuni di metadata cloud | -| `169.254.169.254`, `metadata.google.internal` | Servizi di metadata cloud | -| `100.64.0.0/10` | Spazio di indirizzi condiviso NAT carrier-grade | -| `198.18.0.0/15`, `2001:2::/48` | Intervalli di benchmarking | -| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Intervalli special-use e di documentazione | -| `224.0.0.0/4`, `ff00::/8` | Multicast | -| `240.0.0.0/4` | IPv4 riservato | -| `fc00::/7`, `fec0::/10` | Intervalli IPv6 locali/privati | -| `100::/64`, `2001:20::/28` | Intervalli IPv6 discard e ORCHIDv2 | -| `64:ff9b::/96`, `64:ff9b:1::/48` | Prefissi NAT64 con IPv4 incorporato | -| `2002::/16`, `2001::/32` | 6to4 e Teredo con IPv4 incorporato | -| `::/96`, `::ffff:0:0/96` | IPv6 compatibile con IPv4 e IPv6 IPv4-mapped | +| Intervallo o host | Motivo del blocco | +| ------------------------------------------------------------------------------------ | ---------------------------------------------------- | +| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | Loopback IPv4 | +| `::1/128` | Loopback IPv6 | +| `0.0.0.0/8`, `::/128` | Indirizzi non specificati e this-network | +| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | Reti private RFC1918 | +| `169.254.0.0/16`, `fe80::/10` | Indirizzi link-local e percorsi comuni di metadati cloud | +| `169.254.169.254`, `metadata.google.internal` | Servizi di metadati cloud | +| `100.64.0.0/10` | Spazio indirizzi condiviso NAT carrier-grade | +| `198.18.0.0/15`, `2001:2::/48` | Intervalli di benchmarking | +| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Intervalli special-use e di documentazione | +| `224.0.0.0/4`, `ff00::/8` | Multicast | +| `240.0.0.0/4` | IPv4 riservato | +| `fc00::/7`, `fec0::/10` | Intervalli IPv6 locali/privati | +| `100::/64`, `2001:20::/28` | Intervalli IPv6 discard e ORCHIDv2 | +| `64:ff9b::/96`, `64:ff9b:1::/48` | Prefissi NAT64 con IPv4 incorporato | +| `2002::/16`, `2001::/32` | 6to4 e Teredo con IPv4 incorporato | +| `::/96`, `::ffff:0:0/96` | IPv6 compatibile con IPv4 e IPv6 IPv4-mapped | -Se il tuo provider cloud o la tua piattaforma di rete documenta host di metadata o intervalli riservati aggiuntivi, aggiungi anche quelli. +Se il tuo provider cloud o la tua piattaforma di rete documenta host di metadati o intervalli riservati aggiuntivi, aggiungi anche quelli. ## Validazione @@ -146,9 +146,9 @@ Valida il proxy dallo stesso host, container o account di servizio che esegue Op openclaw proxy validate --proxy-url http://127.0.0.1:3128 ``` -Per impostazione predefinita, quando non vengono fornite destinazioni personalizzate, il comando verifica che `https://example.com/` abbia successo e avvia un canary di loopback temporaneo che il proxy non deve raggiungere. Il controllo negato predefinito passa quando il proxy restituisce una risposta di negazione non 2xx oppure blocca il canary con un errore di trasporto; fallisce se una risposta riuscita raggiunge il canary. Se nessun proxy è abilitato e configurato, la validazione segnala un problema di configurazione; usa `--proxy-url` per un preflight una tantum prima di modificare la configurazione. Usa `--allowed-url` e `--denied-url` per testare aspettative specifiche della distribuzione. Le destinazioni negate personalizzate sono fail-closed: qualsiasi risposta HTTP significa che la destinazione era raggiungibile attraverso il proxy e qualsiasi errore di trasporto viene segnalato come inconcludente perché OpenClaw non può dimostrare che il proxy abbia bloccato un'origine raggiungibile. In caso di fallimento della validazione, il comando esce con codice 1. +Per impostazione predefinita, quando non vengono fornite destinazioni personalizzate, il comando verifica che `https://example.com/` abbia successo e avvia un canary temporaneo su loopback che il proxy non deve raggiungere. Il controllo negato predefinito passa quando il proxy restituisce una risposta di negazione non 2xx o blocca il canary con un errore di trasporto; fallisce se una risposta riuscita raggiunge il canary. Se nessun proxy è abilitato e configurato, la validazione segnala un problema di configurazione; usa `--proxy-url` per un preflight una tantum prima di modificare la configurazione. Usa `--allowed-url` e `--denied-url` per testare aspettative specifiche della distribuzione. Aggiungi `--apns-reachable` per verificare anche che la consegna APNs HTTP/2 diretta possa aprire un tunnel CONNECT attraverso il proxy e ricevere una risposta APNs sandbox; la sonda usa intenzionalmente un token provider non valido, quindi `403 InvalidProviderToken` è previsto e conta come raggiungibile. Le destinazioni negate personalizzate sono chiuse in caso di errore: qualsiasi risposta HTTP significa che la destinazione era raggiungibile tramite il proxy, e qualsiasi errore di trasporto viene segnalato come inconcludente perché OpenClaw non può provare che il proxy abbia bloccato un'origine raggiungibile. In caso di errore di validazione, il comando termina con codice 1. -Usa `--json` per l'automazione. L'output JSON contiene il risultato complessivo, la fonte effettiva della configurazione proxy, eventuali errori di configurazione e ogni controllo di destinazione. Le credenziali dell'URL proxy sono oscurate nell'output testuale e JSON: +Usa `--json` per l'automazione. L'output JSON contiene il risultato complessivo, la sorgente effettiva della configurazione proxy, eventuali errori di configurazione e ogni controllo di destinazione. Le credenziali dell'URL proxy vengono oscurate nell'output testuale e JSON: ```json { @@ -165,6 +165,12 @@ Usa `--json` per l'automazione. L'output JSON contiene il risultato complessivo, "url": "https://example.com/", "ok": true, "status": 200 + }, + { + "kind": "apns", + "url": "https://api.sandbox.push.apple.com", + "ok": true, + "status": 403 } ] } @@ -178,9 +184,9 @@ curl -x http://127.0.0.1:3128 http://127.0.0.1/ curl -x http://127.0.0.1:3128 http://169.254.169.254/ ``` -La richiesta pubblica dovrebbe riuscire. Le richieste loopback e di metadata dovrebbero essere bloccate dal proxy. Per `openclaw proxy validate`, il canary loopback integrato può distinguere un rifiuto del proxy da un'origine raggiungibile. I controlli `--denied-url` personalizzati non hanno quel canary, quindi considera sia le risposte HTTP sia gli errori di trasporto ambigui come errori di convalida, a meno che il tuo proxy non esponga un segnale di rifiuto specifico del deployment che puoi verificare separatamente. +La richiesta pubblica dovrebbe riuscire. Le richieste al loopback e ai metadati dovrebbero essere bloccate dal proxy. Per `openclaw proxy validate`, il canary di loopback integrato può distinguere un rifiuto del proxy da un'origine raggiungibile. I controlli `--denied-url` personalizzati non hanno quel canary, quindi considera sia le risposte HTTP sia gli errori di trasporto ambigui come errori di convalida, a meno che il tuo proxy non esponga un segnale di rifiuto specifico della distribuzione che puoi verificare separatamente. -Poi abilita il routing proxy di OpenClaw: +Poi abilita l'instradamento proxy di OpenClaw: ```bash openclaw config set proxy.enabled true @@ -199,10 +205,10 @@ proxy: ## Limiti - Il proxy migliora la copertura per i client HTTP e WebSocket JavaScript locali al processo, ma non è una sandbox di rete a livello di sistema operativo. -- Socket raw `net`, `tls` e `http2`, addon nativi e processi figli possono aggirare il routing proxy a livello Node, a meno che ereditino e rispettino le variabili d'ambiente del proxy. -- IRC è un canale TCP/TLS raw al di fuori del routing tramite forward proxy gestito dall'operatore. Nei deployment che richiedono che tutto il traffico in uscita passi attraverso quel forward proxy, imposta `channels.irc.enabled=false`, a meno che l'uscita IRC diretta non sia esplicitamente approvata. -- Il proxy di debug locale è uno strumento diagnostico e il suo inoltro diretto verso monte per richieste proxy e tunnel CONNECT è disabilitato per impostazione predefinita mentre la modalità proxy gestita è attiva; abilita l'inoltro diretto solo per diagnostica locale approvata. -- Le WebUI locali dell'utente e i server modello locali dovrebbero essere inseriti nella allowlist nella policy proxy dell'operatore quando necessario; OpenClaw non espone per essi un bypass generale della rete locale. -- Il bypass del proxy del piano di controllo del Gateway è intenzionalmente limitato a `localhost` e agli URL IP loopback letterali. Usa `ws://127.0.0.1:18789`, `ws://[::1]:18789` o `ws://localhost:18789` per connessioni locali dirette al piano di controllo del Gateway; gli altri nomi host vengono instradati come normale traffico basato su nome host. -- OpenClaw non ispeziona, testa né certifica la tua policy proxy. -- Considera le modifiche alla policy proxy come modifiche operative sensibili per la sicurezza. +- I socket raw `net`, `tls` e `http2`, gli addon nativi e i processi figli possono aggirare l'instradamento proxy a livello di Node, a meno che ereditino e rispettino le variabili d'ambiente del proxy. +- IRC è un canale TCP/TLS raw al di fuori dell'instradamento del proxy forward gestito dall'operatore. Nelle distribuzioni che richiedono che tutto il traffico in uscita passi attraverso quel proxy forward, imposta `channels.irc.enabled=false` a meno che l'uscita IRC diretta non sia approvata esplicitamente. +- Il proxy di debug locale è uno strumento diagnostico e il suo inoltro upstream diretto per le richieste proxy e i tunnel CONNECT è disabilitato per impostazione predefinita mentre la modalità proxy gestita è attiva; abilita l'inoltro diretto solo per diagnostica locale approvata. +- Le WebUI locali dell'utente e i server modello locali devono essere inseriti nella allowlist del criterio proxy dell'operatore quando necessario; OpenClaw non espone per loro un bypass generale della rete locale. +- Il bypass del proxy del piano di controllo del Gateway è intenzionalmente limitato a `localhost` e agli URL IP letterali di loopback. Usa `ws://127.0.0.1:18789`, `ws://[::1]:18789` o `ws://localhost:18789` per le connessioni locali dirette al piano di controllo del Gateway; gli altri nomi host vengono instradati come traffico ordinario basato su nome host. +- OpenClaw non ispeziona, testa né certifica il tuo criterio proxy. +- Tratta le modifiche al criterio proxy come modifiche operative sensibili per la sicurezza. diff --git a/docs/it/tools/thinking.md b/docs/it/tools/thinking.md index 80bcdedc9..b00ad11b3 100644 --- a/docs/it/tools/thinking.md +++ b/docs/it/tools/thinking.md @@ -1,13 +1,13 @@ --- read_when: - - Regolazione del ragionamento, della modalità rapida o dell'analisi o dei valori predefiniti della direttiva verbosa + - Regolazione dell’analisi o dei valori predefiniti delle direttive di ragionamento, modalità rapida o dettaglio summary: Sintassi delle direttive per /think, /fast, /verbose, /trace e visibilità del ragionamento title: Livelli di ragionamento x-i18n: - generated_at: "2026-05-04T07:09:38Z" + generated_at: "2026-05-04T18:24:37Z" model: gpt-5.5 provider: openai - source_hash: 6fa1b0a2b5f7b93a706488c3ad39dfe08c08eed0bdd30880eb4c07d730ee4d4f + source_hash: fcd1cd76ca5d0b08656e0629df656ad8aa037201d8de68093b3e46eb0708f811 source_path: tools/thinking.md workflow: 16 --- @@ -16,104 +16,105 @@ x-i18n: - Direttiva inline in qualsiasi corpo in ingresso: `/t `, `/think:` o `/thinking `. - Livelli (alias): `off | minimal | low | medium | high | xhigh | adaptive | max` - - minimal → “think” - - low → “think hard” - - medium → “think harder” + - minimal → “pensa” + - low → “pensa intensamente” + - medium → “pensa più intensamente” - high → “ultrathink” (budget massimo) - - xhigh → “ultrathink+” (modelli GPT-5.2+ e Codex, più effort di Anthropic Claude Opus 4.7) - - adaptive → ragionamento adattivo gestito dal provider (supportato per Claude 4.6 su Anthropic/Bedrock, Anthropic Claude Opus 4.7 e il ragionamento dinamico di Google Gemini) + - xhigh → “ultrathink+” (modelli GPT-5.2+ e Codex, più effort Anthropic Claude Opus 4.7) + - adaptive → thinking adattivo gestito dal provider (supportato per Claude 4.6 su Anthropic/Bedrock, Anthropic Claude Opus 4.7 e thinking dinamico di Google Gemini) - max → ragionamento massimo del provider (Anthropic Claude Opus 4.7; Ollama lo mappa al suo effort `think` nativo più alto) - - `x-high`, `x_high`, `extra-high`, `extra high` e `extra_high` vengono mappati a `xhigh`. - - `highest` viene mappato a `high`. + - `x-high`, `x_high`, `extra-high`, `extra high` ed `extra_high` mappano a `xhigh`. + - `highest` mappa a `high`. - Note sui provider: - - I menu e i selettori di ragionamento sono guidati dal profilo del provider. I Plugin provider dichiarano l'insieme esatto di livelli per il modello selezionato, incluse etichette come il valore binario `on`. - - `adaptive`, `xhigh` e `max` vengono pubblicizzati solo per i profili provider/modello che li supportano. Le direttive digitate per livelli non supportati vengono rifiutate con le opzioni valide per quel modello. - - I livelli non supportati già salvati vengono rimappati in base al rango del profilo del provider. `adaptive` ricade su `medium` sui modelli non adattivi, mentre `xhigh` e `max` ricadono sul livello non-`off` più grande supportato per il modello selezionato. - - I modelli Anthropic Claude 4.6 usano per impostazione predefinita `adaptive` quando non è impostato alcun livello di ragionamento esplicito. - - Anthropic Claude Opus 4.7 non usa il ragionamento adattivo per impostazione predefinita. Il default dell'effort della sua API resta di proprietà del provider, a meno che tu non imposti esplicitamente un livello di ragionamento. - - Anthropic Claude Opus 4.7 mappa `/think xhigh` al ragionamento adattivo più `output_config.effort: "xhigh"`, perché `/think` è una direttiva di ragionamento e `xhigh` è l'impostazione di effort di Opus 4.7. - - Anthropic Claude Opus 4.7 espone anche `/think max`; viene mappato allo stesso percorso di effort massimo di proprietà del provider. - - I modelli DeepSeek V4 espongono `/think xhigh|max`; entrambi vengono mappati a `reasoning_effort: "max"` di DeepSeek, mentre i livelli inferiori non-`off` vengono mappati a `high`. - - I modelli Ollama con capacità di ragionamento espongono `/think low|medium|high|max`; `max` viene mappato a `think: "high"` nativo perché l'API nativa di Ollama accetta le stringhe di effort `low`, `medium` e `high`. - - I modelli OpenAI GPT mappano `/think` tramite il supporto dell'effort specifico del modello nella Responses API. `/think off` invia `reasoning.effort: "none"` solo quando il modello di destinazione lo supporta; altrimenti OpenClaw omette il payload di ragionamento disabilitato invece di inviare un valore non supportato. - - Le voci di catalogo personalizzate compatibili con OpenAI possono abilitare `/think xhigh` impostando `models.providers..models[].compat.supportedReasoningEfforts` in modo da includere `"xhigh"`. Questo usa gli stessi metadati di compatibilità che mappano i payload di effort di ragionamento OpenAI in uscita, quindi menu, convalida della sessione, CLI dell'agente e `llm-task` concordano con il comportamento del trasporto. - - I riferimenti configurati obsoleti a OpenRouter Hunter Alpha saltano l'iniezione del ragionamento proxy perché quella route ritirata poteva restituire testo di risposta finale tramite campi di ragionamento. - - Google Gemini mappa `/think adaptive` al ragionamento dinamico di proprietà del provider di Gemini. Le richieste Gemini 3 omettono un `thinkingLevel` fisso, mentre le richieste Gemini 2.5 inviano `thinkingBudget: -1`; i livelli fissi vengono comunque mappati al `thinkingLevel` o al budget Gemini più vicino per quella famiglia di modelli. - - MiniMax (`minimax/*`) sul percorso di streaming compatibile con Anthropic usa per impostazione predefinita `thinking: { type: "disabled" }` a meno che tu non imposti esplicitamente il ragionamento nei parametri del modello o della richiesta. Questo evita delta `reasoning_content` trapelati dal formato di stream Anthropic non nativo di MiniMax. - - Z.AI (`zai/*`) supporta solo il ragionamento binario (`on`/`off`). Qualsiasi livello diverso da `off` viene trattato come `on` (mappato a `low`). - - Moonshot (`moonshot/*`) mappa `/think off` a `thinking: { type: "disabled" }` e qualsiasi livello diverso da `off` a `thinking: { type: "enabled" }`. Quando il ragionamento è abilitato, Moonshot accetta solo `tool_choice` `auto|none`; OpenClaw normalizza i valori incompatibili a `auto`. + - I menu e i selettori di thinking sono guidati dal profilo del provider. I Plugin provider dichiarano l'insieme esatto di livelli per il modello selezionato, incluse etichette come il binario `on`. + - `adaptive`, `xhigh` e `max` vengono pubblicizzati solo per profili provider/modello che li supportano. Le direttive digitate per livelli non supportati vengono rifiutate con le opzioni valide di quel modello. + - I livelli non supportati già salvati vengono rimappati in base al rango del profilo del provider. `adaptive` esegue il fallback a `medium` sui modelli non adattivi, mentre `xhigh` e `max` eseguono il fallback al livello non-off supportato più grande per il modello selezionato. + - I modelli Anthropic Claude 4.6 usano `adaptive` come valore predefinito quando non è impostato alcun livello di thinking esplicito. + - Anthropic Claude Opus 4.7 non usa il thinking adattivo come valore predefinito. Il valore predefinito di effort della sua API resta di proprietà del provider, a meno che tu non imposti esplicitamente un livello di thinking. + - Anthropic Claude Opus 4.7 mappa `/think xhigh` al thinking adattivo più `output_config.effort: "xhigh"`, perché `/think` è una direttiva di thinking e `xhigh` è l'impostazione di effort di Opus 4.7. + - Anthropic Claude Opus 4.7 espone anche `/think max`; mappa allo stesso percorso di effort massimo di proprietà del provider. + - I modelli DeepSeek V4 espongono `/think xhigh|max`; entrambi mappano a `reasoning_effort: "max"` di DeepSeek, mentre i livelli non-off inferiori mappano a `high`. + - I modelli Ollama con capacità di thinking espongono `/think low|medium|high|max`; `max` mappa al `think: "high"` nativo perché l'API nativa di Ollama accetta le stringhe di effort `low`, `medium` e `high`. + - I modelli OpenAI GPT mappano `/think` attraverso il supporto dell'effort dell'API Responses specifico del modello. `/think off` invia `reasoning.effort: "none"` solo quando il modello di destinazione lo supporta; altrimenti OpenClaw omette il payload di ragionamento disabilitato invece di inviare un valore non supportato. + - Le voci di catalogo personalizzate compatibili con OpenAI possono abilitare `/think xhigh` impostando `models.providers..models[].compat.supportedReasoningEfforts` in modo da includere `"xhigh"`. Questo usa gli stessi metadati di compatibilità che mappano i payload in uscita dell'effort di ragionamento OpenAI, quindi menu, convalida di sessione, CLI dell'agente e `llm-task` concordano con il comportamento di trasporto. + - I riferimenti OpenRouter Hunter Alpha configurati e obsoleti saltano l'iniezione di ragionamento del proxy perché quella rotta ritirata poteva restituire testo di risposta finale tramite campi di ragionamento. + - Google Gemini mappa `/think adaptive` al thinking dinamico di proprietà del provider di Gemini. Le richieste Gemini 3 omettono un `thinkingLevel` fisso, mentre le richieste Gemini 2.5 inviano `thinkingBudget: -1`; i livelli fissi continuano a mappare al `thinkingLevel` o budget Gemini più vicino per quella famiglia di modelli. + - MiniMax (`minimax/*`) sul percorso di streaming compatibile con Anthropic usa per impostazione predefinita `thinking: { type: "disabled" }`, a meno che tu non imposti esplicitamente il thinking nei parametri del modello o della richiesta. Questo evita delta `reasoning_content` trapelati dal formato di stream Anthropic non nativo di MiniMax. + - Z.AI (`zai/*`) supporta solo il thinking binario (`on`/`off`). Qualsiasi livello diverso da `off` viene trattato come `on` (mappato a `low`). + - Moonshot (`moonshot/*`) mappa `/think off` a `thinking: { type: "disabled" }` e qualsiasi livello diverso da `off` a `thinking: { type: "enabled" }`. Quando il thinking è abilitato, Moonshot accetta solo `tool_choice` `auto|none`; OpenClaw normalizza i valori incompatibili su `auto`. ## Ordine di risoluzione 1. Direttiva inline sul messaggio (si applica solo a quel messaggio). -2. Override della sessione (impostato inviando un messaggio composto solo dalla direttiva). -3. Default per agente (`agents.list[].thinkingDefault` nella configurazione). -4. Default globale (`agents.defaults.thinkingDefault` nella configurazione). -5. Fallback: default dichiarato dal provider quando disponibile; altrimenti i modelli con capacità di ragionamento si risolvono a `medium` o al livello non-`off` supportato più vicino per quel modello, mentre i modelli senza ragionamento restano `off`. +2. Override di sessione (impostato inviando un messaggio contenente solo la direttiva). +3. Valore predefinito per agente (`agents.list[].thinkingDefault` nella configurazione). +4. Valore predefinito globale (`agents.defaults.thinkingDefault` nella configurazione). +5. Fallback: valore predefinito dichiarato dal provider quando disponibile; altrimenti i modelli con capacità di ragionamento risolvono a `medium` o al livello non-`off` supportato più vicino per quel modello, e i modelli senza ragionamento restano `off`. -## Impostare un default di sessione +## Impostare un valore predefinito di sessione - Invia un messaggio che contiene **solo** la direttiva (spazi consentiti), ad esempio `/think:medium` o `/t high`. -- Rimane valido per la sessione corrente (per mittente per impostazione predefinita); viene cancellato da `/think:off` o dal reset per inattività della sessione. +- Rimane attivo per la sessione corrente (per mittente per impostazione predefinita); viene cancellato da `/think:off` o dal reset per inattività della sessione. - Viene inviata una risposta di conferma (`Thinking level set to high.` / `Thinking disabled.`). Se il livello non è valido (ad esempio `/thinking big`), il comando viene rifiutato con un suggerimento e lo stato della sessione resta invariato. -- Invia `/think` (o `/think:`) senza argomento per vedere il livello di ragionamento corrente. +- Invia `/think` (o `/think:`) senza argomento per vedere il livello di thinking corrente. ## Applicazione per agente - **Pi incorporato**: il livello risolto viene passato al runtime dell'agente Pi in-process. +- **Backend CLI Claude**: i livelli diversi da off vengono passati a Claude Code come `--effort` quando si usa `claude-cli`; vedi [backend CLI](/it/gateway/cli-backends). ## Modalità veloce (/fast) - Livelli: `on|off`. -- Un messaggio composto solo dalla direttiva attiva o disattiva un override della modalità veloce di sessione e risponde `Fast mode enabled.` / `Fast mode disabled.`. +- Un messaggio contenente solo la direttiva alterna un override di sessione della modalità veloce e risponde `Fast mode enabled.` / `Fast mode disabled.`. - Invia `/fast` (o `/fast status`) senza modalità per vedere lo stato effettivo corrente della modalità veloce. - OpenClaw risolve la modalità veloce in questo ordine: - 1. Inline/solo direttiva `/fast on|off` - 2. Override della sessione - 3. Default per agente (`agents.list[].fastModeDefault`) + 1. `/fast on|off` inline/contenente solo la direttiva + 2. Override di sessione + 3. Valore predefinito per agente (`agents.list[].fastModeDefault`) 4. Configurazione per modello: `agents.defaults.models["/"].params.fastMode` 5. Fallback: `off` -- Per `openai/*`, la modalità veloce viene mappata all'elaborazione prioritaria di OpenAI inviando `service_tier=priority` nelle richieste Responses supportate. -- Per `openai-codex/*`, la modalità veloce invia lo stesso flag `service_tier=priority` nelle Responses Codex. OpenClaw mantiene un singolo toggle `/fast` condiviso tra entrambi i percorsi di autenticazione. -- Per le richieste pubbliche dirette `anthropic/*`, incluso il traffico autenticato tramite OAuth inviato a `api.anthropic.com`, la modalità veloce viene mappata ai tier di servizio Anthropic: `/fast on` imposta `service_tier=auto`, `/fast off` imposta `service_tier=standard_only`. +- Per `openai/*`, la modalità veloce mappa all'elaborazione prioritaria OpenAI inviando `service_tier=priority` sulle richieste Responses supportate. +- Per `openai-codex/*`, la modalità veloce invia lo stesso flag `service_tier=priority` sulle Responses Codex. OpenClaw mantiene un unico toggle `/fast` condiviso tra entrambi i percorsi di autenticazione. +- Per le richieste pubbliche dirette `anthropic/*`, incluso il traffico autenticato tramite OAuth inviato a `api.anthropic.com`, la modalità veloce mappa ai tier di servizio Anthropic: `/fast on` imposta `service_tier=auto`, `/fast off` imposta `service_tier=standard_only`. - Per `minimax/*` sul percorso compatibile con Anthropic, `/fast on` (o `params.fastMode: true`) riscrive `MiniMax-M2.7` in `MiniMax-M2.7-highspeed`. -- I parametri modello Anthropic espliciti `serviceTier` / `service_tier` sovrascrivono il default della modalità veloce quando entrambi sono impostati. OpenClaw salta comunque l'iniezione del tier di servizio Anthropic per gli URL base proxy non Anthropic. +- I parametri modello Anthropic espliciti `serviceTier` / `service_tier` sovrascrivono il valore predefinito della modalità veloce quando entrambi sono impostati. OpenClaw continua a saltare l'iniezione del tier di servizio Anthropic per URL base proxy non Anthropic. - `/status` mostra `Fast` solo quando la modalità veloce è abilitata. ## Direttive verbose (/verbose o /v) -- Livelli: `on` (minimo) | `full` | `off` (default). -- Un messaggio composto solo dalla direttiva attiva o disattiva il verbose di sessione e risponde `Verbose logging enabled.` / `Verbose logging disabled.`; i livelli non validi restituiscono un suggerimento senza modificare lo stato. -- `/verbose off` salva un override esplicito di sessione; cancellalo tramite l'interfaccia Sessions scegliendo `inherit`. -- La direttiva inline influisce solo su quel messaggio; altrimenti si applicano i default di sessione/globali. +- Livelli: `on` (minimale) | `full` | `off` (predefinito). +- Un messaggio contenente solo la direttiva alterna il verbose di sessione e risponde `Verbose logging enabled.` / `Verbose logging disabled.`; i livelli non validi restituiscono un suggerimento senza modificare lo stato. +- `/verbose off` salva un override di sessione esplicito; cancellalo tramite l'interfaccia utente Sessioni scegliendo `inherit`. +- La direttiva inline influisce solo su quel messaggio; in caso contrario si applicano i valori predefiniti di sessione/globali. - Invia `/verbose` (o `/verbose:`) senza argomento per vedere il livello verbose corrente. -- Quando verbose è attivo, gli agenti che emettono risultati strutturati degli strumenti (Pi, altri agenti JSON) inviano ogni chiamata strumento come un proprio messaggio solo metadati, con prefisso ` : ` quando disponibile. Questi riepiloghi degli strumenti vengono inviati appena ogni strumento si avvia (bolle separate), non come delta di streaming. -- I riepiloghi degli errori degli strumenti restano visibili in modalità normale, ma i suffissi con i dettagli grezzi dell'errore sono nascosti a meno che verbose sia `on` o `full`. +- Quando verbose è attivo, gli agenti che emettono risultati strutturati degli strumenti (Pi, altri agenti JSON) rinviano ogni chiamata di strumento come messaggio separato contenente solo metadati, con prefisso ` : ` quando disponibile. Questi riepiloghi degli strumenti vengono inviati appena ogni strumento si avvia (bolle separate), non come delta di streaming. +- I riepiloghi degli errori degli strumenti restano visibili in modalità normale, ma i suffissi con i dettagli grezzi degli errori sono nascosti a meno che verbose sia `on` o `full`. - Quando verbose è `full`, anche gli output degli strumenti vengono inoltrati dopo il completamento (bolla separata, troncata a una lunghezza sicura). Se attivi `/verbose on|full|off` mentre un'esecuzione è in corso, le bolle successive degli strumenti rispettano la nuova impostazione. -- `agents.defaults.toolProgressDetail` controlla la forma dei riepiloghi strumenti di `/verbose` e delle righe strumenti nelle bozze di avanzamento. Usa `"explain"` (default) per etichette umane compatte come `🛠️ Exec: checking JS syntax`; usa `"raw"` quando vuoi anche il comando/dettaglio grezzo aggiunto per il debug. `agents.list[].toolProgressDetail` per agente sovrascrive il default. +- `agents.defaults.toolProgressDetail` controlla la forma dei riepiloghi degli strumenti di `/verbose` e delle righe strumento delle bozze di avanzamento. Usa `"explain"` (predefinito) per etichette umane compatte come `🛠️ Exec: checking JS syntax`; usa `"raw"` quando vuoi anche il comando/dettaglio grezzo aggiunto per il debug. `agents.list[].toolProgressDetail` per agente sovrascrive il valore predefinito. - `explain`: `🛠️ Exec: check JS syntax for /tmp/app.js` - `raw`: `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js` -## Direttive di trace dei Plugin (/trace) +## Direttive di tracciamento Plugin (/trace) -- Livelli: `on` | `off` (default). -- Un messaggio composto solo dalla direttiva attiva o disattiva l'output di trace Plugin della sessione e risponde `Plugin trace enabled.` / `Plugin trace disabled.`. -- La direttiva inline influisce solo su quel messaggio; altrimenti si applicano i default di sessione/globali. -- Invia `/trace` (o `/trace:`) senza argomento per vedere il livello di trace corrente. -- `/trace` è più ristretto di `/verbose`: espone solo righe di trace/debug di proprietà del Plugin, come i riepiloghi di debug di Active Memory. -- Le righe di trace possono apparire in `/status` e come messaggio diagnostico di follow-up dopo la normale risposta dell'assistente. +- Livelli: `on` | `off` (predefinito). +- Un messaggio contenente solo la direttiva alterna l'output di tracciamento Plugin della sessione e risponde `Plugin trace enabled.` / `Plugin trace disabled.`. +- La direttiva inline influisce solo su quel messaggio; in caso contrario si applicano i valori predefiniti di sessione/globali. +- Invia `/trace` (o `/trace:`) senza argomento per vedere il livello di tracciamento corrente. +- `/trace` è più ristretto di `/verbose`: espone solo righe di traccia/debug di proprietà del Plugin, come i riepiloghi di debug di Active Memory. +- Le righe di traccia possono apparire in `/status` e come messaggio diagnostico successivo dopo la normale risposta dell'assistente. ## Visibilità del ragionamento (/reasoning) - Livelli: `on|off|stream`. -- Un messaggio composto solo dalla direttiva attiva o disattiva la visualizzazione dei blocchi di ragionamento nelle risposte. +- Un messaggio contenente solo la direttiva alterna la visualizzazione dei blocchi di thinking nelle risposte. - Quando abilitato, il ragionamento viene inviato come **messaggio separato** con prefisso `Reasoning:`. - `stream` (solo Telegram): trasmette in streaming il ragionamento nella bolla bozza di Telegram mentre la risposta viene generata, poi invia la risposta finale senza ragionamento. - Alias: `/reason`. - Invia `/reasoning` (o `/reasoning:`) senza argomento per vedere il livello di ragionamento corrente. -- Ordine di risoluzione: direttiva inline, poi override della sessione, poi default per agente (`agents.list[].reasoningDefault`), poi fallback (`off`). +- Ordine di risoluzione: direttiva inline, poi override di sessione, poi valore predefinito per agente (`agents.list[].reasoningDefault`), poi fallback (`off`). -I tag di ragionamento dei modelli locali malformati vengono gestiti in modo conservativo. I blocchi chiusi `...` restano nascosti nelle risposte normali, e anche il ragionamento non chiuso dopo testo già visibile viene nascosto. Se una risposta è interamente racchiusa in un singolo tag di apertura non chiuso e altrimenti verrebbe consegnata come testo vuoto, OpenClaw rimuove il tag di apertura malformato e consegna il testo restante. +I tag di ragionamento dei modelli locali malformati vengono gestiti in modo conservativo. I blocchi `...` chiusi restano nascosti nelle risposte normali, e anche il ragionamento non chiuso dopo testo già visibile viene nascosto. Se una risposta è interamente racchiusa in un singolo tag di apertura non chiuso e altrimenti verrebbe consegnata come testo vuoto, OpenClaw rimuove il tag di apertura malformato e consegna il testo rimanente. ## Correlati @@ -121,23 +122,23 @@ I tag di ragionamento dei modelli locali malformati vengono gestiti in modo cons ## Heartbeat -- Il corpo della sonda Heartbeat è il prompt Heartbeat configurato (default: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Le direttive inline in un messaggio Heartbeat si applicano come al solito (ma evita di modificare i default di sessione dagli Heartbeat). -- La consegna Heartbeat usa per impostazione predefinita solo il payload finale. Per inviare anche il messaggio separato `Reasoning:` (quando disponibile), imposta `agents.defaults.heartbeat.includeReasoning: true` o `agents.list[].heartbeat.includeReasoning: true` per agente. +- Il corpo della sonda Heartbeat è il prompt Heartbeat configurato (predefinito: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Le direttive inline in un messaggio Heartbeat si applicano come di consueto (ma evita di modificare i valori predefiniti di sessione dagli Heartbeat). +- La consegna Heartbeat usa per impostazione predefinita solo il payload finale. Per inviare anche il messaggio `Reasoning:` separato (quando disponibile), imposta `agents.defaults.heartbeat.includeReasoning: true` o `agents.list[].heartbeat.includeReasoning: true` per agente. ## Interfaccia web chat -- Il selettore di ragionamento della web chat rispecchia il livello salvato della sessione dallo store/config della sessione in ingresso quando la pagina viene caricata. -- Scegliere un altro livello scrive immediatamente l'override di sessione tramite `sessions.patch`; non attende il prossimo invio e non è un override `thinkingOnce` usa e getta. -- La prima opzione è sempre `Default ()`, dove il default risolto deriva dal profilo di ragionamento del provider del modello della sessione attiva più la stessa logica di fallback usata da `/status` e `session_status`. -- Il selettore usa `thinkingLevels` restituito dalla riga/default della sessione del Gateway, con `thinkingOptions` mantenuto come elenco etichette legacy. L'interfaccia browser non mantiene un proprio elenco regex dei provider; i Plugin possiedono gli insiemi di livelli specifici del modello. -- `/think:` funziona ancora e aggiorna lo stesso livello di sessione salvato, quindi le direttive chat e il selettore restano sincronizzati. +- Il selettore di thinking della chat web rispecchia il livello salvato della sessione dallo store/configurazione della sessione in ingresso quando la pagina viene caricata. +- La scelta di un altro livello scrive immediatamente l'override di sessione tramite `sessions.patch`; non attende il prossimo invio e non è un override `thinkingOnce` valido per una sola volta. +- La prima opzione è sempre `Default ()`, dove il valore predefinito risolto proviene dal profilo di thinking del provider del modello di sessione attivo più la stessa logica di fallback usata da `/status` e `session_status`. +- Il selettore usa `thinkingLevels` restituito dalla riga/impostazioni predefinite della sessione del Gateway, con `thinkingOptions` mantenuto come elenco di etichette legacy. L'interfaccia utente del browser non mantiene un proprio elenco regex di provider; i Plugin possiedono gli insiemi di livelli specifici per modello. +- `/think:` continua a funzionare e aggiorna lo stesso livello di sessione salvato, quindi le direttive della chat e il selettore restano sincronizzati. ## Profili provider -- I Plugin provider possono esporre `resolveThinkingProfile(ctx)` per definire i livelli supportati dal modello e il valore predefinito. -- I Plugin provider che fungono da proxy per i modelli Claude dovrebbero riutilizzare `resolveClaudeThinkingProfile(modelId)` da `openclaw/plugin-sdk/provider-model-shared`, in modo che Anthropic diretto e i cataloghi proxy restino allineati. +- I plugin provider possono esporre `resolveThinkingProfile(ctx)` per definire i livelli supportati dal modello e il valore predefinito. +- I plugin provider che inoltrano modelli Claude tramite proxy devono riutilizzare `resolveClaudeThinkingProfile(modelId)` da `openclaw/plugin-sdk/provider-model-shared` in modo che i cataloghi Anthropic diretti e quelli proxy restino allineati. - Ogni livello del profilo ha un `id` canonico memorizzato (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive` o `max`) e può includere una `label` di visualizzazione. I provider binari usano `{ id: "low", label: "on" }`. -- I Plugin strumento che devono convalidare un override esplicito del ragionamento dovrebbero usare `api.runtime.agent.resolveThinkingPolicy({ provider, model })` più `api.runtime.agent.normalizeThinkingLevel(...)`; non dovrebbero mantenere elenchi propri di livelli per provider/modello. -- I Plugin strumento con accesso ai metadati configurati dei modelli personalizzati possono passare `catalog` a `resolveThinkingPolicy`, così gli opt-in `compat.supportedReasoningEfforts` vengono riflessi nella convalida lato plugin. -- Gli hook legacy pubblicati (`supportsXHighThinking`, `isBinaryThinking` e `resolveDefaultThinkingLevel`) restano adattatori di compatibilità, ma i nuovi insiemi di livelli personalizzati dovrebbero usare `resolveThinkingProfile`. -- Le righe/i valori predefiniti del Gateway espongono `thinkingLevels`, `thinkingOptions` e `thinkingDefault` così i client ACP/chat mostrano gli stessi id e label di profilo usati dalla convalida runtime. +- I plugin degli strumenti che devono convalidare un override esplicito del ragionamento devono usare `api.runtime.agent.resolveThinkingPolicy({ provider, model })` più `api.runtime.agent.normalizeThinkingLevel(...)`; non devono mantenere proprie liste di livelli per provider/modello. +- I plugin degli strumenti con accesso ai metadati configurati dei modelli personalizzati possono passare `catalog` a `resolveThinkingPolicy` in modo che le adesioni esplicite di `compat.supportedReasoningEfforts` si riflettano nella convalida lato plugin. +- Gli hook legacy pubblicati (`supportsXHighThinking`, `isBinaryThinking` e `resolveDefaultThinkingLevel`) restano come adattatori di compatibilità, ma i nuovi insiemi di livelli personalizzati devono usare `resolveThinkingProfile`. +- Le righe e i valori predefiniti del Gateway espongono `thinkingLevels`, `thinkingOptions` e `thinkingDefault` in modo che i client ACP/chat visualizzino gli stessi id e label del profilo usati dalla convalida a runtime.