From 44b7b09728ad0d5eaeb5cea59f95b4ff00c1a123 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 24 Apr 2026 15:24:53 +0000 Subject: [PATCH] chore(i18n): refresh it translations --- docs/it/cli/plugins.md | 193 +++++----------- docs/it/concepts/model-providers.md | 344 ++++++++++++---------------- docs/it/pi.md | 248 ++++++++++---------- docs/it/providers/deepseek.md | 38 +-- docs/it/tools/plugin.md | 245 +++++++++++--------- 5 files changed, 492 insertions(+), 576 deletions(-) diff --git a/docs/it/cli/plugins.md b/docs/it/cli/plugins.md index 6bdbdb3cb..429f896e8 100644 --- a/docs/it/cli/plugins.md +++ b/docs/it/cli/plugins.md @@ -1,14 +1,14 @@ --- read_when: - Vuoi installare o gestire Plugin Gateway o bundle compatibili - - Vuoi eseguire il debug di errori di caricamento dei Plugin + - Vuoi eseguire il debug degli errori di caricamento del Plugin summary: Riferimento CLI per `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor) title: Plugin x-i18n: - generated_at: "2026-04-24T08:34:52Z" + generated_at: "2026-04-24T15:23:22Z" model: gpt-5.4 provider: openai - source_hash: 35ef8f54c64ea52d7618a0ef8b90d3d75841a27ae4cd689b4ca8e0cfdcddc408 + source_hash: bc693d5e3bc49057e1a108ba65a4dcb3bb662c00229e6fa38a0335afba8240e5 source_path: cli/plugins.md workflow: 15 --- @@ -20,7 +20,7 @@ Gestisci Plugin Gateway, pacchetti hook e bundle compatibili. Correlati: - Sistema Plugin: [Plugin](/it/tools/plugin) -- Compatibilità bundle: [Bundle Plugin](/it/plugins/bundles) +- Compatibilità dei bundle: [Bundle Plugin](/it/plugins/bundles) - Manifest Plugin + schema: [Manifest Plugin](/it/plugins/manifest) - Hardening della sicurezza: [Sicurezza](/it/gateway/security) @@ -46,24 +46,19 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -I Plugin bundle sono inclusi con OpenClaw. Alcuni sono abilitati per impostazione predefinita (ad esempio -provider di modelli bundle, provider vocali bundle e il Plugin browser -bundle); altri richiedono `plugins enable`. +I Plugin inclusi vengono distribuiti con OpenClaw. Alcuni sono abilitati per impostazione predefinita (per esempio i provider di modelli inclusi, i provider vocali inclusi e il plugin browser incluso); altri richiedono `plugins enable`. -I Plugin OpenClaw nativi devono includere `openclaw.plugin.json` con uno JSON -Schema inline (`configSchema`, anche se vuoto). I bundle compatibili usano invece i propri manifest bundle. +I Plugin OpenClaw nativi devono includere `openclaw.plugin.json` con uno schema JSON inline (`configSchema`, anche se vuoto). I bundle compatibili usano invece i propri manifest di bundle. -`plugins list` mostra `Format: openclaw` oppure `Format: bundle`. L'output dettagliato di list/info -mostra anche il sottotipo del bundle (`codex`, `claude` o `cursor`) più le capacità del bundle -rilevate. +`plugins list` mostra `Format: openclaw` oppure `Format: bundle`. L'output dettagliato di list/info mostra anche il sottotipo di bundle (`codex`, `claude` o `cursor`) oltre alle funzionalità del bundle rilevate. ### Installazione ```bash openclaw plugins install # prima ClawHub, poi npm openclaw plugins install clawhub: # solo ClawHub -openclaw plugins install --force # sovrascrive l'installazione esistente -openclaw plugins install --pin # fissa la versione +openclaw plugins install --force # sovrascrive un'installazione esistente +openclaw plugins install --pin # blocca la versione openclaw plugins install --dangerously-force-unsafe-install openclaw plugins install # percorso locale openclaw plugins install @ # marketplace @@ -71,79 +66,48 @@ openclaw plugins install --marketplace # marketplace (esplicito openclaw plugins install --marketplace https://github.com// ``` -I nomi pacchetto non qualificati vengono controllati prima in ClawHub, poi in npm. Nota di sicurezza: -tratta le installazioni di Plugin come esecuzione di codice. Preferisci versioni fissate. +I nomi di pacchetto semplici vengono controllati prima in ClawHub, poi in npm. Nota di sicurezza: considera l'installazione dei plugin come esecuzione di codice. Preferisci versioni bloccate. -Se la tua sezione `plugins` è supportata da un singolo `$include` a file singolo, `plugins install/update/enable/disable/uninstall` scrivono in quel file incluso e lasciano `openclaw.json` invariato. Include root, array di include e include con override sibling falliscono in modalità fail-closed invece di appiattirsi. Vedi [Config includes](/it/gateway/configuration) per le forme supportate. +Se la sezione `plugins` è supportata da un singolo `$include` in un file, `plugins install/update/enable/disable/uninstall` scrive in quel file incluso e lascia invariato `openclaw.json`. Gli include radice, gli array di include e gli include con override affiancati falliscono in modalità chiusa invece di essere appiattiti. Consulta [Config includes](/it/gateway/configuration) per le forme supportate. -Se la configurazione non è valida, `plugins install` normalmente fallisce in modalità fail-closed e ti dice di -eseguire prima `openclaw doctor --fix`. L'unica eccezione documentata è un percorso ristretto -di recupero dei Plugin bundle per Plugin che scelgono esplicitamente -`openclaw.install.allowInvalidConfigRecovery`. +Se la configurazione non è valida, `plugins install` normalmente fallisce in modalità chiusa e ti indica di eseguire prima `openclaw doctor --fix`. L'unica eccezione documentata è un percorso ristretto di recupero per plugin inclusi che scelgono esplicitamente `openclaw.install.allowInvalidConfigRecovery`. -`--force` riusa la destinazione di installazione esistente e sovrascrive sul posto un -Plugin o pacchetto hook già installato. Usalo quando stai intenzionalmente reinstallando -lo stesso id da un nuovo percorso locale, archivio, pacchetto ClawHub o artefatto npm. -Per aggiornamenti ordinari di un Plugin npm già tracciato, preferisci -`openclaw plugins update `. +`--force` riutilizza la destinazione di installazione esistente e sovrascrive sul posto un plugin o un pacchetto hook già installato. Usalo quando vuoi intenzionalmente reinstallare lo stesso id da un nuovo percorso locale, archivio, pacchetto ClawHub o artefatto npm. Per aggiornamenti ordinari di un plugin npm già tracciato, preferisci `openclaw plugins update `. -Se esegui `plugins install` per un id Plugin già installato, OpenClaw -si ferma e ti indirizza a `plugins update ` per un normale aggiornamento, -oppure a `plugins install --force` quando vuoi davvero sovrascrivere -l'installazione corrente da una sorgente diversa. +Se esegui `plugins install` per un id plugin già installato, OpenClaw si interrompe e ti indirizza a `plugins update ` per un aggiornamento normale, oppure a `plugins install --force` quando vuoi davvero sovrascrivere l'installazione corrente da una sorgente diversa. -`--pin` si applica solo alle installazioni npm. Non è supportato con `--marketplace`, -perché le installazioni marketplace persistono metadati della sorgente marketplace invece di una -specifica npm. +`--pin` si applica solo alle installazioni npm. Non è supportato con `--marketplace`, perché le installazioni da marketplace salvano i metadati della sorgente marketplace invece di una specifica npm. -`--dangerously-force-unsafe-install` è un'opzione break-glass per i falsi positivi -nello scanner integrato di codice pericoloso. Consente all'installazione di continuare anche -quando lo scanner integrato riporta risultati `critical`, ma **non** -aggira i blocchi di policy degli hook Plugin `before_install` e **non** aggira i -fallimenti della scansione. +`--dangerously-force-unsafe-install` è un'opzione di emergenza per i falsi positivi nel rilevatore integrato di codice pericoloso. Consente all'installazione di proseguire anche quando il rilevatore integrato riporta risultati `critical`, ma **non** aggira i blocchi di policy degli hook `before_install` del plugin e **non** aggira i fallimenti della scansione. -Questo flag CLI si applica ai flussi di installazione/aggiornamento dei Plugin. Le installazioni di dipendenze delle skill -supportate da Gateway usano l'override di richiesta corrispondente `dangerouslyForceUnsafeInstall`, mentre `openclaw skills install` resta un flusso separato di -download/installazione delle skill da ClawHub. +Questo flag CLI si applica ai flussi di installazione/aggiornamento dei plugin. Le installazioni delle dipendenze delle Skills supportate da Gateway usano l'override di richiesta corrispondente `dangerouslyForceUnsafeInstall`, mentre `openclaw skills install` resta un flusso separato di download/installazione di Skills da ClawHub. -`plugins install` è anche la superficie di installazione per i pacchetti hook che espongono -`openclaw.hooks` in `package.json`. Usa `openclaw hooks` per la -visibilità filtrata degli hook e l'abilitazione per singolo hook, non per l'installazione dei package. +`plugins install` è anche la superficie di installazione per i pacchetti hook che espongono `openclaw.hooks` in `package.json`. Usa `openclaw hooks` per la visibilità filtrata degli hook e l'abilitazione per singolo hook, non per l'installazione del pacchetto. -Le specifiche npm sono **solo registry** (nome pacchetto + **versione esatta** facoltativa o -**dist-tag**). Le specifiche Git/URL/file e gli intervalli semver sono rifiutati. Le -installazioni delle dipendenze vengono eseguite con `--ignore-scripts` per sicurezza. +Le specifiche npm sono **solo registry** (nome pacchetto + **versione esatta** opzionale o **dist-tag**). Le specifiche Git/URL/file e gli intervalli semver vengono rifiutati. Le installazioni delle dipendenze vengono eseguite con `--ignore-scripts` per sicurezza. -Le specifiche non qualificate e `@latest` restano sul canale stabile. Se npm risolve -una di queste a una prerelease, OpenClaw si ferma e ti chiede di aderire esplicitamente con un -tag prerelease come `@beta`/`@rc` o una versione prerelease esatta come -`@1.2.3-beta.4`. +Le specifiche semplici e `@latest` restano sul canale stabile. Se npm risolve una di queste in una prerelease, OpenClaw si interrompe e ti chiede di aderire esplicitamente con un tag prerelease come `@beta`/`@rc` oppure con una versione prerelease esatta come `@1.2.3-beta.4`. -Se una specifica di installazione non qualificata corrisponde a un id Plugin bundle (ad esempio `diffs`), OpenClaw -installa direttamente il Plugin bundle. Per installare un package npm con lo stesso -nome, usa una specifica con scope esplicita (ad esempio `@scope/diffs`). +Se una specifica di installazione semplice corrisponde all'id di un plugin incluso (per esempio `diffs`), OpenClaw installa direttamente il plugin incluso. Per installare un pacchetto npm con lo stesso nome, usa una specifica scoped esplicita (per esempio `@scope/diffs`). Archivi supportati: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Sono supportate anche le installazioni dal marketplace Claude. -Le installazioni ClawHub usano un locator esplicito `clawhub:`: +Le installazioni ClawHub usano un localizzatore esplicito `clawhub:`: ```bash openclaw plugins install clawhub:openclaw-codex-app-server openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3 ``` -OpenClaw ora preferisce anche ClawHub per specifiche Plugin non qualificate sicure per npm. Ripiega -su npm solo se ClawHub non ha quel package o quella versione: +OpenClaw ora preferisce anche ClawHub per le specifiche di plugin semplici sicure per npm. Passa a npm solo se ClawHub non dispone di quel pacchetto o di quella versione: ```bash openclaw plugins install openclaw-codex-app-server ``` -OpenClaw scarica l'archivio del package da ClawHub, controlla la compatibilità -pubblicizzata dell'API Plugin / gateway minimo, poi lo installa tramite il normale -percorso archivio. Le installazioni registrate mantengono i propri metadati della sorgente ClawHub per aggiornamenti successivi. +OpenClaw scarica l'archivio del pacchetto da ClawHub, controlla la compatibilità dichiarata dell'API plugin / versione minima del gateway, quindi lo installa tramite il normale percorso per archivi. Le installazioni registrate mantengono i metadati della sorgente ClawHub per gli aggiornamenti successivi. Usa la forma abbreviata `plugin@marketplace` quando il nome del marketplace esiste nella cache del registro locale di Claude in `~/.claude/plugins/known_marketplaces.json`: @@ -152,7 +116,7 @@ openclaw plugins marketplace list openclaw plugins install @ ``` -Usa `--marketplace` quando vuoi passare esplicitamente la sorgente marketplace: +Usa `--marketplace` quando vuoi passare esplicitamente la sorgente del marketplace: ```bash openclaw plugins install --marketplace @@ -164,28 +128,21 @@ openclaw plugins install --marketplace ./my-marketplace Le sorgenti marketplace possono essere: - un nome di marketplace noto a Claude da `~/.claude/plugins/known_marketplaces.json` -- una root marketplace locale o un percorso `marketplace.json` -- una forma abbreviata repo GitHub come `owner/repo` -- un URL repo GitHub come `https://github.com/owner/repo` +- una radice di marketplace locale o un percorso `marketplace.json` +- una forma abbreviata di repo GitHub come `owner/repo` +- un URL di repo GitHub come `https://github.com/owner/repo` - un URL git -Per marketplace remoti caricati da GitHub o git, le voci Plugin devono restare -all'interno del repo marketplace clonato. OpenClaw accetta sorgenti di percorso relative da -quel repo e rifiuta sorgenti Plugin HTTP(S), a percorso assoluto, git, GitHub e altre sorgenti non-path dai manifest remoti. +Per i marketplace remoti caricati da GitHub o git, le voci plugin devono restare all'interno del repo marketplace clonato. OpenClaw accetta sorgenti con percorso relativo da quel repo e rifiuta sorgenti plugin HTTP(S), con percorso assoluto, git, GitHub e altre sorgenti non basate su percorso provenienti da manifest remoti. -Per percorsi locali e archivi, OpenClaw rileva automaticamente: +Per i percorsi locali e gli archivi, OpenClaw rileva automaticamente: - Plugin OpenClaw nativi (`openclaw.plugin.json`) - bundle compatibili con Codex (`.codex-plugin/plugin.json`) -- bundle compatibili con Claude (`.claude-plugin/plugin.json` o il layout componenti - predefinito di Claude) +- bundle compatibili con Claude (`.claude-plugin/plugin.json` o il layout predefinito dei componenti Claude) - bundle compatibili con Cursor (`.cursor-plugin/plugin.json`) -I bundle compatibili vengono installati nella normale root Plugin e partecipano -allo stesso flusso list/info/enable/disable. Oggi, le skill dei bundle, le -command-skills Claude, i valori predefiniti Claude `settings.json`, i valori predefiniti Claude `.lsp.json` / -`lspServers` dichiarati dal manifest, le command-skills Cursor e le directory hook Codex compatibili sono supportati; altre capacità di bundle rilevate vengono -mostrate in diagnostics/info ma non sono ancora collegate all'esecuzione runtime. +I bundle compatibili vengono installati nella normale radice dei plugin e partecipano allo stesso flusso list/info/enable/disable. Attualmente sono supportati bundle Skills, Claude command-skills, valori predefiniti Claude `settings.json`, valori predefiniti Claude `.lsp.json` / `lspServers` dichiarati nel manifest, Cursor command-skills e directory hook Codex compatibili; altre funzionalità di bundle rilevate vengono mostrate nella diagnostica/info ma non sono ancora collegate all'esecuzione runtime. ### Elenco @@ -196,9 +153,15 @@ openclaw plugins list --verbose openclaw plugins list --json ``` -Usa `--enabled` per mostrare solo i Plugin caricati. Usa `--verbose` per passare dalla -vista tabellare a righe di dettaglio per Plugin con metadati di sorgente/origine/versione/attivazione. Usa `--json` per un inventario leggibile dalla macchina più -diagnostica del registro. +Usa `--enabled` per mostrare solo i plugin caricati. Usa `--verbose` per passare dalla vista tabella a righe di dettaglio per plugin con metadati di sorgente/origine/versione/attivazione. Usa `--json` per un inventario leggibile dalle macchine con diagnostica del registro. + +`plugins list` esegue il rilevamento dall'ambiente CLI e dalla configurazione correnti. È utile per verificare se un plugin è abilitato/caricabile, ma non è una sonda runtime live di un processo Gateway già in esecuzione. Dopo aver modificato il codice del plugin, l'abilitazione, la policy degli hook o `plugins.load.paths`, riavvia il Gateway che serve il canale prima di aspettarti l'esecuzione del nuovo codice `register(api)` o degli hook. Per i deployment remoti/in container, verifica di riavviare il vero processo figlio `openclaw gateway run`, non solo un processo wrapper. + +Per il debug runtime degli hook: + +- `openclaw plugins inspect --json` mostra gli hook registrati e la diagnostica da un passaggio di ispezione con modulo caricato. +- `openclaw gateway status --deep --require-rpc` conferma il Gateway raggiungibile, gli indizi sul servizio/processo, il percorso di configurazione e lo stato RPC. +- Gli hook di conversazione non inclusi (`llm_input`, `llm_output`, `agent_end`) richiedono `plugins.entries..hooks.allowConversationAccess=true`. Usa `--link` per evitare di copiare una directory locale (aggiunge a `plugins.load.paths`): @@ -206,11 +169,9 @@ Usa `--link` per evitare di copiare una directory locale (aggiunge a `plugins.lo openclaw plugins install -l ./my-plugin ``` -`--force` non è supportato con `--link` perché le installazioni collegate riusano il -percorso sorgente invece di copiare sopra una destinazione di installazione gestita. +`--force` non è supportato con `--link` perché le installazioni collegate riutilizzano il percorso sorgente invece di copiare sopra una destinazione di installazione gestita. -Usa `--pin` nelle installazioni npm per salvare la specifica esatta risolta (`name@version`) in -`plugins.installs` mantenendo il comportamento predefinito non fissato. +Usa `--pin` nelle installazioni npm per salvare in `plugins.installs` la specifica esatta risolta (`name@version`), mantenendo comunque il comportamento predefinito non bloccato. ### Disinstallazione @@ -220,15 +181,11 @@ openclaw plugins uninstall --dry-run openclaw plugins uninstall --keep-files ``` -`uninstall` rimuove i record Plugin da `plugins.entries`, `plugins.installs`, -dalla allowlist dei Plugin e dalle voci collegate `plugins.load.paths` quando applicabile. -Per i Plugin Active Memory, lo slot di memoria viene reimpostato su `memory-core`. +`uninstall` rimuove i record del plugin da `plugins.entries`, `plugins.installs`, dalla allowlist dei plugin e dalle voci collegate di `plugins.load.paths` quando applicabile. Per i plugin Active Memory, lo slot di memoria viene reimpostato a `memory-core`. -Per impostazione predefinita, la disinstallazione rimuove anche la directory di installazione del Plugin sotto la -root Plugin della state-dir attiva. Usa -`--keep-files` per mantenere i file su disco. +Per impostazione predefinita, uninstall rimuove anche la directory di installazione del plugin sotto la radice plugin della state-dir attiva. Usa `--keep-files` per mantenere i file su disco. -`--keep-config` è supportato come alias deprecato per `--keep-files`. +`--keep-config` è supportato come alias deprecato di `--keep-files`. ### Aggiornamento @@ -242,58 +199,39 @@ openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-ins Gli aggiornamenti si applicano alle installazioni tracciate in `plugins.installs` e alle installazioni tracciate dei pacchetti hook in `hooks.internal.installs`. -Quando passi un id Plugin, OpenClaw riusa la specifica di installazione registrata per quel -Plugin. Questo significa che dist-tag precedentemente memorizzati come `@beta` e versioni esatte fissate continuano a essere usati nelle esecuzioni successive di `update `. +Quando passi un id plugin, OpenClaw riutilizza la specifica di installazione registrata per quel plugin. Questo significa che i dist-tag salvati in precedenza come `@beta` e le versioni esatte bloccate continuano a essere usati nelle esecuzioni successive di `update `. -Per le installazioni npm, puoi anche passare una specifica esplicita del package npm con un dist-tag -o una versione esatta. OpenClaw risolve quel nome package riportandolo al record Plugin tracciato, aggiorna quel Plugin installato e registra la nuova specifica npm per futuri -aggiornamenti basati sull'id. +Per le installazioni npm, puoi anche passare una specifica esplicita del pacchetto npm con un dist-tag o una versione esatta. OpenClaw risolve quel nome pacchetto tornando al record del plugin tracciato, aggiorna il plugin installato e registra la nuova specifica npm per i futuri aggiornamenti basati su id. -Passare il nome del package npm senza versione o tag lo risolve comunque tornando al -record Plugin tracciato. Usalo quando un Plugin era fissato a una versione esatta e -vuoi riportarlo alla linea di rilascio predefinita del registry. +Passare il nome del pacchetto npm senza versione o tag risolve comunque il record del plugin tracciato. Usalo quando un plugin era bloccato a una versione esatta e vuoi riportarlo alla linea di rilascio predefinita del registry. -Prima di un aggiornamento npm live, OpenClaw controlla la versione del package installato rispetto ai metadati del registry npm. Se la versione installata e l'identità dell'artefatto registrato -corrispondono già alla destinazione risolta, l'aggiornamento viene saltato senza -scaricare, reinstallare o riscrivere `openclaw.json`. +Prima di un aggiornamento npm live, OpenClaw controlla la versione del pacchetto installato rispetto ai metadati del registry npm. Se la versione installata e l'identità dell'artefatto registrato corrispondono già alla destinazione risolta, l'aggiornamento viene saltato senza scaricare, reinstallare o riscrivere `openclaw.json`. -Quando esiste un hash di integrità memorizzato e l'hash dell'artefatto recuperato cambia, -OpenClaw lo tratta come drift dell'artefatto npm. Il comando interattivo -`openclaw plugins update` stampa gli hash atteso ed effettivo e chiede -conferma prima di procedere. Gli helper di aggiornamento non interattivi falliscono in modalità fail-closed -a meno che il chiamante non fornisca una policy di continuazione esplicita. +Quando esiste un hash di integrità memorizzato e l'hash dell'artefatto recuperato cambia, OpenClaw lo tratta come deriva dell'artefatto npm. Il comando interattivo `openclaw plugins update` stampa gli hash previsti ed effettivi e chiede conferma prima di procedere. Gli helper di aggiornamento non interattivi falliscono in modalità chiusa, a meno che il chiamante non fornisca una policy esplicita di continuazione. -`--dangerously-force-unsafe-install` è disponibile anche su `plugins update` come -override break-glass per falsi positivi della scansione integrata di codice pericoloso durante -gli aggiornamenti dei Plugin. Non aggira comunque i blocchi di policy `before_install` del Plugin -o il blocco per fallimento della scansione, e si applica solo agli aggiornamenti dei Plugin, non agli aggiornamenti dei pacchetti hook. +`--dangerously-force-unsafe-install` è disponibile anche in `plugins update` come override di emergenza per falsi positivi della scansione integrata di codice pericoloso durante gli aggiornamenti dei plugin. Continua comunque a non aggirare i blocchi di policy `before_install` del plugin né il blocco dovuto a fallimenti della scansione, e si applica solo agli aggiornamenti dei plugin, non agli aggiornamenti dei pacchetti hook. -### Inspect +### Ispezione ```bash openclaw plugins inspect openclaw plugins inspect --json ``` -Introspezione approfondita per un singolo Plugin. Mostra identità, stato di caricamento, sorgente, -capacità registrate, hook, strumenti, comandi, servizi, metodi Gateway, -route HTTP, flag di policy, diagnostica, metadati di installazione, capacità del bundle -ed eventuale supporto MCP o server LSP rilevato. +Introspezione approfondita per un singolo plugin. Mostra identità, stato di caricamento, origine, capacità registrate, hook, strumenti, comandi, servizi, metodi gateway, route HTTP, flag di policy, diagnostica, metadati di installazione, capacità del bundle ed eventuale supporto MCP o server LSP rilevato. -Ogni Plugin è classificato in base a ciò che registra effettivamente a runtime: +Ogni plugin è classificato in base a ciò che registra effettivamente in fase di esecuzione: -- **plain-capability** — un tipo di capacità (ad esempio un Plugin solo provider) +- **plain-capability** — un tipo di capacità (ad esempio un plugin solo provider) - **hybrid-capability** — più tipi di capacità (ad esempio testo + voce + immagini) - **hook-only** — solo hook, nessuna capacità o superficie - **non-capability** — strumenti/comandi/servizi ma nessuna capacità -Vedi [Forme dei Plugin](/it/plugins/architecture#plugin-shapes) per maggiori informazioni sul modello di capacità. +Vedi [Forme dei Plugin](/it/plugins/architecture#plugin-shapes) per ulteriori informazioni sul modello di capacità. -Il flag `--json` produce un report leggibile dalla macchina adatto per scripting e -audit. +Il flag `--json` produce un report leggibile dalle macchine adatto per scripting e auditing. -`inspect --all` mostra una tabella dell'intera flotta con colonne per forma, tipi di capacità, -avvisi di compatibilità, capacità del bundle e riepilogo hook. +`inspect --all` visualizza una tabella dell'intero parco con colonne per forma, tipi di capacità, avvisi di compatibilità, capacità del bundle e riepilogo degli hook. `info` è un alias di `inspect`. @@ -303,13 +241,9 @@ avvisi di compatibilità, capacità del bundle e riepilogo hook. openclaw plugins doctor ``` -`doctor` riporta errori di caricamento dei Plugin, diagnostica del manifest/rilevamento e -avvisi di compatibilità. Quando tutto è pulito stampa `No plugin issues -detected.` +`doctor` segnala errori di caricamento dei plugin, diagnostica di manifest/rilevamento e avvisi di compatibilità. Quando tutto è pulito, stampa `No plugin issues detected.` -Per errori di forma del modulo come esportazioni `register`/`activate` mancanti, riesegui -con `OPENCLAW_PLUGIN_LOAD_DEBUG=1` per includere un riepilogo compatto della forma delle esportazioni -nell'output diagnostico. +Per errori di forma del modulo come esportazioni `register`/`activate` mancanti, riesegui con `OPENCLAW_PLUGIN_LOAD_DEBUG=1` per includere un riepilogo compatto della forma delle esportazioni nell'output diagnostico. ### Marketplace @@ -318,10 +252,7 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -Marketplace list accetta un percorso marketplace locale, un percorso `marketplace.json`, una -forma abbreviata GitHub come `owner/repo`, un URL repo GitHub oppure un URL git. `--json` -stampa l'etichetta della sorgente risolta più il manifest marketplace analizzato e le -voci Plugin. +L'elenco del marketplace accetta un percorso di marketplace locale, un percorso `marketplace.json`, una forma abbreviata GitHub come `owner/repo`, un URL di repository GitHub o un URL git. `--json` stampa l'etichetta della sorgente risolta insieme al manifest del marketplace analizzato e alle voci del plugin. ## Correlati diff --git a/docs/it/concepts/model-providers.md b/docs/it/concepts/model-providers.md index a25033e60..80b14fcc4 100644 --- a/docs/it/concepts/model-providers.md +++ b/docs/it/concepts/model-providers.md @@ -1,92 +1,79 @@ --- read_when: - - Ti serve un riferimento di configurazione dei modelli provider per provider + - Hai bisogno di un riferimento per la configurazione dei modelli, provider per provider - Vuoi configurazioni di esempio o comandi di onboarding CLI per i provider di modelli -summary: Panoramica dei provider di modelli con configurazioni di esempio + flussi CLI -title: Provider di modelli +summary: Panoramica del provider di modelli con configurazioni di esempio + flussi CLI +title: provider di modelli x-i18n: - generated_at: "2026-04-24T08:37:08Z" + generated_at: "2026-04-24T15:23:15Z" model: gpt-5.4 provider: openai - source_hash: ac9bf48897446576d8bc339b340295691741a589863bb57b379c17a5519bffd7 + source_hash: 79258cb26fae7926c65b6fe0db938c7b5736a540b33bc24c1fad5ad706ac8204 source_path: concepts/model-providers.md workflow: 15 --- -Questa pagina tratta i **provider LLM/modelli** (non i canali chat come WhatsApp/Telegram). -Per le regole di selezione del modello, vedi [/concepts/models](/it/concepts/models). +Questa pagina copre i **provider LLM/modelli** (non i canali chat come WhatsApp/Telegram). +Per le regole di selezione dei modelli, vedi [/concepts/models](/it/concepts/models). ## Regole rapide -- I riferimenti dei modelli usano `provider/model` (esempio: `opencode/claude-opus-4-6`). +- I riferimenti ai modelli usano `provider/model` (esempio: `opencode/claude-opus-4-6`). - `agents.defaults.models` agisce come allowlist quando è impostato. - Helper CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set `. -- `models.providers.*.models[].contextWindow` è metadato nativo del modello; `contextTokens` è il limite runtime effettivo. -- Regole di fallback, probe di cooldown e persistenza degli override di sessione: [Model failover](/it/concepts/model-failover). -- I percorsi della famiglia OpenAI sono specifici del prefisso: `openai/` usa il provider diretto con API key - OpenAI in PI, `openai-codex/` usa OAuth Codex in PI, - e `openai/` più `agents.defaults.embeddedHarness.runtime: "codex"` usa l'harness nativo app-server Codex. Vedi [OpenAI](/it/providers/openai) - e [Codex harness](/it/plugins/codex-harness). -- L'abilitazione automatica del Plugin segue lo stesso confine: `openai-codex/` appartiene - al Plugin OpenAI, mentre il Plugin Codex è abilitato da - `embeddedHarness.runtime: "codex"` o dai riferimenti legacy `codex/`. -- GPT-5.5 è attualmente disponibile tramite percorsi subscription/OAuth: - `openai-codex/gpt-5.5` in PI oppure `openai/gpt-5.5` con l'harness - app-server Codex. Il percorso diretto con API key per `openai/gpt-5.5` è supportato quando - OpenAI abiliterà GPT-5.5 sulla API pubblica; fino ad allora usa modelli - abilitati per API come `openai/gpt-5.4` per configurazioni `OPENAI_API_KEY`. +- `models.providers.*.models[].contextWindow` sono metadati nativi del modello; `contextTokens` è il limite effettivo di runtime. +- Regole di fallback, probe di cooldown e persistenza degli override di sessione: [Failover dei modelli](/it/concepts/model-failover). +- I percorsi della famiglia OpenAI sono specifici per prefisso: `openai/` usa il provider diretto con chiave API OpenAI in PI, `openai-codex/` usa OAuth Codex in PI, e `openai/` più `agents.defaults.embeddedHarness.runtime: "codex"` usa l'harness nativo app-server Codex. Vedi [OpenAI](/it/providers/openai) e [Harness Codex](/it/plugins/codex-harness). +- L'abilitazione automatica del Plugin segue lo stesso confine: `openai-codex/` appartiene al Plugin OpenAI, mentre il Plugin Codex viene abilitato da `embeddedHarness.runtime: "codex"` o dai riferimenti legacy `codex/`. +- GPT-5.5 è attualmente disponibile tramite percorsi subscription/OAuth: `openai-codex/gpt-5.5` in PI oppure `openai/gpt-5.5` con l'harness app-server Codex. Il percorso diretto con chiave API per `openai/gpt-5.5` è supportato non appena OpenAI abilita GPT-5.5 sulla API pubblica; fino ad allora usa modelli abilitati API come `openai/gpt-5.4` per le configurazioni `OPENAI_API_KEY`. ## Comportamento del provider gestito dal Plugin -La maggior parte della logica specifica del provider si trova nei Plugin provider (`registerProvider(...)`), mentre OpenClaw mantiene il ciclo di inferenza generico. I Plugin gestiscono onboarding, cataloghi dei modelli, mappatura auth env-var, normalizzazione di trasporto/configurazione, pulizia dello schema degli strumenti, classificazione del failover, refresh OAuth, report di utilizzo, profili di thinking/reasoning e altro. +La maggior parte della logica specifica del provider vive nei plugin provider (`registerProvider(...)`), mentre OpenClaw mantiene il loop di inferenza generico. I plugin gestiscono onboarding, cataloghi di modelli, mapping delle variabili d'ambiente di autenticazione, normalizzazione di trasporto/configurazione, pulizia dello schema degli strumenti, classificazione del failover, refresh OAuth, report dell'uso, profili di thinking/reasoning e altro. -L'elenco completo degli hook SDK provider e degli esempi di Plugin integrati si trova in [Provider plugins](/it/plugins/sdk-provider-plugins). Un provider che richiede un esecutore di richieste totalmente personalizzato è una superficie di estensione separata e più profonda. +L'elenco completo degli hook del provider-SDK e degli esempi di plugin inclusi si trova in [Plugin provider](/it/plugins/sdk-provider-plugins). Un provider che richiede un esecutore di richieste completamente personalizzato è una superficie di estensione separata e più profonda. -Le `capabilities` runtime del provider sono metadati condivisi del runner (famiglia del provider, particolarità di trascrizione/tooling, suggerimenti di trasporto/cache). Non sono la stessa cosa del [modello pubblico delle capability](/it/plugins/architecture#public-capability-model), che descrive ciò che un Plugin registra (inferenza testuale, voce, ecc.). +Il `capabilities` di runtime del provider è metadato condiviso del runner (famiglia di provider, particolarità di transcript/tooling, suggerimenti di trasporto/cache). Non è la stessa cosa del [modello di capability pubblico](/it/plugins/architecture#public-capability-model), che descrive cosa registra un Plugin (inferenza di testo, voce, ecc.). -## Rotazione delle API key +## Rotazione delle chiavi API - Supporta la rotazione generica del provider per provider selezionati. - Configura più chiavi tramite: - - `OPENCLAW_LIVE__KEY` (singolo override live, priorità massima) + - `OPENCLAW_LIVE__KEY` (singolo override live, priorità più alta) - `_API_KEYS` (elenco separato da virgole o punto e virgola) - `_API_KEY` (chiave primaria) - `_API_KEY_*` (elenco numerato, ad esempio `_API_KEY_1`) -- Per i provider Google, `GOOGLE_API_KEY` è incluso anche come fallback. +- Per i provider Google, anche `GOOGLE_API_KEY` è incluso come fallback. - L'ordine di selezione delle chiavi preserva la priorità e rimuove i duplicati. -- Le richieste vengono ritentate con la chiave successiva solo su risposte di rate limit (ad - esempio `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many +- Le richieste vengono ritentate con la chiave successiva solo sulle risposte di rate limit (ad esempio `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, - `workers_ai ... quota limit exceeded` o messaggi periodici di limite d'uso). -- I fallimenti non dovuti a rate limit falliscono immediatamente; non viene tentata alcuna rotazione delle chiavi. -- Quando tutte le chiavi candidate falliscono, l'errore finale viene restituito dall'ultimo tentativo. + `workers_ai ... quota limit exceeded`, o messaggi periodici di limite d'uso). +- Gli errori non dovuti a rate limit falliscono immediatamente; non viene tentata alcuna rotazione della chiave. +- Quando tutte le chiavi candidate falliscono, viene restituito l'errore finale dell'ultimo tentativo. ## Provider integrati (catalogo pi-ai) -OpenClaw include il catalogo pi‑ai. Questi provider non richiedono alcuna -configurazione `models.providers`; basta impostare l'autenticazione e scegliere un modello. +OpenClaw include il catalogo pi‑ai. Questi provider non richiedono alcuna configurazione `models.providers`; basta impostare l'autenticazione e scegliere un modello. ### OpenAI - Provider: `openai` -- Auth: `OPENAI_API_KEY` -- Rotazione facoltativa: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, più `OPENCLAW_LIVE_OPENAI_KEY` (override singolo) +- Autenticazione: `OPENAI_API_KEY` +- Rotazione facoltativa: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, più `OPENCLAW_LIVE_OPENAI_KEY` (singolo override) - Modelli di esempio: `openai/gpt-5.4`, `openai/gpt-5.4-mini` -- Il supporto diretto API per GPT-5.5 qui è pronto per il futuro una volta che OpenAI esporrà GPT-5.5 sulla API +- Il supporto diretto API per GPT-5.5 è pronto per il futuro qui, non appena OpenAI esporrà GPT-5.5 sulla API - CLI: `openclaw onboard --auth-choice openai-api-key` - Il trasporto predefinito è `auto` (prima WebSocket, fallback SSE) -- Sovrascrivi per modello tramite `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` o `"auto"`) -- Il warm-up WebSocket OpenAI Responses è abilitato per impostazione predefinita tramite `params.openaiWsWarmup` (`true`/`false`) +- Override per modello tramite `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` o `"auto"`) +- Il warm-up WebSocket di OpenAI Responses è abilitato per impostazione predefinita tramite `params.openaiWsWarmup` (`true`/`false`) - L'elaborazione prioritaria OpenAI può essere abilitata tramite `agents.defaults.models["openai/"].params.serviceTier` - `/fast` e `params.fastMode` mappano le richieste dirette `openai/*` Responses a `service_tier=priority` su `api.openai.com` -- Usa `params.serviceTier` quando vuoi un livello esplicito invece del toggle condiviso `/fast` -- Gli header nascosti di attribuzione OpenClaw (`originator`, `version`, - `User-Agent`) si applicano solo sul traffico OpenAI nativo verso `api.openai.com`, non - su proxy generici compatibili OpenAI -- I percorsi OpenAI nativi mantengono anche `store` di Responses, suggerimenti di prompt-cache e - modellazione del payload compatibile con il reasoning OpenAI; i percorsi proxy no +- Usa `params.serviceTier` quando vuoi un tier esplicito invece del toggle condiviso `/fast` +- Gli header di attribuzione OpenClaw nascosti (`originator`, `version`, + `User-Agent`) si applicano solo al traffico OpenAI nativo verso `api.openai.com`, non ai proxy generici compatibili con OpenAI +- I percorsi OpenAI nativi mantengono anche `store` di Responses, i suggerimenti di prompt-cache e la modellazione del payload compatibile con il reasoning OpenAI; i percorsi proxy no - `openai/gpt-5.3-codex-spark` è intenzionalmente soppresso in OpenClaw perché le richieste API OpenAI live lo rifiutano e l'attuale catalogo Codex non lo espone ```json5 @@ -98,13 +85,13 @@ configurazione `models.providers`; basta impostare l'autenticazione e scegliere ### Anthropic - Provider: `anthropic` -- Auth: `ANTHROPIC_API_KEY` -- Rotazione facoltativa: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, più `OPENCLAW_LIVE_ANTHROPIC_KEY` (override singolo) +- Autenticazione: `ANTHROPIC_API_KEY` +- Rotazione facoltativa: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, più `OPENCLAW_LIVE_ANTHROPIC_KEY` (singolo override) - Modello di esempio: `anthropic/claude-opus-4-6` - CLI: `openclaw onboard --auth-choice apiKey` -- Le richieste Anthropic pubbliche dirette supportano il toggle condiviso `/fast` e `params.fastMode`, incluso il traffico autenticato con API key e OAuth inviato a `api.anthropic.com`; OpenClaw lo mappa a Anthropic `service_tier` (`auto` vs `standard_only`) -- Nota Anthropic: il personale Anthropic ci ha detto che l'uso stile Claude CLI di OpenClaw è di nuovo consentito, quindi OpenClaw considera il riutilizzo di Claude CLI e l'uso di `claude -p` come autorizzati per questa integrazione, a meno che Anthropic non pubblichi una nuova policy. -- Il setup-token Anthropic resta disponibile come percorso token OpenClaw supportato, ma OpenClaw ora preferisce il riutilizzo di Claude CLI e `claude -p` quando disponibili. +- Le richieste Anthropic pubbliche dirette supportano il toggle condiviso `/fast` e `params.fastMode`, incluso il traffico autenticato con chiave API e OAuth inviato a `api.anthropic.com`; OpenClaw lo mappa a Anthropic `service_tier` (`auto` vs `standard_only`) +- Nota Anthropic: il personale 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. +- Il setup-token Anthropic resta disponibile come percorso token supportato in OpenClaw, ma ora OpenClaw preferisce il riuso di Claude CLI e `claude -p` quando disponibili. ```json5 { @@ -112,26 +99,24 @@ configurazione `models.providers`; basta impostare l'autenticazione e scegliere } ``` -### OpenAI Codex OAuth +### OAuth OpenAI Codex - Provider: `openai-codex` -- Auth: OAuth (ChatGPT) +- Autenticazione: OAuth (ChatGPT) - Riferimento modello PI: `openai-codex/gpt-5.5` -- Riferimento harness nativo app-server Codex: `openai/gpt-5.5` con `agents.defaults.embeddedHarness.runtime: "codex"` +- Riferimento harness app-server Codex nativo: `openai/gpt-5.5` con `agents.defaults.embeddedHarness.runtime: "codex"` - Riferimenti modello legacy: `codex/gpt-*` -- Confine del Plugin: `openai-codex/*` carica il Plugin OpenAI; il Plugin - app-server Codex nativo viene selezionato solo dal runtime harness Codex o dai riferimenti - legacy `codex/*`. +- Confine del Plugin: `openai-codex/*` carica il Plugin OpenAI; il Plugin app-server Codex nativo viene selezionato solo dal runtime harness Codex o dai riferimenti legacy `codex/*`. - CLI: `openclaw onboard --auth-choice openai-codex` o `openclaw models auth login --provider openai-codex` - Il trasporto predefinito è `auto` (prima WebSocket, fallback SSE) -- Sovrascrivi per modello PI tramite `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` o `"auto"`) +- Override per modello PI tramite `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` o `"auto"`) - `params.serviceTier` viene inoltrato anche sulle richieste native Codex Responses (`chatgpt.com/backend-api`) -- Gli header nascosti di attribuzione OpenClaw (`originator`, `version`, - `User-Agent`) vengono allegati solo sul traffico Codex nativo verso - `chatgpt.com/backend-api`, non su proxy generici compatibili OpenAI +- Gli header di attribuzione OpenClaw nascosti (`originator`, `version`, + `User-Agent`) vengono allegati solo al traffico Codex nativo verso + `chatgpt.com/backend-api`, non ai proxy generici compatibili con OpenAI - Condivide lo stesso toggle `/fast` e la stessa configurazione `params.fastMode` di `openai/*` diretto; OpenClaw lo mappa a `service_tier=priority` -- `openai-codex/gpt-5.5` mantiene il valore nativo `contextWindow = 1000000` e un valore predefinito runtime `contextTokens = 272000`; sovrascrivi il limite runtime con `models.providers.openai-codex.models[].contextTokens` -- Nota sulla policy: OpenAI Codex OAuth è esplicitamente supportato per strumenti/flussi di lavoro esterni come OpenClaw. +- `openai-codex/gpt-5.5` mantiene il valore nativo `contextWindow = 1000000` e un valore predefinito di runtime `contextTokens = 272000`; esegui l'override del limite di runtime con `models.providers.openai-codex.models[].contextTokens` +- Nota sulla policy: OAuth OpenAI Codex è esplicitamente supportato per strumenti/workflow esterni come OpenClaw. - L'accesso attuale a GPT-5.5 usa questo percorso OAuth/subscription finché OpenAI non abilita GPT-5.5 sulla API pubblica. ```json5 @@ -152,15 +137,15 @@ configurazione `models.providers`; basta impostare l'autenticazione e scegliere } ``` -### Altre opzioni ospitate in stile subscription +### Altre opzioni hosted in stile subscription -- [Qwen Cloud](/it/providers/qwen): superficie provider Qwen Cloud più mappatura degli endpoint Alibaba DashScope e Coding Plan -- [MiniMax](/it/providers/minimax): accesso MiniMax Coding Plan tramite OAuth o API key +- [Qwen Cloud](/it/providers/qwen): superficie provider Qwen Cloud più mapping degli endpoint Alibaba DashScope e Coding Plan +- [MiniMax](/it/providers/minimax): accesso OAuth o con chiave API a MiniMax Coding Plan - [GLM Models](/it/providers/glm): endpoint Z.AI Coding Plan o API generali ### OpenCode -- Auth: `OPENCODE_API_KEY` (o `OPENCODE_ZEN_API_KEY`) +- Autenticazione: `OPENCODE_API_KEY` (o `OPENCODE_ZEN_API_KEY`) - Provider runtime Zen: `opencode` - Provider runtime Go: `opencode-go` - Modelli di esempio: `opencode/claude-opus-4-6`, `opencode-go/kimi-k2.5` @@ -172,40 +157,38 @@ configurazione `models.providers`; basta impostare l'autenticazione e scegliere } ``` -### Google Gemini (API key) +### Google Gemini (chiave API) - Provider: `google` -- Auth: `GEMINI_API_KEY` -- Rotazione facoltativa: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, fallback `GOOGLE_API_KEY` e `OPENCLAW_LIVE_GEMINI_KEY` (override singolo) +- Autenticazione: `GEMINI_API_KEY` +- Rotazione facoltativa: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, fallback `GOOGLE_API_KEY` e `OPENCLAW_LIVE_GEMINI_KEY` (singolo override) - Modelli di esempio: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview` - Compatibilità: la configurazione legacy OpenClaw che usa `google/gemini-3.1-flash-preview` viene normalizzata in `google/gemini-3-flash-preview` - CLI: `openclaw onboard --auth-choice gemini-api-key` - Le esecuzioni Gemini dirette accettano anche `agents.defaults.models["google/"].params.cachedContent` (o il legacy `cached_content`) per inoltrare un handle nativo del provider - `cachedContents/...`; i cache hit Gemini emergono come `cacheRead` OpenClaw + `cachedContents/...`; i cache hit Gemini vengono esposti come OpenClaw `cacheRead` ### Google Vertex e Gemini CLI - Provider: `google-vertex`, `google-gemini-cli` -- Auth: Vertex usa gcloud ADC; Gemini CLI usa il proprio flusso OAuth -- Attenzione: l'OAuth Gemini CLI in OpenClaw è un'integrazione non ufficiale. Alcuni utenti hanno segnalato restrizioni sull'account Google dopo aver usato client di terze parti. Rivedi i termini di Google e usa un account non critico se scegli di procedere. -- L'OAuth Gemini CLI è incluso come parte del Plugin `google` integrato. +- Autenticazione: Vertex usa gcloud ADC; Gemini CLI usa il proprio flusso OAuth +- Attenzione: OAuth Gemini CLI in OpenClaw è un'integrazione non ufficiale. Alcuni utenti hanno segnalato restrizioni dell'account Google dopo l'uso di client di terze parti. Verifica i termini di Google e usa un account non critico se scegli di procedere. +- OAuth Gemini CLI è distribuito come parte del Plugin `google` incluso. - Installa prima Gemini CLI: - `brew install gemini-cli` - oppure `npm install -g @google/gemini-cli` - Abilita: `openclaw plugins enable google` - - Accesso: `openclaw models auth login --provider google-gemini-cli --set-default` + - Login: `openclaw models auth login --provider google-gemini-cli --set-default` - Modello predefinito: `google-gemini-cli/gemini-3-flash-preview` - - Nota: **non** incolli un client id o un secret in `openclaw.json`. Il flusso di accesso CLI memorizza - i token nei profili di autenticazione sull'host gateway. - - Se le richieste falliscono dopo l'accesso, imposta `GOOGLE_CLOUD_PROJECT` o `GOOGLE_CLOUD_PROJECT_ID` sull'host gateway. - - Le risposte JSON Gemini CLI vengono analizzate da `response`; l'utilizzo usa come fallback - `stats`, con `stats.cached` normalizzato in `cacheRead` OpenClaw. + - Nota: **non** incolli un client id o secret in `openclaw.json`. Il flusso di login CLI archivia i token nei profili di autenticazione sull'host Gateway. + - Se le richieste falliscono dopo il login, imposta `GOOGLE_CLOUD_PROJECT` o `GOOGLE_CLOUD_PROJECT_ID` sull'host Gateway. + - Le risposte JSON di Gemini CLI vengono analizzate da `response`; l'uso ricade su `stats`, con `stats.cached` normalizzato in OpenClaw `cacheRead`. ### Z.AI (GLM) - Provider: `zai` -- Auth: `ZAI_API_KEY` +- Autenticazione: `ZAI_API_KEY` - Modello di esempio: `zai/glm-5.1` - CLI: `openclaw onboard --auth-choice zai-api-key` - Alias: `z.ai/*` e `z-ai/*` vengono normalizzati in `zai/*` @@ -214,7 +197,7 @@ configurazione `models.providers`; basta impostare l'autenticazione e scegliere ### Vercel AI Gateway - Provider: `vercel-ai-gateway` -- Auth: `AI_GATEWAY_API_KEY` +- Autenticazione: `AI_GATEWAY_API_KEY` - Modelli di esempio: `vercel-ai-gateway/anthropic/claude-opus-4.6`, `vercel-ai-gateway/moonshotai/kimi-k2.6` - CLI: `openclaw onboard --auth-choice ai-gateway-api-key` @@ -222,70 +205,64 @@ configurazione `models.providers`; basta impostare l'autenticazione e scegliere ### Kilo Gateway - Provider: `kilocode` -- Auth: `KILOCODE_API_KEY` +- Autenticazione: `KILOCODE_API_KEY` - Modello di esempio: `kilocode/kilo/auto` - CLI: `openclaw onboard --auth-choice kilocode-api-key` -- URL base: `https://api.kilo.ai/api/gateway/` -- Il catalogo statico di fallback include `kilocode/kilo/auto`; il rilevamento live di - `https://api.kilo.ai/api/gateway/models` può espandere ulteriormente il catalogo - runtime. -- L'instradamento upstream esatto dietro `kilocode/kilo/auto` è gestito da Kilo Gateway, - non è codificato rigidamente in OpenClaw. +- URL di base: `https://api.kilo.ai/api/gateway/` +- Il catalogo statico di fallback include `kilocode/kilo/auto`; il rilevamento live di `https://api.kilo.ai/api/gateway/models` può espandere ulteriormente il catalogo di runtime. +- Il routing upstream esatto dietro `kilocode/kilo/auto` è gestito da Kilo Gateway, non codificato rigidamente in OpenClaw. Vedi [/providers/kilocode](/it/providers/kilocode) per i dettagli di configurazione. -### Altri Plugin provider integrati +### Altri plugin provider inclusi -| Provider | Id | Auth env | Modello di esempio | +| Provider | Id | Variabile env di autenticazione | Modello di esempio | | ----------------------- | -------------------------------- | ------------------------------------------------------------ | ----------------------------------------------- | -| BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` | -| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` | -| Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — | -| GitHub Copilot | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | — | -| Groq | `groq` | `GROQ_API_KEY` | — | -| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` or `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` | -| Kilo Gateway | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` | -| Kimi Coding | `kimi` | `KIMI_API_KEY` or `KIMICODE_API_KEY` | `kimi/kimi-code` | -| MiniMax | `minimax` / `minimax-portal` | `MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN` | `minimax/MiniMax-M2.7` | -| Mistral | `mistral` | `MISTRAL_API_KEY` | `mistral/mistral-large-latest` | -| Moonshot | `moonshot` | `MOONSHOT_API_KEY` | `moonshot/kimi-k2.6` | -| NVIDIA | `nvidia` | `NVIDIA_API_KEY` | `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` | -| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | `openrouter/auto` | -| Qianfan | `qianfan` | `QIANFAN_API_KEY` | `qianfan/deepseek-v3.2` | -| Qwen Cloud | `qwen` | `QWEN_API_KEY` / `MODELSTUDIO_API_KEY` / `DASHSCOPE_API_KEY` | `qwen/qwen3.5-plus` | -| StepFun | `stepfun` / `stepfun-plan` | `STEPFUN_API_KEY` | `stepfun/step-3.5-flash` | -| Together | `together` | `TOGETHER_API_KEY` | `together/moonshotai/Kimi-K2.5` | -| Venice | `venice` | `VENICE_API_KEY` | — | -| Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` | -| Volcano Engine (Doubao) | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` | -| xAI | `xai` | `XAI_API_KEY` | `xai/grok-4` | -| Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` | +| BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` | +| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` | +| Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — | +| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek/deepseek-v4-flash` | +| GitHub Copilot | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | — | +| Groq | `groq` | `GROQ_API_KEY` | — | +| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` or `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` | +| Kilo Gateway | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` | +| Kimi Coding | `kimi` | `KIMI_API_KEY` or `KIMICODE_API_KEY` | `kimi/kimi-code` | +| MiniMax | `minimax` / `minimax-portal` | `MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN` | `minimax/MiniMax-M2.7` | +| Mistral | `mistral` | `MISTRAL_API_KEY` | `mistral/mistral-large-latest` | +| Moonshot | `moonshot` | `MOONSHOT_API_KEY` | `moonshot/kimi-k2.6` | +| NVIDIA | `nvidia` | `NVIDIA_API_KEY` | `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` | +| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | `openrouter/auto` | +| Qianfan | `qianfan` | `QIANFAN_API_KEY` | `qianfan/deepseek-v3.2` | +| Qwen Cloud | `qwen` | `QWEN_API_KEY` / `MODELSTUDIO_API_KEY` / `DASHSCOPE_API_KEY` | `qwen/qwen3.5-plus` | +| StepFun | `stepfun` / `stepfun-plan` | `STEPFUN_API_KEY` | `stepfun/step-3.5-flash` | +| Together | `together` | `TOGETHER_API_KEY` | `together/moonshotai/Kimi-K2.5` | +| Venice | `venice` | `VENICE_API_KEY` | — | +| Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` | +| Volcano Engine (Doubao) | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` | +| xAI | `xai` | `XAI_API_KEY` | `xai/grok-4` | +| Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` | -Aspetti utili da conoscere: +Particolarità da conoscere: -- **OpenRouter** applica i suoi header di attribuzione dell'app e i marker Anthropic `cache_control` solo sui percorsi `openrouter.ai` verificati. Come percorso compatibile OpenAI in stile proxy, salta la modellazione riservata a OpenAI nativo (`serviceTier`, `store` di Responses, suggerimenti di prompt-cache, compatibilità di reasoning OpenAI). I riferimenti basati su Gemini mantengono solo la sanitizzazione della thought-signature di Gemini via proxy. -- **Kilo Gateway** per i riferimenti basati su Gemini segue lo stesso percorso di sanitizzazione proxy-Gemini; `kilocode/kilo/auto` e altri riferimenti proxy senza supporto al reasoning saltano l'iniezione di reasoning proxy. -- **MiniMax** nell'onboarding con API key scrive definizioni esplicite del modello M2.7 con `input: ["text", "image"]`; il catalogo integrato mantiene i riferimenti chat solo testo finché quella configurazione non viene materializzata. -- **xAI** usa il percorso xAI Responses. `/fast` oppure `params.fastMode: true` riscrivono `grok-3`, `grok-3-mini`, `grok-4` e `grok-4-0709` nelle rispettive varianti `*-fast`. `tool_stream` è attivo per impostazione predefinita; disabilitalo con `agents.defaults.models["xai/"].params.tool_stream=false`. -- **Cerebras** i modelli GLM usano `zai-glm-4.7` / `zai-glm-4.6`; l'URL base compatibile OpenAI è `https://api.cerebras.ai/v1`. +- **OpenRouter** applica i suoi header di attribuzione dell'app e i marker Anthropic `cache_control` solo sui percorsi `openrouter.ai` verificati. Come percorso in stile proxy compatibile con OpenAI, salta la modellazione riservata a OpenAI nativo (`serviceTier`, `store` di Responses, suggerimenti di prompt-cache, compatibilità reasoning OpenAI). I riferimenti basati su Gemini mantengono solo la sanificazione della thought signature di Gemini via proxy. +- **Kilo Gateway** per i riferimenti basati su Gemini segue lo stesso percorso di sanificazione Gemini via proxy; `kilocode/kilo/auto` e gli altri riferimenti proxy che non supportano il reasoning saltano l'iniezione del reasoning proxy. +- **MiniMax** l'onboarding con chiave API scrive definizioni esplicite del modello M2.7 con `input: ["text", "image"]`; il catalogo incluso mantiene i riferimenti chat solo testuali finché quella configurazione non viene materializzata. +- **xAI** usa il percorso xAI Responses. `/fast` o `params.fastMode: true` riscrivono `grok-3`, `grok-3-mini`, `grok-4` e `grok-4-0709` nelle rispettive varianti `*-fast`. `tool_stream` è attivo per impostazione predefinita; disattivalo con `agents.defaults.models["xai/"].params.tool_stream=false`. +- **Cerebras** i modelli GLM usano `zai-glm-4.7` / `zai-glm-4.6`; l'URL base compatibile con OpenAI è `https://api.cerebras.ai/v1`. -## Provider tramite `models.providers` (personalizzato/base URL) +## Provider tramite `models.providers` (personalizzato / URL base) -Usa `models.providers` (o `models.json`) per aggiungere provider **personalizzati** o -proxy compatibili OpenAI/Anthropic. +Usa `models.providers` (o `models.json`) per aggiungere provider **personalizzati** o proxy compatibili con OpenAI/Anthropic. -Molti dei Plugin provider integrati sotto pubblicano già un catalogo predefinito. -Usa voci esplicite `models.providers.` solo quando vuoi sovrascrivere -l'URL base predefinito, gli header o l'elenco dei modelli. +Molti dei Plugin provider inclusi di seguito pubblicano già un catalogo predefinito. +Usa voci esplicite `models.providers.` solo quando vuoi sovrascrivere l'URL base predefinito, gli header o l'elenco dei modelli. ### Moonshot AI (Kimi) -Moonshot è incluso come Plugin provider integrato. Usa il provider integrato per -impostazione predefinita, e aggiungi una voce esplicita `models.providers.moonshot` solo quando -devi sovrascrivere l'URL base o i metadati del modello: +Moonshot è distribuito come Plugin provider incluso. Usa il provider integrato come impostazione predefinita e aggiungi una voce esplicita `models.providers.moonshot` solo quando hai bisogno di sovrascrivere l'URL base o i metadati del modello: - Provider: `moonshot` -- Auth: `MOONSHOT_API_KEY` +- Autenticazione: `MOONSHOT_API_KEY` - Modello di esempio: `moonshot/kimi-k2.6` - CLI: `openclaw onboard --auth-choice moonshot-api-key` o `openclaw onboard --auth-choice moonshot-api-key-cn` @@ -322,10 +299,10 @@ ID modello Kimi K2: ### Kimi Coding -Kimi Coding usa l'endpoint compatibile Anthropic di Moonshot AI: +Kimi Coding usa l'endpoint compatibile con Anthropic di Moonshot AI: - Provider: `kimi` -- Auth: `KIMI_API_KEY` +- Autenticazione: `KIMI_API_KEY` - Modello di esempio: `kimi/kimi-code` ```json5 @@ -337,14 +314,14 @@ Kimi Coding usa l'endpoint compatibile Anthropic di Moonshot AI: } ``` -Il riferimento modello di compatibilità legacy `kimi/k2p5` continua a essere accettato. +Il legacy `kimi/k2p5` continua a essere accettato come ID modello di compatibilità. ### Volcano Engine (Doubao) Volcano Engine (火山引擎) fornisce accesso a Doubao e ad altri modelli in Cina. - Provider: `volcengine` (coding: `volcengine-plan`) -- Auth: `VOLCANO_ENGINE_API_KEY` +- Autenticazione: `VOLCANO_ENGINE_API_KEY` - Modello di esempio: `volcengine-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice volcengine-api-key` @@ -356,13 +333,9 @@ Volcano Engine (火山引擎) fornisce accesso a Doubao e ad altri modelli in Ci } ``` -L'onboarding usa come predefinita la superficie coding, ma il catalogo generale `volcengine/*` -viene registrato contemporaneamente. +L'onboarding usa per impostazione predefinita la superficie coding, ma allo stesso tempo viene registrato il catalogo generale `volcengine/*`. -Nei selettori di modelli di onboarding/configurazione, la scelta auth Volcengine preferisce sia -le righe `volcengine/*` sia `volcengine-plan/*`. Se quei modelli non sono ancora caricati, -OpenClaw usa come fallback il catalogo non filtrato invece di mostrare un selettore -vuoto limitato al provider. +Nei selettori del modello di onboarding/configurazione, la scelta di autenticazione Volcengine privilegia sia le righe `volcengine/*` sia quelle `volcengine-plan/*`. Se questi modelli non sono ancora caricati, OpenClaw usa come fallback il catalogo non filtrato invece di mostrare un selettore limitato al provider vuoto. Modelli disponibili: @@ -382,10 +355,10 @@ Modelli coding (`volcengine-plan`): ### BytePlus (internazionale) -BytePlus ARK fornisce accesso agli stessi modelli di Volcano Engine per utenti internazionali. +BytePlus ARK fornisce accesso agli stessi modelli di Volcano Engine per gli utenti internazionali. - Provider: `byteplus` (coding: `byteplus-plan`) -- Auth: `BYTEPLUS_API_KEY` +- Autenticazione: `BYTEPLUS_API_KEY` - Modello di esempio: `byteplus-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice byteplus-api-key` @@ -397,13 +370,9 @@ BytePlus ARK fornisce accesso agli stessi modelli di Volcano Engine per utenti i } ``` -L'onboarding usa come predefinita la superficie coding, ma il catalogo generale `byteplus/*` -viene registrato contemporaneamente. +L'onboarding usa per impostazione predefinita la superficie coding, ma allo stesso tempo viene registrato il catalogo generale `byteplus/*`. -Nei selettori di modelli di onboarding/configurazione, la scelta auth BytePlus preferisce sia -le righe `byteplus/*` sia `byteplus-plan/*`. Se quei modelli non sono ancora caricati, -OpenClaw usa come fallback il catalogo non filtrato invece di mostrare un selettore -vuoto limitato al provider. +Nei selettori del modello di onboarding/configurazione, la scelta di autenticazione BytePlus privilegia sia le righe `byteplus/*` sia quelle `byteplus-plan/*`. Se questi modelli non sono ancora caricati, OpenClaw usa come fallback il catalogo non filtrato invece di mostrare un selettore limitato al provider vuoto. Modelli disponibili: @@ -421,10 +390,10 @@ Modelli coding (`byteplus-plan`): ### Synthetic -Synthetic fornisce modelli compatibili Anthropic dietro il provider `synthetic`: +Synthetic fornisce modelli compatibili con Anthropic dietro il provider `synthetic`: - Provider: `synthetic` -- Auth: `SYNTHETIC_API_KEY` +- Autenticazione: `SYNTHETIC_API_KEY` - Modello di esempio: `synthetic/hf:MiniMaxAI/MiniMax-M2.5` - CLI: `openclaw onboard --auth-choice synthetic-api-key` @@ -451,35 +420,33 @@ Synthetic fornisce modelli compatibili Anthropic dietro il provider `synthetic`: MiniMax viene configurato tramite `models.providers` perché usa endpoint personalizzati: -- MiniMax OAuth (globale): `--auth-choice minimax-global-oauth` -- MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth` -- API key MiniMax (globale): `--auth-choice minimax-global-api` -- API key MiniMax (CN): `--auth-choice minimax-cn-api` -- Auth: `MINIMAX_API_KEY` per `minimax`; `MINIMAX_OAUTH_TOKEN` oppure +- OAuth MiniMax (globale): `--auth-choice minimax-global-oauth` +- OAuth MiniMax (CN): `--auth-choice minimax-cn-oauth` +- Chiave API MiniMax (globale): `--auth-choice minimax-global-api` +- Chiave API MiniMax (CN): `--auth-choice minimax-cn-api` +- Autenticazione: `MINIMAX_API_KEY` per `minimax`; `MINIMAX_OAUTH_TOKEN` o `MINIMAX_API_KEY` per `minimax-portal` -Vedi [/providers/minimax](/it/providers/minimax) per dettagli di configurazione, opzioni dei modelli e snippet di configurazione. +Vedi [/providers/minimax](/it/providers/minimax) per i dettagli di configurazione, le opzioni dei modelli e gli snippet di configurazione. -Sul percorso di streaming compatibile Anthropic di MiniMax, OpenClaw disabilita il thinking per -impostazione predefinita a meno che tu non lo imposti esplicitamente, e `/fast on` riscrive -`MiniMax-M2.7` in `MiniMax-M2.7-highspeed`. +Nel percorso di streaming compatibile con Anthropic di MiniMax, OpenClaw disabilita il thinking per impostazione predefinita a meno che tu non lo imposti esplicitamente, e `/fast on` riscrive `MiniMax-M2.7` in `MiniMax-M2.7-highspeed`. Suddivisione delle capability gestita dal Plugin: -- I valori predefiniti per testo/chat restano su `minimax/MiniMax-M2.7` -- La generazione immagini è `minimax/image-01` oppure `minimax-portal/image-01` -- La comprensione delle immagini è `MiniMax-VL-01` gestita dal Plugin su entrambi i percorsi auth MiniMax +- Le impostazioni predefinite di testo/chat restano su `minimax/MiniMax-M2.7` +- La generazione di immagini è `minimax/image-01` o `minimax-portal/image-01` +- La comprensione delle immagini è `MiniMax-VL-01`, gestita dal plugin, su entrambi i percorsi di autenticazione MiniMax - La ricerca web resta sull'id provider `minimax` ### LM Studio -LM Studio è incluso come Plugin provider integrato e usa l'API nativa: +LM Studio è distribuito come Plugin provider incluso che usa la API nativa: - Provider: `lmstudio` -- Auth: `LM_API_TOKEN` +- Autenticazione: `LM_API_TOKEN` - URL base predefinito per l'inferenza: `http://localhost:1234/v1` -Poi imposta un modello (sostituisci con uno degli ID restituiti da `http://localhost:1234/api/v1/models`): +Quindi imposta un modello (sostituisci con uno degli ID restituiti da `http://localhost:1234/api/v1/models`): ```json5 { @@ -489,20 +456,20 @@ Poi imposta un modello (sostituisci con uno degli ID restituiti da `http://local } ``` -OpenClaw usa `/api/v1/models` e `/api/v1/models/load` nativi di LM Studio per rilevamento + caricamento automatico, con `/v1/chat/completions` per l'inferenza per impostazione predefinita. +OpenClaw usa i percorsi nativi di LM Studio `/api/v1/models` e `/api/v1/models/load` per discovery + auto-load, con `/v1/chat/completions` per l'inferenza per impostazione predefinita. Vedi [/providers/lmstudio](/it/providers/lmstudio) per configurazione e risoluzione dei problemi. ### Ollama -Ollama è incluso come Plugin provider integrato e usa l'API nativa di Ollama: +Ollama è distribuito come Plugin provider incluso e usa la API nativa di Ollama: - Provider: `ollama` -- Auth: nessuna richiesta (server locale) +- Autenticazione: nessuna richiesta (server locale) - Modello di esempio: `ollama/llama3.3` - Installazione: [https://ollama.com/download](https://ollama.com/download) ```bash -# Install Ollama, then pull a model: +# Installa Ollama, poi scarica un modello: ollama pull llama3.3 ``` @@ -514,27 +481,23 @@ ollama pull llama3.3 } ``` -Ollama viene rilevato localmente su `http://127.0.0.1:11434` quando attivi -`OLLAMA_API_KEY`, e il Plugin provider integrato aggiunge direttamente Ollama a -`openclaw onboard` e al selettore dei modelli. Vedi [/providers/ollama](/it/providers/ollama) -per onboarding, modalità cloud/locale e configurazione personalizzata. +Ollama viene rilevato localmente su `http://127.0.0.1:11434` quando esegui l'opt-in con `OLLAMA_API_KEY`, e il Plugin provider incluso aggiunge Ollama direttamente a `openclaw onboard` e al selettore dei modelli. Vedi [/providers/ollama](/it/providers/ollama) per onboarding, modalità cloud/locale e configurazione personalizzata. ### vLLM -vLLM è incluso come Plugin provider integrato per server locali/self-hosted -compatibili OpenAI: +vLLM è distribuito come Plugin provider incluso per server locali/self-hosted compatibili con OpenAI: - Provider: `vllm` -- Auth: facoltativa (dipende dal tuo server) +- Autenticazione: facoltativa (dipende dal tuo server) - URL base predefinito: `http://127.0.0.1:8000/v1` -Per attivare il rilevamento automatico in locale (qualsiasi valore va bene se il tuo server non impone l'autenticazione): +Per eseguire l'opt-in all'auto-discovery in locale (qualsiasi valore funziona se il tuo server non impone autenticazione): ```bash export VLLM_API_KEY="vllm-local" ``` -Poi imposta un modello (sostituisci con uno degli ID restituiti da `/v1/models`): +Quindi imposta un modello (sostituisci con uno degli ID restituiti da `/v1/models`): ```json5 { @@ -548,21 +511,19 @@ Vedi [/providers/vllm](/it/providers/vllm) per i dettagli. ### SGLang -SGLang è incluso come Plugin provider integrato per server self-hosted -compatibili OpenAI ad alte prestazioni: +SGLang è distribuito come Plugin provider incluso per server self-hosted veloci compatibili con OpenAI: - Provider: `sglang` -- Auth: facoltativa (dipende dal tuo server) +- Autenticazione: facoltativa (dipende dal tuo server) - URL base predefinito: `http://127.0.0.1:30000/v1` -Per attivare il rilevamento automatico in locale (qualsiasi valore va bene se il tuo server non impone -l'autenticazione): +Per eseguire l'opt-in all'auto-discovery in locale (qualsiasi valore funziona se il tuo server non impone autenticazione): ```bash export SGLANG_API_KEY="sglang-local" ``` -Poi imposta un modello (sostituisci con uno degli ID restituiti da `/v1/models`): +Quindi imposta un modello (sostituisci con uno degli ID restituiti da `/v1/models`): ```json5 { @@ -576,7 +537,7 @@ Vedi [/providers/sglang](/it/providers/sglang) per i dettagli. ### Proxy locali (LM Studio, vLLM, LiteLLM, ecc.) -Esempio (compatibile OpenAI): +Esempio (compatibile con OpenAI): ```json5 { @@ -612,7 +573,7 @@ Esempio (compatibile OpenAI): Note: - Per i provider personalizzati, `reasoning`, `input`, `cost`, `contextWindow` e `maxTokens` sono facoltativi. - Quando omessi, OpenClaw usa come predefiniti: + Se omessi, OpenClaw usa questi valori predefiniti: - `reasoning: false` - `input: ["text"]` - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` @@ -620,12 +581,9 @@ Note: - `maxTokens: 8192` - Consigliato: imposta valori espliciti che corrispondano ai limiti del tuo proxy/modello. - Per `api: "openai-completions"` su endpoint non nativi (qualsiasi `baseUrl` non vuoto il cui host non sia `api.openai.com`), OpenClaw forza `compat.supportsDeveloperRole: false` per evitare errori 400 del provider dovuti a ruoli `developer` non supportati. -- I percorsi compatibili OpenAI in stile proxy saltano anche la - modellazione delle richieste riservata a OpenAI nativo: niente `service_tier`, niente `store` di Responses, nessun suggerimento di prompt-cache, nessuna - modellazione del payload compatibile con il reasoning OpenAI e nessun header - nascosto di attribuzione OpenClaw. +- I percorsi compatibili con OpenAI in stile proxy saltano anche la modellazione delle richieste riservata a OpenAI nativo: niente `service_tier`, niente `store` di Responses, niente suggerimenti di prompt-cache, niente modellazione del payload compatibile con il reasoning OpenAI e nessun header di attribuzione OpenClaw nascosto. - Se `baseUrl` è vuoto/omesso, OpenClaw mantiene il comportamento OpenAI predefinito (che risolve in `api.openai.com`). -- Per sicurezza, un `compat.supportsDeveloperRole: true` esplicito viene comunque sovrascritto sugli endpoint `openai-completions` non nativi. +- Per sicurezza, un valore esplicito `compat.supportsDeveloperRole: true` viene comunque sovrascritto sugli endpoint `openai-completions` non nativi. ## Esempi CLI @@ -640,6 +598,6 @@ Vedi anche: [/gateway/configuration](/it/gateway/configuration) per esempi compl ## Correlati - [Models](/it/concepts/models) — configurazione dei modelli e alias -- [Model Failover](/it/concepts/model-failover) — catene di fallback e comportamento di nuovo tentativo -- [Configuration Reference](/it/gateway/config-agents#agent-defaults) — chiavi di configurazione del modello -- [Providers](/it/providers) — guide di configurazione per provider +- [Failover dei modelli](/it/concepts/model-failover) — catene di fallback e comportamento dei retry +- [Riferimento della configurazione](/it/gateway/config-agents#agent-defaults) — chiavi di configurazione del modello +- [Provider](/it/providers) — guide di configurazione per provider diff --git a/docs/it/pi.md b/docs/it/pi.md index 2d6ac19f9..fce2224d4 100644 --- a/docs/it/pi.md +++ b/docs/it/pi.md @@ -1,48 +1,48 @@ --- read_when: - - Comprendere la progettazione dell'integrazione dell'SDK Pi in OpenClaw - - Modifica del ciclo di vita della sessione agente, del tooling o del wiring del provider per Pi -summary: Architettura dell'integrazione dell'agente Pi embedded di OpenClaw e ciclo di vita della sessione -title: Architettura di integrazione Pi + - Comprendere il design dell'integrazione dell'SDK di Pi in OpenClaw + - Modifica del ciclo di vita della sessione dell'agente, degli strumenti o del collegamento del provider per Pi +summary: Architettura dell'integrazione dell'agente Pi incorporato di OpenClaw e ciclo di vita della sessione +title: Architettura dell'integrazione di Pi x-i18n: - generated_at: "2026-04-24T08:49:07Z" + generated_at: "2026-04-24T15:23:17Z" model: gpt-5.4 provider: openai - source_hash: 3c0c490cad121a65d557a72887ea619a7d0cff34a62220752214185c9148dc0b + source_hash: 0c0b019ff6d35f6fdcd57b56edd1945e62a96bb4b34e312d7fb0c627f01287f1 source_path: pi.md workflow: 15 --- -Questo documento descrive come OpenClaw si integra con [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) e i suoi package correlati (`pi-ai`, `pi-agent-core`, `pi-tui`) per alimentare le proprie capacità di agente AI. +Questo documento descrive come OpenClaw si integra con [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) e con i pacchetti correlati (`pi-ai`, `pi-agent-core`, `pi-tui`) per alimentare le proprie funzionalità di agente AI. ## Panoramica -OpenClaw usa l'SDK pi per incorporare un agente di coding AI nella propria architettura gateway di messaggistica. Invece di avviare pi come sottoprocesso o usare la modalità RPC, OpenClaw importa e istanzia direttamente `AgentSession` di pi tramite `createAgentSession()`. Questo approccio embedded fornisce: +OpenClaw usa l'SDK di pi per incorporare un agente di coding AI nella propria architettura di Gateway di messaggistica. Invece di avviare pi come sottoprocesso o usare la modalità RPC, OpenClaw importa e istanzia direttamente `AgentSession` di pi tramite `createAgentSession()`. Questo approccio incorporato fornisce: -- Controllo completo sul ciclo di vita della sessione e sulla gestione degli eventi +- Controllo completo del ciclo di vita della sessione e della gestione degli eventi - Iniezione personalizzata degli strumenti (messaggistica, sandbox, azioni specifiche del canale) - Personalizzazione del prompt di sistema per canale/contesto - Persistenza della sessione con supporto per branching/Compaction -- Rotazione dei profili auth multi-account con failover -- Cambio modello indipendente dal provider +- Rotazione di più profili di autenticazione account con failover +- Cambio di modello indipendente dal provider -## Dipendenze dei package +## Dipendenze dei pacchetti ```json { - "@mariozechner/pi-agent-core": "0.68.1", - "@mariozechner/pi-ai": "0.68.1", - "@mariozechner/pi-coding-agent": "0.68.1", - "@mariozechner/pi-tui": "0.68.1" + "@mariozechner/pi-agent-core": "0.70.2", + "@mariozechner/pi-ai": "0.70.2", + "@mariozechner/pi-coding-agent": "0.70.2", + "@mariozechner/pi-tui": "0.70.2" } ``` -| Package | Scopo | -| ----------------- | ----------------------------------------------------------------------------------------------------- | -| `pi-ai` | Astrazioni LLM core: `Model`, `streamSimple`, tipi di messaggio, API provider | -| `pi-agent-core` | Loop dell'agente, esecuzione degli strumenti, tipi `AgentMessage` | -| `pi-coding-agent` | SDK di alto livello: `createAgentSession`, `SessionManager`, `AuthStorage`, `ModelRegistry`, strumenti integrati | -| `pi-tui` | Componenti UI terminale (usati nella modalità TUI locale di OpenClaw) | +| Pacchetto | Scopo | +| ----------------- | ------------------------------------------------------------------------------------------------------ | +| `pi-ai` | Astrazioni LLM di base: `Model`, `streamSimple`, tipi di messaggio, API del provider | +| `pi-agent-core` | Loop dell'agente, esecuzione degli strumenti, tipi `AgentMessage` | +| `pi-coding-agent` | SDK di alto livello: `createAgentSession`, `SessionManager`, `AuthStorage`, `ModelRegistry`, strumenti incorporati | +| `pi-tui` | Componenti UI del terminale (usati nella modalità TUI locale di OpenClaw) | ## Struttura dei file @@ -50,71 +50,71 @@ OpenClaw usa l'SDK pi per incorporare un agente di coding AI nella propria archi src/agents/ ├── pi-embedded-runner.ts # Re-export da pi-embedded-runner/ ├── pi-embedded-runner/ -│ ├── run.ts # Entry principale: runEmbeddedPiAgent() +│ ├── run.ts # Punto di ingresso principale: runEmbeddedPiAgent() │ ├── run/ -│ │ ├── attempt.ts # Logica del singolo tentativo con configurazione della sessione +│ │ ├── attempt.ts # Logica di un singolo tentativo con configurazione della sessione │ │ ├── params.ts # Tipo RunEmbeddedPiAgentParams -│ │ ├── payloads.ts # Costruisce i payload di risposta dai risultati dell'esecuzione -│ │ ├── images.ts # Iniezione delle immagini del modello vision +│ │ ├── payloads.ts # Costruzione dei payload di risposta dai risultati dell'esecuzione +│ │ ├── images.ts # Iniezione immagini del modello di visione │ │ └── types.ts # EmbeddedRunAttemptResult -│ ├── abort.ts # Rilevamento dell'errore di abort +│ ├── abort.ts # Rilevamento degli errori di interruzione │ ├── cache-ttl.ts # Tracciamento del TTL della cache per il pruning del contesto │ ├── compact.ts # Logica di Compaction manuale/automatica -│ ├── extensions.ts # Carica estensioni pi per esecuzioni embedded -│ ├── extra-params.ts # Parametri stream specifici del provider -│ ├── google.ts # Correzioni dell'ordine dei turni Google/Gemini +│ ├── extensions.ts # Caricamento delle estensioni pi per le esecuzioni incorporate +│ ├── extra-params.ts # Parametri di stream specifici del provider +│ ├── google.ts # Correzioni dell'ordinamento dei turni per Google/Gemini │ ├── history.ts # Limitazione della cronologia (DM vs gruppo) -│ ├── lanes.ts # Lane di comandi sessione/globali +│ ├── lanes.ts # Corsie di comando sessione/globali │ ├── logger.ts # Logger del sottosistema │ ├── model.ts # Risoluzione del modello tramite ModelRegistry -│ ├── runs.ts # Tracciamento delle esecuzioni attive, abort, coda -│ ├── sandbox-info.ts # Informazioni sandbox per il prompt di sistema -│ ├── session-manager-cache.ts # Caching dell'istanza SessionManager +│ ├── runs.ts # Tracciamento delle esecuzioni attive, interruzione, coda +│ ├── sandbox-info.ts # Informazioni sulla sandbox per il prompt di sistema +│ ├── session-manager-cache.ts # Cache delle istanze di SessionManager │ ├── session-manager-init.ts # Inizializzazione del file di sessione │ ├── system-prompt.ts # Costruttore del prompt di sistema -│ ├── tool-split.ts # Divide gli strumenti in builtIn vs custom +│ ├── tool-split.ts # Suddivisione degli strumenti in builtIn e custom │ ├── types.ts # EmbeddedPiAgentMeta, EmbeddedPiRunResult -│ └── utils.ts # Mapping ThinkLevel, descrizione errori -├── pi-embedded-subscribe.ts # Sottoscrizione/dispatch degli eventi di sessione +│ └── utils.ts # Mappatura di ThinkLevel, descrizione degli errori +├── pi-embedded-subscribe.ts # Sottoscrizione/instradamento degli eventi della sessione ├── pi-embedded-subscribe.types.ts # SubscribeEmbeddedPiSessionParams -├── pi-embedded-subscribe.handlers.ts # Factory di handler degli eventi +├── pi-embedded-subscribe.handlers.ts # Factory dei gestori di eventi ├── pi-embedded-subscribe.handlers.lifecycle.ts ├── pi-embedded-subscribe.handlers.types.ts -├── pi-embedded-block-chunker.ts # Chunking delle risposte a blocchi in streaming +├── pi-embedded-block-chunker.ts # Suddivisione in chunk delle risposte a blocchi in streaming ├── pi-embedded-messaging.ts # Tracciamento degli invii dello strumento di messaggistica ├── pi-embedded-helpers.ts # Classificazione degli errori, validazione dei turni -├── pi-embedded-helpers/ # Moduli helper -├── pi-embedded-utils.ts # Utility di formattazione +├── pi-embedded-helpers/ # Moduli di supporto +├── pi-embedded-utils.ts # Utilità di formattazione ├── pi-tools.ts # createOpenClawCodingTools() -├── pi-tools.abort.ts # Wrapping AbortSignal per gli strumenti -├── pi-tools.policy.ts # Policy allowlist/denylist degli strumenti -├── pi-tools.read.ts # Personalizzazioni dello strumento read +├── pi-tools.abort.ts # Wrapping di AbortSignal per gli strumenti +├── pi-tools.policy.ts # Policy di allowlist/denylist degli strumenti +├── pi-tools.read.ts # Personalizzazioni dello strumento di lettura ├── pi-tools.schema.ts # Normalizzazione dello schema degli strumenti ├── pi-tools.types.ts # Alias di tipo AnyAgentTool ├── pi-tool-definition-adapter.ts # Adattatore AgentTool -> ToolDefinition ├── pi-settings.ts # Override delle impostazioni ├── pi-hooks/ # Hook pi personalizzati -│ ├── compaction-safeguard.ts # Estensione safeguard +│ ├── compaction-safeguard.ts # Estensione di salvaguardia │ ├── compaction-safeguard-runtime.ts -│ ├── context-pruning.ts # Estensione di pruning del contesto cache-TTL +│ ├── context-pruning.ts # Estensione di pruning del contesto Cache-TTL │ └── context-pruning/ -├── model-auth.ts # Risoluzione del profilo auth -├── auth-profiles.ts # Archivio profili, cooldown, failover +├── model-auth.ts # Risoluzione del profilo di autenticazione +├── auth-profiles.ts # Archivio dei profili, cooldown, failover ├── model-selection.ts # Risoluzione del modello predefinito ├── models-config.ts # Generazione di models.json -├── model-catalog.ts # Cache del catalogo modelli +├── model-catalog.ts # Cache del catalogo dei modelli ├── context-window-guard.ts # Validazione della finestra di contesto ├── failover-error.ts # Classe FailoverError ├── defaults.ts # DEFAULT_PROVIDER, DEFAULT_MODEL ├── system-prompt.ts # buildAgentSystemPrompt() ├── system-prompt-params.ts # Risoluzione dei parametri del prompt di sistema ├── system-prompt-report.ts # Generazione del report di debug -├── tool-summaries.ts # Riepiloghi delle descrizioni degli strumenti +├── tool-summaries.ts # Riepiloghi della descrizione degli strumenti ├── tool-policy.ts # Risoluzione della policy degli strumenti ├── transcript-policy.ts # Policy di validazione della trascrizione -├── skills.ts # Costruzione di snapshot/prompt delle Skills +├── skills.ts # Snapshot delle Skills/costruzione del prompt ├── skills/ # Sottosistema Skills -├── sandbox.ts # Risoluzione del contesto sandbox +├── sandbox.ts # Risoluzione del contesto della sandbox ├── sandbox/ # Sottosistema sandbox ├── channel-tools.ts # Iniezione degli strumenti specifici del canale ├── openclaw-tools.ts # Strumenti specifici di OpenClaw @@ -134,19 +134,18 @@ src/agents/ └── ... ``` -I runtime delle azioni dei messaggi specifiche del canale ora si trovano nelle directory -delle estensioni possedute dal Plugin invece che sotto `src/agents/tools`, per esempio: +I runtime delle azioni di messaggio specifiche del canale ora si trovano nelle directory di estensione possedute dal Plugin invece che sotto `src/agents/tools`, per esempio: - i file runtime delle azioni del Plugin Discord - il file runtime delle azioni del Plugin Slack - il file runtime delle azioni del Plugin Telegram - il file runtime delle azioni del Plugin WhatsApp -## Flusso principale di integrazione +## Flusso di integrazione principale -### 1. Esecuzione di un agente embedded +### 1. Esecuzione di un agente incorporato -L'entry principale è `runEmbeddedPiAgent()` in `pi-embedded-runner/run.ts`: +Il punto di ingresso principale è `runEmbeddedPiAgent()` in `pi-embedded-runner/run.ts`: ```typescript import { runEmbeddedPiAgent } from "./agents/pi-embedded-runner.js"; @@ -170,7 +169,7 @@ const result = await runEmbeddedPiAgent({ ### 2. Creazione della sessione -Dentro `runEmbeddedAttempt()` (chiamato da `runEmbeddedPiAgent()`), viene usato l'SDK pi: +All'interno di `runEmbeddedAttempt()` (chiamato da `runEmbeddedPiAgent()`), viene usato l'SDK di pi: ```typescript import { @@ -234,33 +233,31 @@ Gli eventi gestiti includono: ### 4. Prompting -Dopo la configurazione, la sessione riceve il prompt: +Dopo la configurazione, il prompt viene inviato alla sessione: ```typescript await session.prompt(effectivePrompt, { images: imageResult.images }); ``` -L'SDK gestisce l'intero loop dell'agente: invio all'LLM, esecuzione delle chiamate agli strumenti, streaming delle risposte. +L'SDK gestisce il loop completo dell'agente: invio all'LLM, esecuzione delle chiamate agli strumenti, streaming delle risposte. -L'iniezione delle immagini è locale al prompt: OpenClaw carica i riferimenti immagine dal prompt corrente e -li passa tramite `images` solo per quel turno. Non riesegue la scansione dei turni più vecchi della cronologia -per reinserire i payload immagine. +L'iniezione delle immagini è locale al prompt: OpenClaw carica i riferimenti alle immagini dal prompt corrente e li passa tramite `images` solo per quel turno. Non esegue nuovamente la scansione dei turni di cronologia precedenti per re-iniettare i payload delle immagini. ## Architettura degli strumenti ### Pipeline degli strumenti -1. **Strumenti di base**: `codingTools` di pi (read, bash, edit, write) +1. **Strumenti di base**: `codingTools` di pi (`read`, `bash`, `edit`, `write`) 2. **Sostituzioni personalizzate**: OpenClaw sostituisce bash con `exec`/`process`, personalizza read/edit/write per la sandbox -3. **Strumenti OpenClaw**: messaggistica, browser, canvas, sessioni, cron, gateway, ecc. -4. **Strumenti di canale**: strumenti di azione specifici per Discord/Telegram/Slack/WhatsApp -5. **Filtro delle policy**: strumenti filtrati per profilo, provider, agente, gruppo, policy sandbox +3. **Strumenti OpenClaw**: messaggistica, browser, canvas, sessioni, Cron, Gateway, ecc. +4. **Strumenti del canale**: strumenti di azione specifici per Discord/Telegram/Slack/WhatsApp +5. **Filtraggio tramite policy**: strumenti filtrati in base a policy di profilo, provider, agente, gruppo e sandbox 6. **Normalizzazione dello schema**: gli schemi vengono ripuliti per le particolarità di Gemini/OpenAI -7. **Wrapping AbortSignal**: gli strumenti vengono wrappati per rispettare gli abort signal +7. **Wrapping di AbortSignal**: gli strumenti vengono wrappati per rispettare i segnali di interruzione -### Adattatore della definizione degli strumenti +### Adattatore di definizione degli strumenti -`AgentTool` di pi-agent-core ha una firma `execute` diversa da `ToolDefinition` di pi-coding-agent. L'adattatore in `pi-tool-definition-adapter.ts` crea il ponte: +`AgentTool` di pi-agent-core ha una firma `execute` diversa da `ToolDefinition` di pi-coding-agent. L'adattatore in `pi-tool-definition-adapter.ts` colma questa differenza: ```typescript export function toToolDefinitions(tools: AnyAgentTool[]): ToolDefinition[] { @@ -284,17 +281,17 @@ export function toToolDefinitions(tools: AnyAgentTool[]): ToolDefinition[] { ```typescript export function splitSdkTools(options: { tools: AnyAgentTool[]; sandboxEnabled: boolean }) { return { - builtInTools: [], // Vuoto. Sovrascriviamo tutto + builtInTools: [], // Vuoto. Sostituiamo tutto customTools: toToolDefinitions(options.tools), }; } ``` -Questo garantisce che il filtro delle policy di OpenClaw, l'integrazione con la sandbox e il set esteso di strumenti restino coerenti tra i provider. +Questo garantisce che il filtraggio tramite policy di OpenClaw, l'integrazione con la sandbox e il set di strumenti esteso rimangano coerenti tra i vari provider. ## Costruzione del prompt di sistema -Il prompt di sistema viene costruito in `buildAgentSystemPrompt()` (`system-prompt.ts`). Assembla un prompt completo con sezioni che includono Tooling, Tool Call Style, guardrail di sicurezza, riferimento CLI OpenClaw, Skills, documentazione, Workspace, Sandbox, Messaggistica, Reply Tags, Voce, Risposte silenziose, Heartbeat, metadati Runtime, più Memoria e Reazioni quando abilitati, e file di contesto facoltativi e contenuto extra del prompt di sistema. Le sezioni vengono ridotte per la modalità di prompt minima usata dai subagenti. +Il prompt di sistema viene costruito in `buildAgentSystemPrompt()` (`system-prompt.ts`). Assembla un prompt completo con sezioni che includono Tooling, stile delle chiamate agli strumenti, guardrail di sicurezza, riferimento alla CLI di OpenClaw, Skills, documentazione, workspace, sandbox, messaggistica, tag di risposta, voce, risposte silenziose, Heartbeat, metadati di runtime, oltre a Memory e Reactions quando abilitati, e file di contesto opzionali e contenuto aggiuntivo del prompt di sistema. Le sezioni vengono ridotte per la modalità prompt minima usata dai sottoagenti. Il prompt viene applicato dopo la creazione della sessione tramite `applySystemPromptOverrideToSession()`: @@ -307,17 +304,17 @@ applySystemPromptOverrideToSession(session, systemPromptOverride); ### File di sessione -Le sessioni sono file JSONL con struttura ad albero (collegamento id/parentId). `SessionManager` di Pi gestisce la persistenza: +Le sessioni sono file JSONL con struttura ad albero (collegamento tramite id/parentId). `SessionManager` di Pi gestisce la persistenza: ```typescript const sessionManager = SessionManager.open(params.sessionFile); ``` -OpenClaw lo wrappa con `guardSessionManager()` per la sicurezza dei risultati degli strumenti. +OpenClaw lo incapsula con `guardSessionManager()` per la sicurezza dei risultati degli strumenti. -### Caching della sessione +### Cache della sessione -`session-manager-cache.ts` mantiene in cache le istanze di SessionManager per evitare parsing ripetuti dei file: +`session-manager-cache.ts` mantiene in cache le istanze di SessionManager per evitare il parsing ripetuto dei file: ```typescript await prewarmSessionFile(params.sessionFile); @@ -331,12 +328,7 @@ trackSessionManagerAccess(params.sessionFile); ### Compaction -La auto-Compaction si attiva in caso di overflow del contesto. Le firme comuni di overflow -includono `request_too_large`, `context length exceeded`, `input exceeds the -maximum number of tokens`, `input token count exceeds the maximum number of -input tokens`, `input is too long for the model` e `ollama error: context -length exceeded`. `compactEmbeddedPiSessionDirect()` gestisce la -Compaction manuale: +La Compaction automatica si attiva in caso di overflow del contesto. Le firme comuni di overflow includono `request_too_large`, `context length exceeded`, `input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `input is too long for the model` e `ollama error: context length exceeded`. `compactEmbeddedPiSessionDirect()` gestisce la Compaction manuale: ```typescript const compactResult = await compactEmbeddedPiSessionDirect({ @@ -346,9 +338,9 @@ const compactResult = await compactEmbeddedPiSessionDirect({ ## Autenticazione e risoluzione del modello -### Profili auth +### Profili di autenticazione -OpenClaw mantiene un archivio di profili auth con più chiavi API per provider: +OpenClaw mantiene un archivio di profili di autenticazione con più chiavi API per provider: ```typescript const authStore = ensureAuthProfileStore(agentDir, { allowKeychainPrompt: false }); @@ -374,7 +366,7 @@ const { model, error, authStorage, modelRegistry } = resolveModel( config, ); -// Usa ModelRegistry e AuthStorage di pi +// Usa ModelRegistry e AuthStorage di Pi authStorage.setRuntimeApiKey(model.provider, apiKeyInfo.apiKey); ``` @@ -396,11 +388,11 @@ if (fallbackConfigured && isFailoverErrorMessage(errorText)) { ## Estensioni Pi -OpenClaw carica estensioni pi personalizzate per comportamenti specializzati: +OpenClaw carica estensioni Pi personalizzate per comportamenti specializzati: -### Safeguard di Compaction +### Salvaguardia della Compaction -`src/agents/pi-hooks/compaction-safeguard.ts` aggiunge guardrail alla Compaction, inclusi budgeting adattivo dei token più riepiloghi dei guasti degli strumenti e delle operazioni sui file: +`src/agents/pi-hooks/compaction-safeguard.ts` aggiunge guardrail alla Compaction, inclusi budgeting adattivo dei token più riepiloghi degli errori degli strumenti e delle operazioni sui file: ```typescript if (resolveCompactionMode(params.cfg) === "safeguard") { @@ -411,7 +403,7 @@ if (resolveCompactionMode(params.cfg) === "safeguard") { ### Pruning del contesto -`src/agents/pi-hooks/context-pruning.ts` implementa il pruning del contesto basato su cache-TTL: +`src/agents/pi-hooks/context-pruning.ts` implementa il pruning del contesto basato su Cache-TTL: ```typescript if (cfg?.agents?.defaults?.contextPruning?.mode === "cache-ttl") { @@ -427,28 +419,28 @@ if (cfg?.agents?.defaults?.contextPruning?.mode === "cache-ttl") { ## Streaming e risposte a blocchi -### Chunking dei blocchi +### Suddivisione in blocchi -`EmbeddedBlockChunker` gestisce il testo in streaming in blocchi di risposta discreti: +`EmbeddedBlockChunker` gestisce lo streaming del testo in blocchi di risposta discreti: ```typescript const blockChunker = blockChunking ? new EmbeddedBlockChunker(blockChunking) : null; ``` -### Rimozione dei tag Thinking/Final +### Rimozione dei tag thinking/final -L'output in streaming viene elaborato per rimuovere i blocchi ``/`` ed estrarre il contenuto ``: +L'output in streaming viene elaborato per rimuovere i blocchi ``/`` ed estrarre il contenuto di ``: ```typescript const stripBlockTags = (text: string, state: { thinking: boolean; final: boolean }) => { // Rimuove il contenuto ... - // Se enforceFinalTag, restituisce solo il contenuto ... + // Se enforceFinalTag è attivo, restituisce solo il contenuto ... }; ``` ### Direttive di risposta -Direttive di risposta come `[[media:url]]`, `[[voice]]`, `[[reply:id]]` vengono analizzate ed estratte: +Le direttive di risposta come `[[media:url]]`, `[[voice]]`, `[[reply:id]]` vengono analizzate ed estratte: ```typescript const { text: cleanedText, mediaUrls, audioAsVoice, replyToId } = consumeReplyDirectives(chunk); @@ -462,16 +454,16 @@ const { text: cleanedText, mediaUrls, audioAsVoice, replyToId } = consumeReplyDi ```typescript isContextOverflowError(errorText) // Contesto troppo grande -isCompactionFailureError(errorText) // Compaction fallita -isAuthAssistantError(lastAssistant) // Errore auth -isRateLimitAssistantError(...) // Rate limited -isFailoverAssistantError(...) // Deve fare failover +isCompactionFailureError(errorText) // Compaction non riuscita +isAuthAssistantError(lastAssistant) // Errore di autenticazione +isRateLimitAssistantError(...) // Rate limit raggiunto +isFailoverAssistantError(...) // Deve eseguire failover classifyFailoverReason(errorText) // "auth" | "rate_limit" | "quota" | "timeout" | ... ``` ### Fallback del livello di thinking -Se un livello di thinking non è supportato, viene usato il fallback: +Se un livello di thinking non è supportato, viene usato un fallback: ```typescript const fallbackThinking = pickFallbackThinkingLevel({ @@ -486,7 +478,7 @@ if (fallbackThinking) { ## Integrazione con la sandbox -Quando la modalità sandbox è abilitata, strumenti e percorsi sono vincolati: +Quando la modalità sandbox è abilitata, gli strumenti e i percorsi sono vincolati: ```typescript const sandbox = await resolveSandboxContext({ @@ -506,55 +498,55 @@ if (sandboxRoot) { ### Anthropic -- Pulizia della stringa magica di rifiuto -- Validazione del turno per ruoli consecutivi -- Validazione rigorosa a monte dei parametri degli strumenti Pi +- Rimozione della stringa magica di rifiuto +- Validazione dei turni per ruoli consecutivi +- Validazione rigorosa a monte dei parametri degli strumenti di Pi ### Google/Gemini -- Sanitizzazione dello schema degli strumenti posseduta dal Plugin +- Sanificazione dello schema degli strumenti posseduti dal Plugin ### OpenAI -- Strumento `apply_patch` per modelli Codex +- Strumento `apply_patch` per i modelli Codex - Gestione del downgrade del livello di thinking ## Integrazione TUI -OpenClaw ha anche una modalità TUI locale che usa direttamente i componenti pi-tui: +OpenClaw dispone anche di una modalità TUI locale che usa direttamente i componenti di pi-tui: ```typescript // src/tui/tui.ts import { ... } from "@mariozechner/pi-tui"; ``` -Questo fornisce un'esperienza terminale interattiva simile alla modalità nativa di Pi. +Questo fornisce l'esperienza di terminale interattivo simile alla modalità nativa di pi. -## Differenze chiave rispetto alla CLI Pi +## Differenze principali rispetto alla CLI di Pi -| Aspetto | CLI Pi | OpenClaw Embedded | -| --------------- | ----------------------- | ---------------------------------------------------------------------------------------------- | -| Invocazione | comando `pi` / RPC | SDK tramite `createAgentSession()` | -| Strumenti | Strumenti di coding predefiniti | Suite di strumenti OpenClaw personalizzata | -| Prompt di sistema | AGENTS.md + prompt | Dinamico per canale/contesto | -| Archiviazione sessione | `~/.pi/agent/sessions/` | `~/.openclaw/agents//sessions/` (o `$OPENCLAW_STATE_DIR/agents//sessions/`) | -| Auth | Credenziale singola | Multi-profilo con rotazione | -| Estensioni | Caricate da disco | Percorsi programmatici + da disco | -| Gestione eventi | Rendering TUI | Basata su callback (`onBlockReply`, ecc.) | +| Aspetto | CLI di Pi | OpenClaw incorporato | +| --------------- | ----------------------- | ----------------------------------------------------------------------------------------------- | +| Invocazione | comando `pi` / RPC | SDK tramite `createAgentSession()` | +| Strumenti | Strumenti di coding predefiniti | Suite di strumenti OpenClaw personalizzata | +| Prompt di sistema | AGENTS.md + prompt | Dinamico per canale/contesto | +| Archiviazione sessione | `~/.pi/agent/sessions/` | `~/.openclaw/agents//sessions/` (oppure `$OPENCLAW_STATE_DIR/agents//sessions/`) | +| Auth | Credenziale singola | Multi-profilo con rotazione | +| Estensioni | Caricate dal disco | Percorsi programmatici + da disco | +| Gestione eventi | Rendering TUI | Basata su callback (`onBlockReply`, ecc.) | ## Considerazioni future Aree di possibile rielaborazione: -1. **Allineamento della firma degli strumenti**: attualmente adattamento tra le firme di pi-agent-core e pi-coding-agent -2. **Wrapping del session manager**: `guardSessionManager` aggiunge sicurezza ma aumenta la complessità -3. **Caricamento delle estensioni**: potrebbe usare più direttamente `ResourceLoader` di pi -4. **Complessità del gestore streaming**: `subscribeEmbeddedPiSession` è diventato grande -5. **Particolarità dei provider**: molti codepath specifici del provider che potenzialmente pi potrebbe gestire +1. **Allineamento della firma degli strumenti**: attualmente viene effettuato un adattamento tra le firme di pi-agent-core e pi-coding-agent +2. **Wrapping del gestore della sessione**: `guardSessionManager` aggiunge sicurezza ma aumenta la complessità +3. **Caricamento delle estensioni**: potrebbe usare `ResourceLoader` di pi più direttamente +4. **Complessità del gestore dello streaming**: `subscribeEmbeddedPiSession` è cresciuto molto +5. **Particolarità dei provider**: molti percorsi di codice specifici del provider che pi potrebbe potenzialmente gestire ## Test -La copertura dell'integrazione Pi si estende a queste suite: +La copertura dell'integrazione di Pi include queste suite: - `src/agents/pi-*.test.ts` - `src/agents/pi-auth-json.test.ts` @@ -570,11 +562,11 @@ La copertura dell'integrazione Pi si estende a queste suite: Live/opt-in: -- `src/agents/pi-embedded-runner-extraparams.live.test.ts` (abilita `OPENCLAW_LIVE_TEST=1`) +- `src/agents/pi-embedded-runner-extraparams.live.test.ts` (abilitare `OPENCLAW_LIVE_TEST=1`) -Per i comandi di esecuzione correnti, vedi [Flusso di lavoro di sviluppo Pi](/it/pi-dev). +Per i comandi di esecuzione correnti, vedere [Flusso di sviluppo di Pi](/it/pi-dev). ## Correlati -- [Flusso di lavoro di sviluppo Pi](/it/pi-dev) +- [Flusso di sviluppo di Pi](/it/pi-dev) - [Panoramica dell'installazione](/it/install) diff --git a/docs/it/providers/deepseek.md b/docs/it/providers/deepseek.md index 909c0afdd..89db90d81 100644 --- a/docs/it/providers/deepseek.md +++ b/docs/it/providers/deepseek.md @@ -1,26 +1,26 @@ --- read_when: - Vuoi usare DeepSeek con OpenClaw - - Hai bisogno della variabile d’ambiente della chiave API o della scelta di autenticazione CLI + - Ti serve la variabile d'ambiente della chiave API o l'opzione di autenticazione della CLI summary: Configurazione di DeepSeek (autenticazione + selezione del modello) title: DeepSeek x-i18n: - generated_at: "2026-04-24T08:56:05Z" + generated_at: "2026-04-24T15:23:17Z" model: gpt-5.4 provider: openai - source_hash: ead407c67c05bd8700db1cba36defdd9d47bdc9a071c76a07c4b4fb82f6b80e2 + source_hash: 5b0d2345c72328e14351d71c5784204dc6ed9dc922f919b6adfac394001c3261 source_path: providers/deepseek.md workflow: 15 --- -[DeepSeek](https://www.deepseek.com) fornisce potenti modelli AI con un’API OpenAI-compatible. +[DeepSeek](https://www.deepseek.com) fornisce potenti modelli di IA con un'API compatibile con OpenAI. | Proprietà | Valore | | --------- | -------------------------- | | Provider | `deepseek` | | Auth | `DEEPSEEK_API_KEY` | -| API | OpenAI-compatible | -| Base URL | `https://api.deepseek.com` | +| API | Compatibile con OpenAI | +| URL di base | `https://api.deepseek.com` | ## Per iniziare @@ -28,12 +28,12 @@ x-i18n: Crea una chiave API su [platform.deepseek.com](https://platform.deepseek.com/api_keys). - + ```bash openclaw onboard --auth-choice deepseek-api-key ``` - Questo chiederà la tua chiave API e imposterà `deepseek/deepseek-chat` come modello predefinito. + Ti verrà chiesta la chiave API e `deepseek/deepseek-v4-flash` verrà impostato come modello predefinito. @@ -45,7 +45,7 @@ x-i18n: - Per installazioni scriptate o headless, passa direttamente tutti i flag: + Per installazioni con script o headless, passa direttamente tutti i flag: ```bash openclaw onboard --non-interactive \ @@ -60,20 +60,24 @@ x-i18n: -Se il Gateway viene eseguito come daemon (launchd/systemd), assicurati che `DEEPSEEK_API_KEY` -sia disponibile per quel processo (per esempio in `~/.openclaw/.env` oppure tramite +Se il Gateway è in esecuzione come demone (launchd/systemd), assicurati che `DEEPSEEK_API_KEY` +sia disponibile per quel processo (ad esempio in `~/.openclaw/.env` o tramite `env.shellEnv`). ## Catalogo integrato -| Riferimento modello | Nome | Input | Contesto | Output max | Note | -| ---------------------------- | ----------------- | ----- | -------- | ---------- | --------------------------------------------------- | -| `deepseek/deepseek-chat` | DeepSeek Chat | text | 131,072 | 8,192 | Modello predefinito; superficie non-thinking DeepSeek V3.2 | -| `deepseek/deepseek-reasoner` | DeepSeek Reasoner | text | 131,072 | 65,536 | Superficie V3.2 con ragionamento abilitato | +| Riferimento modello | Nome | Input | Contesto | Output max | Note | +| ---------------------------- | ----------------- | ----- | --------- | ---------- | ------------------------------------------ | +| `deepseek/deepseek-v4-flash` | DeepSeek V4 Flash | text | 1,000,000 | 384,000 | Modello predefinito; superficie V4 con capacità di thinking | +| `deepseek/deepseek-v4-pro` | DeepSeek V4 Pro | text | 1,000,000 | 384,000 | Superficie V4 con capacità di thinking | +| `deepseek/deepseek-chat` | DeepSeek Chat | text | 131,072 | 8,192 | Superficie non-thinking DeepSeek V3.2 | +| `deepseek/deepseek-reasoner` | DeepSeek Reasoner | text | 131,072 | 65,536 | Superficie V3.2 con ragionamento abilitato | -Entrambi i modelli inclusi attualmente dichiarano compatibilità con l’uso in streaming nel sorgente. +I modelli V4 supportano il controllo `thinking` di DeepSeek. OpenClaw riproduce anche +`reasoning_content` di DeepSeek nei turni successivi, così le sessioni di thinking con chiamate +agli strumenti possono continuare. ## Esempio di configurazione @@ -83,7 +87,7 @@ Entrambi i modelli inclusi attualmente dichiarano compatibilità con l’uso in env: { DEEPSEEK_API_KEY: "sk-..." }, agents: { defaults: { - model: { primary: "deepseek/deepseek-chat" }, + model: { primary: "deepseek/deepseek-v4-flash" }, }, }, } diff --git a/docs/it/tools/plugin.md b/docs/it/tools/plugin.md index 65ca18a5e..d840c634b 100644 --- a/docs/it/tools/plugin.md +++ b/docs/it/tools/plugin.md @@ -7,21 +7,21 @@ sidebarTitle: Install and Configure summary: Installa, configura e gestisci i plugin di OpenClaw title: Plugin x-i18n: - generated_at: "2026-04-24T09:54:53Z" + generated_at: "2026-04-24T15:23:22Z" model: gpt-5.4 provider: openai - source_hash: 83ab1218d6677ad518a4991ca546d55eed9648e1fa92b76b7433ecd5df569e28 + source_hash: 947bb7ffc13280fd63f79bb68cb18a37c6614144b91a83afd38e5ac3c5187aed source_path: tools/plugin.md workflow: 15 --- -I plugin estendono OpenClaw con nuove capacità: canali, provider di modelli, -harness per agenti, strumenti, Skills, voce, trascrizione in tempo reale, voce -in tempo reale, comprensione dei media, generazione di immagini, generazione di -video, recupero web, ricerca web e altro ancora. Alcuni plugin sono **core** -(inclusi con OpenClaw), altri sono **external** (pubblicati su npm dalla comunità). +I plugin estendono OpenClaw con nuove funzionalità: canali, provider di modelli, +harness per agenti, strumenti, Skills, voce, trascrizione in tempo reale, voce in tempo reale, +comprensione dei media, generazione di immagini, generazione di video, recupero dal web, ricerca sul web +e altro ancora. Alcuni plugin sono **core** (forniti con OpenClaw), altri +sono **esterni** (pubblicati su npm dalla community). -## Avvio rapido +## Guida rapida @@ -35,7 +35,7 @@ video, recupero web, ricerca web e altro ancora. Alcuni plugin sono **core** # Da npm openclaw plugins install @openclaw/voice-call - # Da una directory o un archivio locale + # Da una directory locale o un archivio openclaw plugins install ./my-plugin openclaw plugins install ./my-plugin.tgz ``` @@ -47,7 +47,7 @@ video, recupero web, ricerca web e altro ancora. Alcuni plugin sono **core** openclaw gateway restart ``` - Quindi configura in `plugins.entries.\.config` nel tuo file di configurazione. + Poi configura in `plugins.entries.\.config` nel tuo file di configurazione. @@ -60,17 +60,17 @@ Se preferisci un controllo nativo via chat, abilita `commands.plugins: true` e u /plugin enable voice-call ``` -Il percorso di installazione usa lo stesso resolver della CLI: percorso/archivio locale, `clawhub:` esplicito oppure specifica pacchetto semplice (prima ClawHub, poi fallback a npm). +Il percorso di installazione usa lo stesso resolver della CLI: percorso/archivio locale, `clawhub:` esplicito oppure specifica package semplice (prima ClawHub, poi fallback a npm). Se la configurazione non è valida, l'installazione normalmente fallisce in modo sicuro e ti indirizza a -`openclaw doctor --fix`. L'unica eccezione di ripristino è un percorso ristretto di reinstallazione -di plugin inclusi per i plugin che aderiscono a +`openclaw doctor --fix`. L'unica eccezione di recupero è un percorso limitato di +reinstallazione di plugin inclusi per i plugin che aderiscono a `openclaw.install.allowInvalidConfigRecovery`. -Le installazioni pacchettizzate di OpenClaw non installano in modo anticipato l'intero -albero delle dipendenze runtime di ogni plugin incluso. Quando un plugin incluso di proprietà di OpenClaw è attivo dalla -configurazione dei plugin, dalla configurazione legacy del canale o da un manifest abilitato per impostazione predefinita, -l'avvio ripara soltanto le dipendenze runtime dichiarate da quel plugin prima di importarlo. +Le installazioni pacchettizzate di OpenClaw non installano preventivamente l'intero albero delle dipendenze di runtime di ogni plugin incluso. +Quando un plugin incluso di proprietà OpenClaw è attivo dalla configurazione dei +plugin, dalla configurazione legacy del canale o da un manifest abilitato per impostazione predefinita, l'avvio +ripara solo le dipendenze di runtime dichiarate da quel plugin prima di importarlo. I plugin esterni e i percorsi di caricamento personalizzati devono comunque essere installati tramite `openclaw plugins install`. @@ -78,21 +78,21 @@ I plugin esterni e i percorsi di caricamento personalizzati devono comunque esse OpenClaw riconosce due formati di plugin: -| Formato | Come funziona | Esempi | -| ---------- | --------------------------------------------------------------- | ------------------------------------------------------ | -| **Native** | `openclaw.plugin.json` + modulo runtime; viene eseguito nel processo | Plugin ufficiali, pacchetti npm della comunità | +| Formato | Come funziona | Esempi | +| ---------- | ---------------------------------------------------------------- | ------------------------------------------------------ | +| **Nativo** | `openclaw.plugin.json` + modulo di runtime; viene eseguito in-process | Plugin ufficiali, package npm della community | | **Bundle** | Layout compatibile con Codex/Claude/Cursor; mappato sulle funzionalità di OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` | -Entrambi compaiono in `openclaw plugins list`. Vedi [Plugin Bundles](/it/plugins/bundles) per i dettagli sui bundle. +Entrambi compaiono in `openclaw plugins list`. Vedi [Bundle di plugin](/it/plugins/bundles) per i dettagli sui bundle. -Se stai scrivendo un plugin nativo, inizia da [Building Plugins](/it/plugins/building-plugins) -e dalla [Plugin SDK Overview](/it/plugins/sdk-overview). +Se stai scrivendo un plugin nativo, inizia da [Creare plugin](/it/plugins/building-plugins) +e dalla [Panoramica del Plugin SDK](/it/plugins/sdk-overview). ## Plugin ufficiali ### Installabili (npm) -| Plugin | Pacchetto | Documentazione | +| Plugin | Package | Documentazione | | --------------- | ---------------------- | ------------------------------------ | | Matrix | `@openclaw/matrix` | [Matrix](/it/channels/matrix) | | Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/it/channels/msteams) | @@ -101,7 +101,7 @@ e dalla [Plugin SDK Overview](/it/plugins/sdk-overview). | Zalo | `@openclaw/zalo` | [Zalo](/it/channels/zalo) | | Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/it/plugins/zalouser) | -### Core (inclusi con OpenClaw) +### Core (forniti con OpenClaw) @@ -114,7 +114,7 @@ e dalla [Plugin SDK Overview](/it/plugins/sdk-overview). - `memory-core` — ricerca nella memoria inclusa (predefinita tramite `plugins.slots.memory`) - - `memory-lancedb` — memoria a lungo termine con installazione su richiesta con richiamo/acquisizione automatica (imposta `plugins.slots.memory = "memory-lancedb"`) + - `memory-lancedb` — memoria a lungo termine installata su richiesta con richiamo/acquisizione automatica (imposta `plugins.slots.memory = "memory-lancedb"`) @@ -122,12 +122,12 @@ e dalla [Plugin SDK Overview](/it/plugins/sdk-overview). - - `browser` — plugin browser incluso per lo strumento browser, la CLI `openclaw browser`, il metodo Gateway `browser.request`, il runtime browser e il servizio di controllo browser predefinito (abilitato per impostazione predefinita; disabilitalo prima di sostituirlo) + - `browser` — plugin browser incluso per lo strumento browser, la CLI `openclaw browser`, il metodo gateway `browser.request`, il runtime browser e il servizio predefinito di controllo del browser (abilitato per impostazione predefinita; disabilitalo prima di sostituirlo) - `copilot-proxy` — bridge VS Code Copilot Proxy (disabilitato per impostazione predefinita) -Cerchi plugin di terze parti? Vedi [Community Plugins](/it/plugins/community). +Cerchi plugin di terze parti? Vedi [Plugin della community](/it/plugins/community). ## Configurazione @@ -145,23 +145,34 @@ Cerchi plugin di terze parti? Vedi [Community Plugins](/it/plugins/community). } ``` -| Campo | Descrizione | -| ---------------- | ---------------------------------------------------------- | -| `enabled` | Interruttore principale (predefinito: `true`) | -| `allow` | Allowlist dei plugin (facoltativa) | -| `deny` | Denylist dei plugin (facoltativa; deny ha la precedenza) | -| `load.paths` | File/directory di plugin aggiuntivi | +| Campo | Descrizione | +| ---------------- | -------------------------------------------------------- | +| `enabled` | Interruttore principale (predefinito: `true`) | +| `allow` | Allowlist dei plugin (facoltativa) | +| `deny` | Denylist dei plugin (facoltativa; deny ha la precedenza) | +| `load.paths` | File/directory plugin aggiuntivi | | `slots` | Selettori di slot esclusivi (ad es. `memory`, `contextEngine`) | -| `entries.\` | Attivazione/disattivazione + configurazione per plugin | +| `entries.\` | Interruttori per plugin + configurazione | -Le modifiche alla configurazione **richiedono un riavvio del gateway**. Se il Gateway è in esecuzione con il monitoraggio -della configurazione + il riavvio in-process abilitati (il percorso predefinito `openclaw gateway`), quel -riavvio viene in genere eseguito automaticamente poco dopo che la scrittura della configurazione è stata applicata. +Le modifiche alla configurazione **richiedono un riavvio del Gateway**. Se il Gateway è in esecuzione con il monitoraggio +della configurazione + riavvio in-process abilitato (il percorso predefinito di `openclaw gateway`), quel +riavvio viene di solito eseguito automaticamente poco dopo che la scrittura della configurazione è stata applicata. +Non esiste un percorso supportato di hot-reload per il codice di runtime nativo del plugin o per gli hook +del ciclo di vita; riavvia il processo Gateway che sta servendo il canale live prima di +aspettarti che il codice aggiornato di `register(api)`, gli hook `api.on(...)`, gli strumenti, i servizi o gli +hook di provider/runtime vengano eseguiti. - - - **Disabled**: il plugin esiste ma le regole di abilitazione lo hanno disattivato. La configurazione viene mantenuta. - - **Missing**: la configurazione fa riferimento a un id plugin che il rilevamento non ha trovato. - - **Invalid**: il plugin esiste ma la sua configurazione non corrisponde allo schema dichiarato. +`openclaw plugins list` è un'istantanea locale di CLI/configurazione. Un plugin `loaded` +in quell'elenco significa che il plugin è individuabile e caricabile dalla configurazione/dai file visti da quella +invocazione della CLI. Non prova che un Gateway remoto già in esecuzione +sia stato riavviato con lo stesso codice del plugin. In configurazioni VPS/container con processi wrapper, +invia i riavvii al processo effettivo `openclaw gateway run`, oppure usa +`openclaw gateway restart` sul Gateway in esecuzione. + + + - **Disabilitato**: il plugin esiste ma le regole di abilitazione lo hanno disattivato. La configurazione viene preservata. + - **Mancante**: la configurazione fa riferimento a un ID plugin che il rilevamento non ha trovato. + - **Non valido**: il plugin esiste ma la sua configurazione non corrisponde allo schema dichiarato. ## Rilevamento e precedenza @@ -182,7 +193,7 @@ OpenClaw esegue la scansione dei plugin in questo ordine (la prima corrispondenz - Inclusi con OpenClaw. Molti sono abilitati per impostazione predefinita (provider di modelli, voce). + Forniti con OpenClaw. Molti sono abilitati per impostazione predefinita (provider di modelli, voce). Altri richiedono un'abilitazione esplicita. @@ -192,16 +203,37 @@ OpenClaw esegue la scansione dei plugin in questo ordine (la prima corrispondenz - `plugins.enabled: false` disabilita tutti i plugin - `plugins.deny` ha sempre la precedenza su allow - `plugins.entries.\.enabled: false` disabilita quel plugin -- I plugin provenienti dal workspace sono **disabilitati per impostazione predefinita** (devono essere abilitati esplicitamente) -- I plugin inclusi seguono l'insieme predefinito interno di quelli attivi, salvo override +- I plugin originati dal workspace sono **disabilitati per impostazione predefinita** (devono essere abilitati esplicitamente) +- I plugin inclusi seguono l'insieme interno predefinito di quelli attivi, salvo override - Gli slot esclusivi possono forzare l'abilitazione del plugin selezionato per quello slot -- Alcuni plugin inclusi opzionali vengono abilitati automaticamente quando la configurazione assegna un nome a - una superficie posseduta dal plugin, come un riferimento a un modello provider, una configurazione di canale o un +- Alcuni plugin inclusi opzionali vengono abilitati automaticamente quando la configurazione nomina una + superficie posseduta dal plugin, come un riferimento al modello del provider, una configurazione di canale o un runtime harness -- I percorsi Codex della famiglia OpenAI mantengono confini tra plugin separati: - `openai-codex/*` appartiene al plugin OpenAI, mentre il plugin app-server Codex incluso - viene selezionato da `embeddedHarness.runtime: "codex"` o dai riferimenti legacy ai modelli - `codex/*` +- I percorsi Codex della famiglia OpenAI mantengono confini di plugin separati: + `openai-codex/*` appartiene al plugin OpenAI, mentre il plugin app-server + Codex incluso viene selezionato da `embeddedHarness.runtime: "codex"` o dai riferimenti legacy + al modello `codex/*` + +## Risoluzione dei problemi degli hook di runtime + +Se un plugin compare in `plugins list` ma gli effetti collaterali di `register(api)` o gli hook +non vengono eseguiti nel traffico live della chat, controlla prima questi punti: + +- Esegui `openclaw gateway status --deep --require-rpc` e conferma che l'URL, + il profilo, il percorso di configurazione e il processo del Gateway attivo siano quelli che stai modificando. +- Riavvia il Gateway live dopo modifiche a installazione/configurazione/codice del plugin. Nei + container wrapper, PID 1 potrebbe essere solo un supervisore; riavvia o invia un segnale al processo figlio + `openclaw gateway run`. +- Usa `openclaw plugins inspect --json` per confermare le registrazioni degli hook e la + diagnostica. Gli hook di conversazione non inclusi come `llm_input`, + `llm_output` e `agent_end` richiedono + `plugins.entries..hooks.allowConversationAccess=true`. +- Per il cambio di modello, preferisci `before_model_resolve`. Viene eseguito prima della risoluzione + del modello per i turni dell'agente; `llm_output` viene eseguito solo dopo che un tentativo di modello + produce output dell'assistente. +- Per avere prova del modello di sessione effettivo, usa `openclaw sessions` oppure le + superfici di sessione/stato del Gateway e, quando esegui il debug dei payload del provider, avvia + il Gateway con `--raw-stream --raw-stream-path `. ## Slot dei plugin (categorie esclusive) @@ -212,16 +244,16 @@ Alcune categorie sono esclusive (solo una attiva alla volta): plugins: { slots: { memory: "memory-core", // oppure "none" per disabilitare - contextEngine: "legacy", // oppure un id plugin + contextEngine: "legacy", // oppure un ID plugin }, }, } ``` -| Slot | Cosa controlla | Predefinito | -| --------------- | --------------------------- | ------------------- | -| `memory` | Plugin Active Memory | `memory-core` | -| `contextEngine` | Motore di contesto attivo | `legacy` (integrato) | +| Slot | Cosa controlla | Predefinito | +| --------------- | ------------------------- | ------------------- | +| `memory` | Plugin di memoria attiva | `memory-core` | +| `contextEngine` | Motore di contesto attivo | `legacy` (integrato) | ## Riferimento CLI @@ -229,26 +261,26 @@ Alcune categorie sono esclusive (solo una attiva alla volta): openclaw plugins list # inventario compatto openclaw plugins list --enabled # solo plugin caricati openclaw plugins list --verbose # righe di dettaglio per plugin -openclaw plugins list --json # inventario leggibile da macchina -openclaw plugins inspect # dettaglio approfondito -openclaw plugins inspect --json # leggibile da macchina -openclaw plugins inspect --all # tabella dell'intera flotta +openclaw plugins list --json # inventario leggibile dalle macchine +openclaw plugins inspect # dettagli approfonditi +openclaw plugins inspect --json # leggibile dalle macchine +openclaw plugins inspect --all # tabella dell'intero insieme openclaw plugins info # alias di inspect openclaw plugins doctor # diagnostica openclaw plugins install # installa (prima ClawHub, poi npm) openclaw plugins install clawhub: # installa solo da ClawHub openclaw plugins install --force # sovrascrive un'installazione esistente -openclaw plugins install # installa da un percorso locale +openclaw plugins install # installa da percorso locale openclaw plugins install -l # collega (senza copia) per sviluppo openclaw plugins install --marketplace openclaw plugins install --marketplace https://github.com// -openclaw plugins install --pin # registra la specifica npm risolta esatta +openclaw plugins install --pin # registra la specifica npm esatta risolta openclaw plugins install --dangerously-force-unsafe-install openclaw plugins update # aggiorna un plugin openclaw plugins update --dangerously-force-unsafe-install openclaw plugins update --all # aggiorna tutti -openclaw plugins uninstall # rimuove i record di configurazione/installazione +openclaw plugins uninstall # rimuove record di configurazione/installazione openclaw plugins uninstall --keep-files openclaw plugins marketplace list openclaw plugins marketplace list --json @@ -257,59 +289,59 @@ openclaw plugins enable openclaw plugins disable ``` -I plugin inclusi vengono distribuiti con OpenClaw. Molti sono abilitati per impostazione predefinita (ad esempio +I plugin inclusi vengono forniti con OpenClaw. Molti sono abilitati per impostazione predefinita (ad esempio i provider di modelli inclusi, i provider vocali inclusi e il plugin browser incluso). Altri plugin inclusi richiedono comunque `openclaw plugins enable `. -`--force` sovrascrive sul posto un plugin installato o un hook pack esistente. Usa -`openclaw plugins update ` per gli aggiornamenti ordinari dei plugin npm -tracciati. Non è supportato con `--link`, che riutilizza il percorso sorgente invece -di copiare su una destinazione di installazione gestita. +`--force` sovrascrive sul posto un plugin o hook pack già installato. Usa +`openclaw plugins update ` per gli aggiornamenti ordinari dei plugin +npm tracciati. Non è supportato con `--link`, che riutilizza il percorso sorgente invece +di copiare in una destinazione di installazione gestita. -Quando `plugins.allow` è già impostato, `openclaw plugins install` aggiunge l'id del plugin -installato a quella allowlist prima di abilitarlo, così le installazioni sono +Quando `plugins.allow` è già impostato, `openclaw plugins install` aggiunge l'ID del +plugin installato a quella allowlist prima di abilitarlo, così le installazioni sono immediatamente caricabili dopo il riavvio. `openclaw plugins update ` si applica alle installazioni tracciate. Passare -una specifica di pacchetto npm con un dist-tag o una versione esatta risolve il nome del pacchetto -fino al record del plugin tracciato e registra la nuova specifica per gli aggiornamenti futuri. -Passare il nome del pacchetto senza una versione riporta un'installazione esatta fissata -alla linea di rilascio predefinita del registro. Se il plugin npm installato corrisponde già +una specifica di package npm con un dist-tag o una versione esatta risolve il nome del package +risalendo al record del plugin tracciato e registra la nuova specifica per aggiornamenti futuri. +Passare il nome del package senza una versione riporta un'installazione bloccata a una versione esatta +alla linea di release predefinita del registro. Se il plugin npm installato corrisponde già alla versione risolta e all'identità dell'artefatto registrata, OpenClaw salta l'aggiornamento senza scaricare, reinstallare o riscrivere la configurazione. `--pin` è solo per npm. Non è supportato con `--marketplace`, perché -le installazioni dal marketplace mantengono metadati della sorgente marketplace invece di una specifica npm. +le installazioni dal marketplace mantengono i metadati della sorgente del marketplace invece di una specifica npm. `--dangerously-force-unsafe-install` è un override di emergenza per i falsi positivi dello scanner integrato di codice pericoloso. Consente alle installazioni -e agli aggiornamenti dei plugin di proseguire oltre i rilevamenti integrati `critical`, ma comunque -non aggira i blocchi di policy `before_install` del plugin né il blocco dovuto al fallimento della scansione. +e agli aggiornamenti dei plugin di proseguire oltre i risultati integrati `critical`, ma comunque +non aggira i blocchi di policy `before_install` del plugin né il blocco dovuto a errori di scansione. -Questo flag CLI si applica solo ai flussi di installazione/aggiornamento dei plugin. Le installazioni -di dipendenze delle Skills supportate dal Gateway usano invece il corrispondente override di richiesta -`dangerouslyForceUnsafeInstall`, mentre `openclaw skills install` resta il flusso separato di download/installazione delle Skills da ClawHub. +Questo flag CLI si applica solo ai flussi di installazione/aggiornamento dei plugin. Le +installazioni di dipendenze delle Skills supportate dal Gateway usano invece l'override corrispondente della richiesta +`dangerouslyForceUnsafeInstall`, mentre `openclaw skills install` resta il flusso separato di download/installazione +delle Skills da ClawHub. -I bundle compatibili partecipano allo stesso flusso di elenco/ispezione/abilitazione/disabilitazione -dei plugin. Il supporto runtime attuale include bundle Skills, command-skills di Claude, -impostazioni predefinite di Claude `settings.json`, impostazioni predefinite di Claude `.lsp.json` e -`lspServers` dichiarati nel manifest, command-skills di Cursor e directory hook -Codex compatibili. +I bundle compatibili partecipano allo stesso flusso di elenco/ispezione/abilitazione/disabilitazione dei plugin. +Il supporto runtime attuale include bundle Skills, command-skills di Claude, +impostazioni predefinite di Claude `settings.json`, valori predefiniti di Claude `.lsp.json` e `lspServers` +dichiarati nel manifest, command-skills di Cursor e directory hook Codex compatibili. -`openclaw plugins inspect ` riporta anche le capacità del bundle rilevate, oltre alle -voci di server MCP e LSP supportate o non supportate per i plugin basati su bundle. +`openclaw plugins inspect ` riporta anche le capacità del bundle rilevate, oltre alle voci +MCP e server LSP supportate o non supportate per i plugin basati su bundle. -Le sorgenti del marketplace possono essere un nome di marketplace noto di Claude da -`~/.claude/plugins/known_marketplaces.json`, una root di marketplace locale o un -percorso `marketplace.json`, una forma abbreviata GitHub come `owner/repo`, un URL -di repository GitHub oppure un URL git. Per i marketplace remoti, le voci dei plugin devono -rimanere all'interno del repository marketplace clonato e usare solo sorgenti con percorso relativo. +Le sorgenti marketplace possono essere un nome di marketplace noto di Claude da +`~/.claude/plugins/known_marketplaces.json`, una root di marketplace locale o un percorso +`marketplace.json`, una forma abbreviata GitHub come `owner/repo`, un URL di repository GitHub +oppure un URL git. Per i marketplace remoti, le voci plugin devono restare all'interno del +repository marketplace clonato e usare solo sorgenti di percorso relative. Vedi il [riferimento CLI di `openclaw plugins`](/it/cli/plugins) per tutti i dettagli. ## Panoramica dell'API dei plugin -I plugin nativi esportano un oggetto entry che espone `register(api)`. I plugin meno recenti +I plugin nativi esportano un oggetto entry che espone `register(api)`. I plugin più vecchi possono ancora usare `activate(api)` come alias legacy, ma i nuovi plugin dovrebbero usare `register`. @@ -333,24 +365,23 @@ export default definePluginEntry({ OpenClaw carica l'oggetto entry e chiama `register(api)` durante l'attivazione del plugin. Il loader continua a usare `activate(api)` come fallback per i plugin più vecchi, -ma i plugin inclusi e i nuovi plugin esterni dovrebbero considerare `register` come -contratto pubblico. +ma i plugin inclusi e i nuovi plugin esterni dovrebbero trattare `register` come contratto pubblico. Metodi di registrazione comuni: | Metodo | Cosa registra | | --------------------------------------- | --------------------------- | | `registerProvider` | Provider di modelli (LLM) | -| `registerChannel` | Canale di chat | -| `registerTool` | Strumento dell'agente | +| `registerChannel` | Canale chat | +| `registerTool` | Strumento agente | | `registerHook` / `on(...)` | Hook del ciclo di vita | | `registerSpeechProvider` | Sintesi vocale / STT | | `registerRealtimeTranscriptionProvider` | STT in streaming | -| `registerRealtimeVoiceProvider` | Voce duplex in tempo reale | +| `registerRealtimeVoiceProvider` | Voce realtime duplex | | `registerMediaUnderstandingProvider` | Analisi di immagini/audio | | `registerImageGenerationProvider` | Generazione di immagini | | `registerMusicGenerationProvider` | Generazione musicale | -| `registerVideoGenerationProvider` | Generazione video | +| `registerVideoGenerationProvider` | Generazione di video | | `registerWebFetchProvider` | Provider di recupero / scraping web | | `registerWebSearchProvider` | Ricerca web | | `registerHttpRoute` | Endpoint HTTP | @@ -358,22 +389,22 @@ Metodi di registrazione comuni: | `registerContextEngine` | Motore di contesto | | `registerService` | Servizio in background | -Comportamento delle guardie hook per gli hook tipizzati del ciclo di vita: +Comportamento delle guardie hook per hook del ciclo di vita tipizzati: - `before_tool_call`: `{ block: true }` è terminale; gli handler con priorità inferiore vengono saltati. - `before_tool_call`: `{ block: false }` non ha effetto e non annulla un blocco precedente. - `before_install`: `{ block: true }` è terminale; gli handler con priorità inferiore vengono saltati. - `before_install`: `{ block: false }` non ha effetto e non annulla un blocco precedente. - `message_sending`: `{ cancel: true }` è terminale; gli handler con priorità inferiore vengono saltati. -- `message_sending`: `{ cancel: false }` non ha effetto e non annulla una cancellazione precedente. +- `message_sending`: `{ cancel: false }` non ha effetto e non annulla una precedente cancellazione. Per il comportamento completo degli hook tipizzati, vedi [Panoramica SDK](/it/plugins/sdk-overview#hook-decision-semantics). ## Correlati -- [Building Plugins](/it/plugins/building-plugins) — crea il tuo plugin -- [Plugin Bundles](/it/plugins/bundles) — compatibilità bundle Codex/Claude/Cursor -- [Plugin Manifest](/it/plugins/manifest) — schema del manifest -- [Registering Tools](/it/plugins/building-plugins#registering-agent-tools) — aggiungi strumenti dell'agente in un plugin -- [Plugin Internals](/it/plugins/architecture) — modello delle capacità e pipeline di caricamento -- [Community Plugins](/it/plugins/community) — elenchi di terze parti +- [Creare plugin](/it/plugins/building-plugins) — crea il tuo plugin +- [Bundle di plugin](/it/plugins/bundles) — compatibilità bundle Codex/Claude/Cursor +- [Manifest del plugin](/it/plugins/manifest) — schema del manifest +- [Registrazione degli strumenti](/it/plugins/building-plugins#registering-agent-tools) — aggiungi strumenti agente in un plugin +- [Componenti interni dei plugin](/it/plugins/architecture) — modello di capacità e pipeline di caricamento +- [Plugin della community](/it/plugins/community) — elenchi di terze parti